ご覧のページは、お客様の利便性のために一部機械翻訳されています。また、ドキュメントは頻繁に更新が加えられており、翻訳は未完成の部分が含まれることをご了承ください。最新情報は都度公開されておりますため、必ず英語版をご参照ください。翻訳に問題がある場合は、こちらまでご連絡ください。

バッチエンジンAPIの基本 - データのインポート

Liferayのヘッドレスバッチエンジンは、データのインポートやエクスポートを行うためのREST APIを提供します。これらのサービスを呼び出して、Liferayにデータをインポートします。

データのインポート

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

docker run -it -m 8g -p 8080:8080 liferay/dxp:2025.q1.6-lts

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

次に、次の手順に従います。

バッチエンジン API の基礎をダウンロードして解凍します。

curl https://resources.learn.liferay.com/examples/liferay-g4j2.zip -O

unzip liferay-g4j2.zip

データをインポートするには、インポートするエンティティの完全修飾クラス名が必要です。 /o/apiでインストールされているAPIエクスプローラーからクラス名を取得することができます。 Schemas セクションまでスクロールダウンし、インポートしたいエンティティの x-class-name フィールドをメモしておきます。

以下のcURLスクリプトを使用して、Liferayインスタンスにアカウントをインポートします。コマンドラインで、curlフォルダに移動します。 アカウント の完全修飾クラス名をパラメータとしてImportTask_POST_ToInstance.sh スクリプトを実行します。

./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
}

現在の executeStatus は INITIALです。バッチエンジンへのタスクの送信を示します。これが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
}
```
executeStatus が COMPLETEDの場合、インポートデータを確認することができます。実行されていない場合は、再度コマンドを実行し、タスクの実行が終了したことを確認します。 executeStatusがFAILEDを示している場合、errorMessageフィールドで、何が問題だったかを確認します。
インポートされたデータを確認するには、 グローバルメニュー () を開き、 コントロールパネル → アカウントに移動します。新しいアカウントが2つ追加されたことを確認します。
また、Javaクライアントを使用してThe RESTサービスを呼び出すことができます。 curl フォルダから、 java フォルダに移動します。ソースファイルをコンパイルします。
```
javac -classpath .:* *.java
```
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に注意してください。
ImportTask_GET_ById クラスを実行します。 1234 をインポートタスクのIDに置き換えてください。 executeStatus が COMPLETEDと表示されたら、上記の手順でデータを確認することができます。
```
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"`	基本的な認証情報

注

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

他の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依存関係情報は、/o/apiでインストール先のAPIエクスプローラーで確認できます。

注

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

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

重要

サービスの詳細については、 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コマンドを実行して、サイトにデータをインポートできます。この例では、ブログの記事をサイトにインポートしています。サイトの ID を見つけて、 1234 をそれに置き換えます。別のエンティティを使用する場合は、cURLスクリプトでインポートする完全修飾クラス名パラメーターとデータも更新する必要があります。

注

Liferay DXP 2025.Q3+ からは、サイトIDの代わりにサイトのキー（デフォルトの言語でのサイト名）または外部参照コードを使用することもできます。

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応答には、新しく作成されたインポートタスクの情報が表示されます。 idに注意して、そのexecuteStatusを追跡します。

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

以下の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 のデータを上書きしたい場合は、 1234 と 5678 を既存のアカウントの 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

例えば、 Accountデータを削除する場合は、1234と5678を既存のアカウントの 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 ファイルとしてダウンロードされます。

インポートタスク_GET_ContentById.sh

コマンド：

./ImportTask_GET_ContentById.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());
	}
}

API エクスプローラーには、すべてのヘッドレスバッチエンジンサービスとスキーマが一覧表示され、各サービスを試すためのインターフェイスがあります。

バッチエクスポートファイルからのデータのインポート

エクスポートしてバッチエンジン経由でダウンロードしたデータは、抽出後にインポートできます。

Liferay インスタンスにインポートするデータを含む JSON ファイルを取得したら、 --data パラメータと、ファイルへのパスの前に @ を付けてコマンドを実行します (例: --data @export.json)。

たとえば、このコマンドは、 export1というフォルダー内のファイルからバッチエクスポートでアカウントをインポートします。

curl \
     "http://localhost:8080/o/headless-batch-engine/v1.0/import-task/com.liferay.headless.admin.user.dto.v1_0.Account" \
     --data "@export1/export.json" \
     --header "Content-Type: application/json" \
     --request "POST" \
     --user "test@liferay.com:learn"

externalReferenceCode クエリパラメータを含むデータをインポートする場合、パラメータはインポートタスク自体の外部参照コードを設定しますが、指定された API エンドポイントには適用されません。代わりに、 batchExternalReferenceCode パラメータを使用して、外部参照コードをエンドポイントに渡します。これにより、インポートするデータからインポートタスクの外部参照コードが個別に設定されます。

たとえば、ここではインポートタスクの外部参照コードは 00000000-aaaa-1111-bbbb-222222222222に設定されており、インポートされた Able オブジェクトの外部参照コードは 3333333-cccc-4444-dddd-555555555555です。

curl \
    "http://localhost:8080/o/headless-batch-engine/v1.0/import-task/com.liferay.object.rest.dto.v1_0.ObjectEntry?taskItemDelegateName=C_Able&externalReferenceCode=00000000-aaaa-1111-bbbb-222222222222&batchExternalReferenceCode=33333333-cccc-4444-dddd-555555555555" \
    --data-raw "[{\"name\": \"Mary\"}]" \
    --header "Content-Type: application/json" \
    --request "POST" \
    --user "test@liferay.com:learn"

externalReferenceCode パラメータはインポートタスクにのみ適用され、 batchExternalReferenceCode パラメータはインポートされたエンティティ自体の外部参照コードとして適用されます。

注

Liferay DXP 2025.Q2より前のバージョンでは、 externalReferenceCode クエリパラメータとの両方がインポートタスクの外部参照コードを設定し、APIエンドポイントに適用されます。 batchExternalReferenceCode パラメータは無視されます。

外部参照コードによるデータの削除

Liferay DXP 2025年第2四半期以降

外部参照コードを使用してデータを一括削除できます。 ID が指定されていない場合、外部参照コードは削除対象のエンティティを識別します (そうでない場合、外部参照コードは無視されます)。

サイトまたはアセットライブラリのスコープ内のエンティティを削除するには、そのスコープの識別子 (サイトのキー (既定の言語での名前)、サイト ID、または外部参照コード) を指定する必要があります。

たとえば、このエンドポイントを使用して、ゲストサイトからサイトスコープのオブジェクトを削除できます (外部参照コードは L_GUESTです)。

curl \
    "http://localhost:8080/o/headless-batch-engine/v1.0/import-task/com.liferay.object.rest.dto.v1_0.ObjectEntry?taskItemDelegateName=C_MyObject&siteId=L_GUEST" \
    --data-raw '
        [
            {
                "externalReferenceCode": "11111111-2222-3333-4444-555555555555"
            },
            {
                "externalReferenceCode": "66666666-7777-8888-9999-000000000000"
            }
        ]' \
    --header "Content-Type: application/json" \
    --request "DELETE" \
    --user "test@liferay.com:learn"

このアプローチは、オブジェクトエントリなどのインスタンススコープのデータにも機能します。これは、複数の Liferay インスタンス間で削除を複製する場合に役立ちます。

重要

Liferay 2025.Q2では、インスタンススコープのオブジェクトエントリのみが外部参照コードによる一括削除をサポートします。サイトスコープのエンティティを含む、エンドポイントを使用して他のエンティティタイプを削除するには、Liferay 2025.Q3+ が必要です。

たとえば、このコマンドは、外部参照コードによって University オブジェクトのオブジェクトエントリを削除します。

curl \
    "http://localhost:8080/o/headless-batch-engine/v1.0/import-task/com.liferay.object.rest.dto.v1_0.ObjectEntry?taskItemDelegateName=C_University" \
    --data-raw '
        [
            {
                "externalReferenceCode": "11111111-2222-3333-4444-555555555555"
            },
            {
                "externalReferenceCode": "66666666-7777-8888-9999-000000000000"
            }
        ]' \
    --header "Content-Type: application/json" \
    --request "DELETE" \
    --user "test@liferay.com:learn"

カスタムオブジェクトのインポート

カスタムオブジェクトエントリをインポートするには、URL に ObjectEntry クラス名を指定し、オブジェクトの名前を taskItemDelegateName クエリパラメータで渡す必要があります。

たとえば、このコマンドは、インスタンススコープの Able オブジェクト ( 名前 と 番号 フィールドを持つ) の単一のエントリをインポートします。

curl \
    "http://localhost:8080/o/headless-batch-engine/v1.0/import-task/com.liferay.object.rest.dto.v1_0.ObjectEntry?taskItemDelegateName=C_Able" \
    --data-raw "[{\"name\": \"Mary\", \"number\": \"100\"}]" \
    --header "Content-Type: application/json" \
    --request "POST" \
    --user "test@liferay.com:learn"

オブジェクトのオリジナル作成者データを保持する

Liferay DXP 2025.Q1+/ポータル GA132+

デフォルトでは、バッチエンジン API を使用してオブジェクトデータをインポートすると、インポートされたオブジェクトエントリには作成者情報を含む新しく作成されたメタデータが含まれます。これにより、インポートを認証したユーザーがすべてのオブジェクトの新しい所有者になります。

ただし、URL の末尾に importCreatorStrategy パラメータを追加することで、この動作を変更し、元々エクスポートされた作成者データを保持することができます。このパラメータには 2 つの有効な値があります: KEEP_CREATOR と OVERWRITE_CREATOR (デフォルト値)。

たとえば、次のコマンドは、元の作成者を維持しながら、インスタンススコープの Able オブジェクトのファイルからデータをインポートします。

curl \
    "http://localhost:8080/o/headless-batch-engine/v1.0/import-task/com.liferay.object.rest.dto.v1_0.ObjectEntry?taskItemDelegateName=C_Able&importCreatorStrategy=KEEP_CREATOR" \
     --data "@export.json" \
     --header "Content-Type: application/json" \
     --request "POST" \
     --user "test@liferay.com:learn"

注

KEEP_CREATOR 戦略を使用してオブジェクトデータをインポートしたが、インポートされたデータで参照されているユーザーが対象の Liferay インスタンスに存在しない場合、パラメーターは無視され、代わりに OVERWRITE_CREATOR 戦略が使用されます。

Capability: