Documentation

Batch Engine APIの基本 - データのエクスポート

LiferayのHeadless Batch Engineは、データのインポートとエクスポートを行うためのREST APIを提供しています。 これらのサービスを呼び出して、Liferayからデータをエクスポートします。

データのエクスポート

新しいLiferay DXPインスタンスを起動し、以下を実行します。

docker run -it -m 8g -p 8080:8080 liferay/dxp:7.4.13-u29。

メールアドレス_test@liferay.com_とパスワード_test_を使用して、http://localhost:8080でLiferayにサインインしてください。 プロンプトが表示されたら、パスワードを _learn_に変更します。

次に、以下の手順を実行します。

  1. Batch Engine API Basics をダウンロードし、解凍してください。

    curl https://learn.liferay.com/dxp/latest/ja/headless-delivery/consuming-apis/liferay-g4j2.zip -O
    
    unzip liferay-g4j2.zip
    
  2. データをエクスポートするには、エクスポートするエンティティの完全修飾クラス名が必要です。 クラス名は、インストールされているAPIエクスプローラから、 /o/apiで取得することができます。 Schemas セクションまでスクロールダウンし、エクスポートしたいエンティティの x-class-name フィールドをメモしておきます。

  3. 以下のcURLスクリプトを使用して、Liferayインスタンスからアカウントをエクスポートします。 コマンドラインで、 curl フォルダに移動します。 ExportTask_POST_ToInstance.sh スクリプトを、完全修飾クラス名 Account および json をパラメータとして実行します。 json パラメータは、エクスポートされるデータの形式を示します。 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
    }
    

    重要

    出力フォーマットに json または jsonl を使用した場合、デフォルトですべてのフィールドがエクスポートされます。 フィールドを指定するには、エクスポートしたいフィールドを追加のクエリパラメータ (fieldNames) で指定する必要があります。 各項目はカンマ(,)で区切る必要があります。 エクスポートフォーマットとして csv を使用する場合、これは必須のクエリパラメータである。

  4. 現在の executeStatusINITIALです。 Batch Engineへのタスク投入を表す。 これが 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
    }
    

    executeStatusCOMPLETEDであれば、エクスポートされたデータをダウンロードすることができます。 そうでない場合は、再度コマンドを実行し、タスクの実行が終了したことを確認します。 executeStatusFAILEDを示している場合、何が問題だったのかを理解するために errorMessage フィールドをチェックしてください。

  5. executeStatusCOMPLETEDになったら、 ExportTaskContent_GET_ById.sh スクリプトを実行して 1234 をエクスポートタスクの ID に置き換えると、エクスポートしたデータをダウンロードすることができ ます。

    ./ExportTaskContent_GET_ById.sh 1234
    

    これは、エクスポートされたデータを .zip ファイルとして、カレントディレクトリにダウンロードします。 それを取り出し、適切なアプリケーションを使用してデータを表示する。

  6. また、Javaクライアントを使用して、The RESTサービスを呼び出すこともできます。 curl フォルダから、 java フォルダに移動します。 ソースファイルをコンパイルします。

    javac -classpath .:* *.java
    
  7. ExportTask_POST_ToInstance クラスを実行します。 able をクラスの完全修飾名に置き換えてください。

    java -classpath .:* -DclassName=able ExportTask_POST_ToInstance
    

    例えば、 アカウント のデータをエクスポートします。

    java -classpath .:* -DclassName=com.liferay.headless.admin.user.dto.v1_0.Account ExportTask_POST_ToInstance
    

    JSONレスポンスからエクスポートタスクの id に注目してください。

  8. ExportTask_GET_ById クラスを、以下のコマンドで実行します。 1234 をエクスポートタスクのIDに置き換えてください。

    java -classpath .:* -DexportTaskId=1234 ExportTask_GET_ById
    
  9. executeStatusCOMPLETEDを示したら、 ExportTaskContent_GET_ById クラスを実行して、データをダウンロードすることができます。 1234 をエクスポートタスクのIDに置き換えてください。

    java -classpath .:* -DexportTaskId=1234 ExportTaskContent_GET_ById
    

