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 フォルダに移動します。 ImportTask_POST_ToInstance.sh スクリプトを、完全修飾クラス名 Account をパラメータとして実行します。

    ./ImportTask_POST_ToInstance.sh com.liferay.headless.admin.user.dto.v1_0.Account
    

    JSONレスポンスには、新しいインポートタスクの作成が表示されます。 タスクの id に注意してください。

    {
    "className" : "com.liferay.headless.admin.user.dto.v1_0.Account",
    "contentType" : "JSON",
    "errorMessage" : "",
    "executeStatus" : "INITIAL",
    "externalReferenceCode" : "4a6ab4b0-12cc-e8e3-fc1a-4726ebc09df2",
    "failedItems" : [ ],
    "id" : 1234,
    "importStrategy" : "ON_ERROR_FAIL",
    "operation" : "CREATE",
    "processedItemsCount" : 0,
    "startTime" : "2022-10-19T14:19:43Z",
    "totalItemsCount" : 0
    }
    
  4. 現在の executeStatusINITIALです。 Batch Engineへのタスク投入を表す。 これが COMPLETED になるまで待って、データを確認する必要があります。 コマンドラインで、 ImportTask_GET_ById.sh スクリプトを実行し、 1234 をインポートタスクのIDに置き換えます。

    ./ImportTask_GET_ById.sh 1234
    
    {
    "className" : "com.liferay.headless.admin.user.dto.v1_0.Account",
    "contentType" : "JSON",
    "endTime" : "2022-10-19T12:18:59Z",
    "errorMessage" : "",
    "executeStatus" : "COMPLETED",
    "externalReferenceCode" : "7d256faa-9b7e-9589-e85c-3a72f68b8f08",
    "failedItems" : [ ],
    "id" : 1234,
    "importStrategy" : "ON_ERROR_FAIL",
    "operation" : "CREATE",
    "processedItemsCount" : 2,
    "startTime" : "2022-10-19T12:18:58Z",
    "totalItemsCount" : 2
    }
    

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

  5. グローバルメニュー(Applications Menu icon) を開き、 コントロールパネルアカウント に移動して、インポートしたデータを確認します。 2つの新しいアカウントが追加されていることを確認します。

    2つの新しいアカウントが追加されたことを確認します。

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

    javac -classpath .:* *.java
    
  7. ImportTask_POST_ToInstance クラスを実行します。 able をクラスの完全修飾名に、 baker をインポートしたい JSON データに置き換えてください。

    java -classpath .:* -DclassName=able -Ddata=baker ImportTask_POST_ToInstance
    

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

    java -classpath .:* -DclassName=com.liferay.headless.admin.user.dto.v1_0.Account -Ddata="[{\"name\": \"Able\", \"type\": \"business\"}, {\"name\": \"Baker\", \"type\": \"guest\"}]" ImportTask_POST_ToInstance
    

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

  8. ImportTask_GET_ById クラスを実行します。 1234 をインポートタスクのIDに置き換えてください。 executeStatusCOMPLETEDと表示されたら、上記の手順でデータを確認することができます。

    java -cp .:* -DimportTaskId=1234 ImportTask_GET_ById
    

cURLコマンドの検証

ImportTask_POST_ToInstance.sh スクリプトは、cURL を使用して REST サービスを呼び出します。

curl \
	 -H "Content-Type: application/json" \
	 -X POST \
	 "http://localhost:8080/o/headless-batch-engine/v1.0/import-task/${1}" \
	 -d "[{\"name\": \"Able\", \"type\": \"business\"}, {\"name\": \"Baker\", \"type\": \"guest\"}]" \
	 -u "[email protected]:learn"

ここでは、コマンドの引数を紹介します。

引数

説明

-H "Content-Type: application/json"

リクエストボディのフォーマットがJSONであることを示します。

-X POST

指定されたエンドポイントで起動するHTTPメソッド

"http://localhost:8080/o/headless-batch-engine/v1.0/import-task/${1}"

RESTサービスのエンドポイント

-d "[{\"name\": \"Able\", \"type\": \"business\"}, {\"name\": \"Baker\", \"type\": \"guest\"}]"

お客様が掲載を希望するデータ

-u "test@liferay.com:learn"

基本的な認証情報

注釈

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

他のcURLコマンドも同様のJSON引数を使用しています。

Javaクラスを調べる

ImportTask_POST_ToInstance.java クラスは、Batch Engine 関連サービスを呼び出してデータを取り込みます。

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

	ImportTaskResource importTaskResource = builder.authentication(
		"[email protected]", "learn"
	).build();

	System.out.println(
		importTaskResource.postImportTask(
			String.valueOf(System.getProperty("className")), null, null,
			null, null, null, null,
			String.valueOf(System.getProperty("data"))));
}

このクラスは、次の3行のコードのみを使用してRESTサービスを呼び出します。

行(省略)

説明

ImportTaskResource.Builder builder = ...

ImportTaskResource サービスインスタンスを生成するための Builder を取得します。

ImportTaskResource importTaskResource = builder.authentication(...).build();

基本認証を指定して、ImportTaskResource サービスインスタンスを生成します。

importTaskResource.postImportTask(...);

importTaskResource.postImportTask メソッドを呼び出して、データを post に渡します。

                                                                                                                                    |

プロジェクトには、依存関係としてcom.liferay.headless.batch.engine.client.jarファイルが含まれていることに注意してください。 すべてのRESTアプリケーションのクライアントJAR依存関係情報は、/o/apiでインストール先のAPIエクスプローラーで確認できます。

注釈

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

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

重要

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

以下は、cURLとJavaを使用して他のBatch EngineインポートRESTサービスを呼び出す例です。

ImportTaskのステータスを取得します。

以下のcURLまたはJavaコマンドを実行することで、インポートタスクのステータスを取得することができます。 1234 をインポートタスクのIDに置き換えてください。

ImportTask_GET_ById.sh

コマンド:

./ImportTask_GET_ById.sh 1234

コード:

curl \
	 "http://localhost:8080/o/headless-batch-engine/v1.0/import-task/${1}" \
	 -u "[email protected]:learn"

ImportTask_GET_ById.java

ImportTask_GET_ById クラスを実行します。 1234 をインポートタスクのIDに置き換えてください。

コマンド:

java -classpath .:* -DimportTaskId=1234 ImportTask_GET_ById

コード:

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

	ImportTaskResource importTaskResource = builder.authentication(
		"[email protected]", "learn"
	).build();

	System.out.println(
		importTaskResource.getImportTask(
			Long.valueOf(System.getProperty("importTaskId"))));
}

サイトへのデータ取り込み

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

ImportTask_POST_ToSite.sh

コマンド:

./ImportTask_POST_ToSite.sh com.liferay.headless.delivery.dto.v1_0.BlogPosting 1234

コード:

curl \
	 -H "Content-Type: application/json" \
	 -X POST \
	 "http://localhost:8080/o/headless-batch-engine/v1.0/import-task/${1}?siteId=${2}" \
	 -d "[{\"articleBody\": \"Foo\", \"headline\": \"Able\"}, {\"articleBody\": \"Bar\", \"headline\": \"Baker\"}]" \
	 -u "[email protected]:learn"

ImportTask_POST_ToSite.java

ImportTask_POST_ToSite クラスを実行します。 1234 をサイトの ID、 able をクラスの完全修飾名、 baker をインポートしたい JSON データに置き換えてください。

コマンド:

java -classpath .:* -DsiteId=1234 -DclassName=able -Ddata=baker ImportTask_POST_ToSite

例えば、 BlogPosting のデータをインポートします。

java -classpath .:* -DsiteId=1234 -DclassName=com.liferay.headless.delivery.dto.v1_0.BlogPosting -Ddata="[{\"articleBody\": \"Foo\", \"headline\": \"Able\"}, {\"articleBody\": \"Bar\", \"headline\": \"Baker\"}]" ImportTask_POST_ToSite

コード:

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

	ImportTaskResource importTaskResource = builder.authentication(
		"[email protected]", "learn"
	).parameter(
		"siteId", String.valueOf(System.getProperty("siteId"))
	).build();

	System.out.println(
		importTaskResource.postImportTask(
			String.valueOf(System.getProperty("className")), null, null,
			null, null, null, null,
			String.valueOf(System.getProperty("data"))));
}

JSONレスポンスには、新しく作成されたインポートタスクの情報が表示されます。 id に注意して、その executeStatusを追跡してください。

インポートしたデータを置く

Batch Engineを使用して既存のデータを完全に上書きするには、以下のcURLまたはJavaコマンドを使用します。 この例では、既存のアカウントデータを更新しています。 別のエンティティを使用する場合は、cURLスクリプトで完全修飾クラス名パラメータと上書きするデータを更新する必要があります。

ImportTask_PUT_ById.sh

コマンド:

./ImportTask_PUT_ById.sh com.liferay.headless.admin.user.dto.v1_0.Account

コード:

curl \
	 -H "Content-Type: application/json" \
	 -X PUT \
	 "http://localhost:8080/o/headless-batch-engine/v1.0/import-task/${1}" \
	 -d "[{\"id\" :1234, \"name\": \"Bar\", \"type\": \"business\"}, {\"id\": 5678, \"name\": \"Goo\", \"type\": \"guest\"}]" \
	 -u "[email protected]:learn"

ImportTask_PUT_ById.java

ImportTask_PUT_ById クラスを実行します。 able をクラスの完全修飾名に、 baker をJSONデータに置き換えて、そこにあるものを上書きしてください。 データには、上書きしたいエンティティのIDが含まれている必要があります。

コマンド:

java -classpath .:* -DclassName=able -Ddata=baker ImportTask_PUT_ById

例えば、既存の アカウント のデータを上書きしたい場合は、 12345678 を既存のアカウントの ID に置き換えます。

java -classpath .:* -DclassName=com.liferay.headless.admin.user.dto.v1_0.Account -Ddata="[{\"id\" :1234, \"name\": \"Bar\", \"type\": \"business\"}, {\"id\": 5678, \"name\": \"Goo\", \"type\": \"guest\"}]" ImportTask_PUT_ById

コード:

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

	ImportTaskResource importTaskResource = builder.authentication(
		"[email protected]", "learn"
	).build();

	System.out.println(
		importTaskResource.putImportTask(
			String.valueOf(System.getProperty("className")), "", "", "", "",
			null, String.valueOf(System.getProperty("data"))));
}

インポートデータを削除する

Batch Engineを使用して既存のデータを削除するには、以下のcURLまたはJavaコマンドを使用します。 この例では、アカウントデータを削除しています。 別のエンティティを使用する場合は、完全修飾クラス名パラメータを更新し、さらにcURLスクリプトで削除するデータを更新する必要があります。

ImportTask_DELETE_ById.sh

コマンド:

./ImportTask_DELETE_ById.sh com.liferay.headless.admin.user.dto.v1_0.Account

コード:

curl \
	 -H "Content-Type: application/json" \
	 -X DELETE \
	 "http://localhost:8080/o/headless-batch-engine/v1.0/import-task/${1}" \
	 -d "[{\"id\": 1234}, {\"id\": 5678}]" \
	 -u "[email protected]:learn"

ImportTask_DELETE_ById.java

ImportTask_DELETE_ById クラスを実行します。 able をクラスの完全修飾名に、 baker をJSONデータに置き換えて、そこにあるものを上書きしてください。 データには、削除したいエンティティのIDが含まれている必要があります。

コマンド:

java -classpath .:* -DclassName=able -Ddata=baker ImportTask_DELETE_ById

例えば、 アカウント のデータを削除する場合、 12345678 を既存のアカウントの ID に置き換えてください。

java -classpath .:* -DclassName=com.liferay.headless.admin.user.dto.v1_0.Account -Ddata="[{\"id\": 1234}, {\"id\": 5678}]" ImportTask_DELETE_ById

コード:

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

	ImportTaskResource importTaskResource = builder.authentication(
		"[email protected]", "learn"
	).build();

	System.out.println(
		importTaskResource.deleteImportTask(
			String.valueOf(System.getProperty("className")), null, null,
			null, null, String.valueOf(System.getProperty("data"))));
}

インポートデータの内容を取得する

インポートしたデータは、以下のcURLやJavaコマンドで取得することができます。 1234 をインポートタスクのIDに置き換えてください。 そして、カレントディレクトリに .zip ファイルとしてダウンロードされます。

ImportTaskContent_GET_ById.sh

コマンド:

./ImportTaskContent_GET_ById.sh 1234

コード:

curl \
	 "http://localhost:8080/o/headless-batch-engine/v1.0/import-task/${1}/content" \
	 -o file.zip \
	 -u "[email protected]:learn"

ImportTaskContent_GET_ById.java

コマンド

java -classpath .:* -DimportTaskId=1234 ImportTaskContent_GET_ById

コード:

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

	ImportTaskResource importTaskResource = builder.authentication(
		"[email protected]", "learn"
	).build();

	HttpInvoker.HttpResponse httpResponse =
		importTaskResource.getImportTaskContentHttpResponse(
			Long.valueOf(System.getProperty("importTaskId")));

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

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

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

追加情報