oo

バッチエンジン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 に変更します。

その後、以下の手順に従ってください:

  1. 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
    
  2. データをインポートするには、インポートするエンティティの完全修飾クラス名が必要です。 クラス名は、インストールされているAPI Explorerの /o/api から取得できる。 スキーマ セクションまでスクロールダウンし、インポートしたいエンティティの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 である。 バッチエンジンへのタスクの送信を示します。 データを確認するためには、これが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. グローバルメニュー( アプリケーションメニューアイコン )を開き、 コントロールパネルアカウント に移動して、インポートされたデータを確認します。 新しいアカウントが2つ追加されたことを確認します。

    Verify that two new accounts have been added.

  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
    

    例えば、Account データをインポートする:

    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 \
	"http://localhost:8080/o/headless-batch-engine/v1.0/import-task/${1}" \
	--data-raw '
		[
			{
				"name": "Able",
				"type": "business"
			},
			{
				"name": "Baker",
				"type": "guest"
			}
		]' \
	--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/import-task/${1}" RESTサービスのエンドポイント
-d "[{\"name\": \"Able\", \"type\": \"business\"}, {\"name\": \"Baker\", \"type\": \"guest\"}]" お客様が掲載を希望するデータ
-u "test@liferay.com:learn" 基本的な認証情報
note

ここでは、デモのために基本的な認証を使用しています。 本番環境では、 OAuth 2.0を使用する を介してユーザーを認証する必要があります。 Oauth2 を使用するサンプル React アプリケーションについては、 Use OAuth2 to authorize users を参照してください。

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

Javaクラスを調べる

ImportTask_POST_ToInstance.java クラスはバッチエンジン関連のサービスを呼び出してデータをインポートする。

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

	ImportTaskResource importTaskResource = builder.authentication(
		"test@liferay.com", "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 依存情報は、インストー ルの API エクスプローラーの /o/api にある。

note

mainメソッドのコメントは、クラスの実行を示している。

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

important

サービスの詳細については、 ImportTaskResource を参照。

以下は、cURLとJavaを使用して他のBatch Engine import 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}" \
	--user "test@liferay.com: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(
		"test@liferay.com", "learn"
	).build();

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

データをサイトにインポートする

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

ImportTask_POST_ToSite.sh

コマンド:

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

コード:

curl \
	"http://localhost:8080/o/headless-batch-engine/v1.0/import-task/${1}?siteId=${2}" \
	--data-raw '
		[
			{
				"articleBody": "Foo",
				"headline": "Able"
			},
			{
				"articleBody": "Bar",
				"headline": "Baker"
			}
		]' \
	--header "Content-Type: application/json" \
	--request "POST" \
	--user "test@liferay.com: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(
		"test@liferay.com", "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応答には、新しく作成されたインポートタスクの情報が表示されます。 その executeStatus を追跡するために id に注意すること。

インポートデータを配置する

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

ImportTask_PUT_ById.sh

コマンド:

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

コード:

curl \
	"http://localhost:8080/o/headless-batch-engine/v1.0/import-task/${1}" \
	--data-raw '
		[
			{
				"id": 1234,
				"name": "Bar",
				"type": "business"
			},
			{
				"id": 5678,
				"name": "Goo",
				"type": "guest"
			}
		]' \
	--header "Content-Type: application/json" \
	--request "PUT" \
	--user "test@liferay.com:learn"

ImportTask_PUT_ById.java

ImportTask_PUT_ById クラスを実行する。 ableをクラスの完全修飾名に、bakerをJSONデータに置き換えて上書きする。 データには、上書きしたいエンティティのIDが含まれているはずです。

コマンド:

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

例えば、既存のAccountのデータを上書きしたい場合は、12345678を既存のAccountの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(
		"test@liferay.com", "learn"
	).build();

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

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

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

ImportTask_DELETE_ById.sh

コマンド:

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

コード:

curl \
	"http://localhost:8080/o/headless-batch-engine/v1.0/import-task/${1}" \
	--data-raw '
		[
			{
				"id": 1234
			},
			{
				"id": 5678
			}
		]' \
	--header "Content-Type: application/json" \
	--request "DELETE" \
	--user "test@liferay.com: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(
		"test@liferay.com", "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" \
	--output file.zip \
	--user "test@liferay.com: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(
		"test@liferay.com", "learn"
	).build();

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

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

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

RESTサービスの使用 には、ヘッドレスバッチエンジンの全サービスとスキーマが一覧表示され、各サービスを試すためのインターフェースがあります。

関連トピック

Capability: