バッチエンジンAPIの基本 - データのエクスポート
Liferayのヘッドレスバッチエンジンは、データのインポートやエクスポートを行うためのREST APIを提供します。 これらのサービスを呼び出して、Liferayにデータをエクスポートします。
データのエクスポート
新しいLiferay DXPインスタンスを起動し、以下を実行します。
docker run -it -m 8g -p 8080:8080 liferay/dxp:2024.q1.1。
メールアドレス test@liferay.com とパスワード test を使用して、http://localhost:8080でLiferayにサインインしてください。 プロンプトが表示されたら、パスワードを learn に変更します。
次に、以下の手順に従います。
-
Batch Engine API Basics をダウンロードして解凍する。
curl https://resources.learn.liferay.com/dxp/latest/en/headless-delivery/consuming-apis/liferay-g4j2.zip -O
unzip liferay-g4j2.zip
-
データをエクスポートするには、エクスポートするエンティティの完全修飾クラス名が必要です。 クラス名は、インストールされているAPI Explorerの
/o/api
から取得できる。 スキーマ セクションまでスクロールダウンし、エクスポートしたいエンティティのx-class-name
フィールドをメモする。 -
以下のcURLスクリプトを使用して、Liferayインスタンスからアカウントをエクスポートします。 コマンドラインで
curl
フォルダに移動します。ExportTask_POST_ToInstance.sh
スクリプトを、完全修飾クラス名 Account とjson
をパラメータとして実行する。 jsonパラメータはエクスポートされるデータのフォーマットを示す。 また、
jsont、
jsonl、
csv`形式もサポートしている。./ExportTask_POST_ToInstance.sh com.liferay.headless.admin.user.dto.v1_0.Account json
JSON応答は、新規エクスポートタスクの作成を示しています。 タスクの
id
に注意:{ "className" : "com.liferay.headless.admin.user.dto.v1_0.Account", "contentType" : "JSON", "errorMessage" : "", "executeStatus" : "INITIAL", "externalReferenceCode" : "6c5286a2-aa28-175b-041e-eacca4a54d3b", "id" : 1234, "processedItemsCount" : 0, "totalItemsCount" : 0 }
importantjsont
は、バッチクライアント拡張と組み合わせて使用する場合、*.batch-engine-dat.json
ファイルの必須フォーマットです。出力形式として
json
またはjsonl
を使用する場合、デフォルトですべてのフィールドがエクスポートされます。 フィールドを指定するには、エクスポートしたいフィールドを追加のクエリパラメータ(fieldNames
)で指定する必要があります。 各フィールドはカンマ(,)で区切る必要があります。 エクスポート形式としてcsv
を使用する場合、これは必須のクエリパラメーターとなります。 -
現在の
executeStatus
はINITIAL
である。 バッチエンジンへのタスクの送信を示します。 データをダウンロードするには、COMPLETED
になるまで待たなければならない。 コマンドラインでExportTask_GET_ById.sh
スクリプトを実行し、1234
をエクスポートタスクのIDに置き換える。./ExportTask_GET_ById.sh 1234
{ "className" : "com.liferay.headless.admin.user.dto.v1_0.Account", "contentType" : "JSON", "endTime" : "2022-10-19T14:13:58Z", "errorMessage" : "", "executeStatus" : "COMPLETED", "externalReferenceCode" : "6c5286a2-aa28-175b-041e-eacca4a54d3b", "id" : 1234, "processedItemsCount" : 8, "startTime" : "2022-10-19T14:13:58Z", "totalItemsCount" : 8 }
executeStatus
がCOMPLETED
の場合、エクスポートしたデータをダウンロードできる。 実行されていない場合は、再度コマンドを実行し、タスクの実行が終了したことを確認します。 もしexecuteStatus
がFAILED
と表示されたら、errorMessage
フィールドをチェックして、何が問題だったのかを理解する。 -
executeStatus
がCOMPLETED
になったら、ExportTaskContent_GET_ById.sh
スクリプトを実行し、1234
をエクスポートタスクのIDに置き換えることで、エクスポートしたデータをダウンロードすることができる。./ExportTaskContent_GET_ById.sh 1234
これはエクスポートされたデータを
.zip
ファイルとしてカレントディレクトリにダウンロードする。 ZIPファイルを展開し、適切なアプリケーションを使用してデータを表示します。 -
また、Javaクライアントを使用してThe RESTサービスを呼び出すことができます。 curl
フォルダから
java` フォルダに移動します。 ソースファイルをコンパイルします。javac -classpath .:* *.java
-
ExportTask_POST_ToInstance
クラスを実行する。 able`をクラスの完全修飾名に置き換える。java -classpath .:* -DclassName=able ExportTask_POST_ToInstance
例えば、
Account
データをエクスポートします:java -classpath .:* -DclassName=com.liferay.headless.admin.user.dto.v1_0.Account ExportTask_POST_ToInstance
JSONレスポンスからエクスポートタスクの
id
に注目する。 -
次のコマンドで
ExportTask_GET_ById
クラスを実行する。1234
をエクスポートタスクのIDに置き換えてください。java -classpath .:* -DexportTaskId=1234 ExportTask_GET_ById
-
executeStatus
にCOMPLETED
と表示されたら、ExportTaskContent_GET_ById
クラスを実行してデータをダウンロードすることができる。 1234`をエクスポートタスクのIDに置き換えてください。java -classpath .:* -DexportTaskId=1234 ExportTaskContent_GET_ById
cURLコマンドの検証
ExportTask_POST_ToInstance.sh
スクリプトは、cURLコマンドでRESTサービスを呼び出す。
curl \
"http://localhost:8080/o/headless-batch-engine/v1.0/export-task/${1}/${2}" \
--header "Content-Type: application/json" \
--request "POST" \
--user "test@liferay.com:learn"
ここでは、コマンドの引数を紹介します。
引数 | 説明 |
---|---|
-H "Content-Type: application/json" | リクエストボディのフォーマットがJSONであることを示します。 |
-X POST | 指定されたエンドポイントで起動するHTTPメソッド |
"http://localhost:8080/o/headless-batch-engine/v1.0/export-task/${1}/${2}" | RESTサービスのエンドポイント |
-u "test@liferay.com:learn" | 基本的な認証情報 |
ここでは、デモのために基本的な認証を使用しています。 本番環境では、 OAuth 2.0を使用する を介してユーザーを認証する必要があります。 Oauth2 を使用する React アプリケーションのサンプルについては、 OAuth2によるユーザーの認証 を参照してください。
Javaクラスを調べる
ExportTask_POST_ToInstance.java
クラスは、バッチエンジン関連のサービスを呼び出してデータをエクスポートする。
public static void main(String[] args) throws Exception {
ExportTaskResource.Builder builder = ExportTaskResource.builder();
ExportTaskResource exportTaskResource = builder.authentication(
"test@liferay.com", "learn"
).build();
ExportTask exportTask = exportTaskResource.postExportTask(
String.valueOf(System.getProperty("className")), "json", null, null,
null, "");
System.out.println(exportTask);
}
このクラスは、わずか3行のコードでRESTサービスを呼び出します。
行(省略形) | 説明 |
---|---|
ExportTaskResource.Builder builder = ... | ExportTaskResource サービスインスタンスを生成するためのBuilder を取得する。 |
ExportTaskResource exportTaskResource = builder.authentication(...).build(); | 基本認証を指定し、ExportTaskResource サービスインスタンスを生成する。 |
exportTaskResource.postExportTask(...); | exportTaskResource.postExportTask メソッドを呼び出し、データをpostに渡す。 |
このプロジェクトには com.liferay.headless.batch.engine.client.jar
ファイルが依存関係として含まれていることに注意してください。 すべての REST アプリケーションのクライアント JAR 依存情報は、インストー ルの API エクスプローラーの /o/api
にある。
main
メソッドのコメントは、クラスの実行を示している。
他のJavaクラスの例もこれと似ているが、異なる ExportTaskResource
メソッドを呼び出している。
サービスの詳細については、 ExportTaskResource を参照してください。
以下は、cURLとJavaを使用して他のBatch Engine export RESTサービスを呼び出す例です。
ExportTaskのステータスを取得する
以下のcURLまたはJavaコマンドを実行することで、エクスポートタスクのステータスを取得することができます。 1234
をエクスポートタスクのIDに置き換えてください。
ExportTask_GET_ById.sh
コマンド:
./ExportTask_GET_ById.sh 1234
コード:
curl \
"http://localhost:8080/o/headless-batch-engine/v1.0/export-task/${1}" \
--user "test@liferay.com:learn"
ExportTask_GET_ById.java
ExportTask_GET_ById
クラスを実行する。 1234
をエクスポートタスクのIDに置き換えてください。
コマンド:
java -classpath .:* -DexportTaskId=1234 ExportTask_GET_ById
コード:
public static void main(String[] args) throws Exception {
ExportTaskResource.Builder builder = ExportTaskResource.builder();
ExportTaskResource exportTaskResource = builder.authentication(
"test@liferay.com", "learn"
).build();
System.out.println(
exportTaskResource.getExportTask(
Long.valueOf(System.getProperty("exportTaskId"))));
}
データをサイトからエクスポートする
以下のcURLまたはJavaコマンドを実行して、サイトからデータをエクスポートできます。 以下の例では、あるサイトからブログ記事をエクスポートしています。 RESTサービスの使用 を探し、1234
を置き換えてください。 別のエンティティを使用する場合は、cURLスクリプトの完全修飾クラス名パラメーターも更新する必要があります。
ExportTask_POST_ToSite.sh
コマンド:
./ExportTask_POST_ToSite.sh com.liferay.headless.delivery.dto.v1_0.BlogPosting json 1234
コード:
curl \
"http://localhost:8080/o/headless-batch-engine/v1.0/export-task/${1}/${2}?siteId=${3}" \
--header "Content-Type: application/json" \
--request "POST" \
--user "test@liferay.com:learn"
ExportTask_POST_ToSite.java
ExportTask_POST_ToSite
クラスを実行する。 1234をあなたのサイトのIDに、
able`をエクスポートしたいクラスの完全修飾名に置き換えてください:
java -classpath .:* -DsiteId=1234 -DclassName=able ExportTask_POST_ToSite
例えば、BlogPosting
データをエクスポートする:
java -classpath .:* -DsiteId=1234 -DclassName=com.liferay.headless.delivery.dto.v1_0.BlogPosting ExportTask_POST_ToSite
コード:
public static void main(String[] args) throws Exception {
ExportTaskResource.Builder builder = ExportTaskResource.builder();
ExportTaskResource exportTaskResource = builder.authentication(
"test@liferay.com", "learn"
).parameter(
"siteId", String.valueOf(System.getProperty("siteId"))
).build();
ExportTask exportTask = exportTaskResource.postExportTask(
String.valueOf(System.getProperty("className")), "json", null, null,
null, "");
System.out.println(exportTask);
}
第2パラメータは json
で、エクスポートされたデータの出力形式を表示します。 ここでは jsonl
と csv
を使用することもできます。 CSVを使用する場合は、エクスポートしたいフィールドをカンマ区切りの文字列で指定し、exportTaskResource.postExportTask()
メソッドの第5パラメータとして渡すことが必須です。
JSON応答には、新しく作成されたエクスポートタスクの情報が表示されます。 その executeStatus
を追跡するために id
に注意すること。 完了したら、エクスポートタスクIDを指定してExportTaskContent_GET_ById.[java|sh]
を実行し、データをダウンロードすることができる。
エクスポートデータの内容を取得する
エクスポートしたデータは、以下のcURLコマンドとJavaコマンドでダウンロードできます。 1234
をエクスポートタスクのIDに置き換える。 その後、カレントディレクトリに.zip
ファイルとしてダウンロードされる。
ExportTaskContent_GET_ById.sh
コマンド:
./ExportTaskContent_GET_ById.sh 1234
コード:
curl \
"http://localhost:8080/o/headless-batch-engine/v1.0/export-task/${1}/content" \
--output file.zip \
--user "test@liferay.com:learn"
ExportTaskContent_GET_ById.java
コマンド
java -classpath .:* -DexportTaskId=1234 ExportTaskContent_GET_ById
コード:
public static void main(String[] args) throws Exception {
ExportTaskResource.Builder builder = ExportTaskResource.builder();
ExportTaskResource exportTaskResource = builder.authentication(
"test@liferay.com", "learn"
).build();
HttpInvoker.HttpResponse httpResponse =
exportTaskResource.getExportTaskContentHttpResponse(
Long.valueOf(System.getProperty("exportTaskId")));
try (FileOutputStream fileOutputStream = new FileOutputStream(
"file.zip")) {
fileOutputStream.write(httpResponse.getBinaryContent());
}
}
RESTサービスの使用 には、ヘッドレスバッチエンジンの全サービスとスキーマが一覧表示され、各サービスを試すためのインターフェースがあります。