cURLコマンドの検証

ExportTask_POST_ToInstance.sh スクリプトは、cURL コマンドで REST サービスを呼び出します。

curl \
	 -H "Content-Type: application/json" \
	 -X POST \
	 "http://localhost:8080/o/headless-batch-engine/v1.0/export-task/${1}/${2}" \
	 -u "[email protected]: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"

基本的な認証情報

注釈

ここでは、デモのために基本認証を使用しています。 本番環境では、 OAuth2 経由でユーザーを認可する必要があります。

Javaクラスを調べる

ExportTask_POST_ToInstance.java クラスは、Batch Engine 関連サービスを呼び出すことでデータをエクスポートします。

public static void main(String[] args) throws Exception {
	ExportTaskResource.Builder builder = ExportTaskResource.builder();

	ExportTaskResource exportTaskResource = builder.authentication(
		"[email protected]", "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依存関係情報は、/o/apiでインストール先のAPIエクスプローラーで確認できます。

注釈

mainメソッドのコメントでは、クラスの実行を実演しています。

他のサンプルのJavaクラスは、これと似ていますが、異なる ExportTaskResource メソッドを呼び出します。

重要

サービスの詳細は ExportTaskResource を参照ください。

以下は、cURLとJavaを使用して、他のBatch Engineエクスポート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}" \
	 -u "[email protected]: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(
		"[email protected]", "learn"
	).build();

	System.out.println(
		exportTaskResource.getExportTask(
			Long.valueOf(System.getProperty("exportTaskId"))));
}

サイトからのデータのエクスポート

以下のcURLまたはJavaコマンドを実行することで、サイトからデータをエクスポートすることができます。 以下の例では、あるサイトからブログ記事をエクスポートしています。 あなたのサイトのID を探し、 1234 をそれに置き換えてください。 別のエンティティを使用する場合は、cURLスクリプトの完全修飾クラス名パラメータも更新する必要があります。

ExportTask_POST_ToSite.sh

コマンド:

./ExportTask_POST_ToSite.sh com.liferay.headless.delivery.dto.v1_0.BlogPosting json 1234

コード:

curl \
	 -H "Content-Type: application/json" \
	 -X POST \
	 "http://localhost:8080/o/headless-batch-engine/v1.0/export-task/${1}/${2}?siteId=${3}" \
	 -u "[email protected]: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(
		"[email protected]", "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 で、エクスポートされるデータの出力形式を表す。 また、ここでは jsonlcsv を使用することができる。 CSVを利用する場合は、エクスポートしたいフィールドをカンマ区切りの文字列で指定し、 exportTaskResource.postExportTask() メソッドの5番目のパラメータとして渡すことが必須となります。

JSONレスポンスには、新しく作成されたエクスポートタスクの情報が表示されます。 id に注意して、その executeStatusを追跡してください。 完了後、 ExportTaskContent_GET_ById.[java|sh] をエクスポートタスクIDで実行すると、データをダウンロードすることができます。

エクスポートされたデータの内容を取得する

エクスポートされたデータは、以下の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" \
	 -o file.zip \
	 -u "[email protected]: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(
		"[email protected]", "learn"
	).build();

	HttpInvoker.HttpResponse httpResponse =
		exportTaskResource.getExportTaskContentHttpResponse(
			Long.valueOf(System.getProperty("exportTaskId")));

	try (FileOutputStream fileOutputStream = new FileOutputStream(
			"file.zip")) {

		fileOutputStream.write(httpResponse.getBinaryContent());
	}
}

API Explorer には、Headless Batch Engine の全サービスとスキーマがリストアップされており、各サービスを試すためのインターフェイスが用意されています。

追加情報