バッチエンジンAPIの基本 - データのインポート
Liferayのヘッドレスバッチエンジンは、データのインポートやエクスポートを行うためのREST APIを提供します。 これらのサービスを呼び出して、Liferayにデータをインポートします。
データのインポート
Liferay DXP の新しいインスタンスを起動するには、以下を実行します。
docker run -it -m 8g -p 8080:8080 liferay/dxp:2026.q1.9-lts
http://localhost:8080 に、メールアドレス test@liferay.com とパスワード test を使用して Liferay にサインインします。 プロンプトが表示されたら、パスワードを learn に変更してください。
それでは、以下の手順に従ってください。
-
バッチエンジンAPIの基本 をダウンロードして解凍します。
curl https://resources.learn.liferay.com/examples/liferay-g4j2.zip -Ounzip liferay-g4j2.zip -
データをインポートするには、インポートするエンティティの完全修飾クラス名が必要です。 クラス名は、インストール先の API エクスプローラー
/o/apiから取得できます。 Schemas セクションまでスクロールダウンし、インポートしたいエンティティのx-class-nameフィールドをメモします。 -
以下のcURLスクリプトを使用して、アカウントをLiferayインスタンスにインポートしてください。 コマンドラインで、
curlフォルダーに移動します。ImportTask_POST_ToInstance.shスクリプトを、完全修飾クラス名 Account をパラメータとして実行します。./ImportTask_POST_ToInstance.sh com.liferay.headless.admin.user.dto.v1_0.AccountJSONレスポンスには、新しいインポートタスクの作成が示されています。 タスクの
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"、 "操作" : "CREATE"、 "processedItemsCount" : 0、 "startTime" : "2022-10-19T14:19:43Z", "totalItemsCount" : 0 } -
現在の
実行ステータスはINITIALです。 これは、タスクがバッチエンジンに送信されたことを示します。 データの検証を行うには、これが完了になるまで待つ必要があります。 コマンドラインで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" : "完了"、 "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にFAILEDと表示されている場合、errorMessageフィールドを確認して、何が問題だったのかを理解してください。 -
グローバルメニュー (
) を開き、 コントロールパネル → アカウント に移動して、インポートされたデータを確認します。 新しいアカウントが2つ追加されていることを確認してください。
-
Javaクライアントを使用してRESTサービスを呼び出すこともできます。
curlフォルダからjavaフォルダに移動します。 ソースファイルをコンパイルします。javac -classpath .:* *.java -
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_ToInstanceJSONレスポンスからインポートタスクの
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"、
"タイプ": "ビジネス"
}、
{
"名前": "パン屋"、
"タイプ": "ゲスト"
}
]' \
--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 "[{\"名前\": \"Able\"、\"タイプ\": \"ビジネス\"}、{\"名前\": \"Baker\"、\"タイプ\": \"ゲスト\"}]" | お客様が掲載を希望するデータ |
-u "test@liferay.com:learn" | 基本的な認証情報 |
ここでは、デモンストレーション目的で基本認証を使用しています。 本番環境では、 OAuth2 を介してユーザーを認証する必要があります。 OAuth2 を使用する React アプリケーションの例については、 OAuth2 を使用してユーザーを認証する を参照してください。
他のcURLコマンドも同様のJSON引数を使用しています。
Javaクラスを調べます
ImportTask_POST_ToInstance.java クラスは、 ImportTaskResource サービスを呼び出すことでデータをインポートします。
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エクスプローラーで確認できます。
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}" \
--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"、
"見出し": "Able"
}、
{
"記事本文": "バー"、
"見出し": "パン屋"
}
]' \
--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 に注目して、その 実行ステータス を追跡してください。
インポートしたデータを配置する
バッチエンジンを使用して既存のデータを完全に上書きするには、以下の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,
"名前": "バー"、
"タイプ": "ビジネス"
}、
{
"ID": 5678、
"名前": "Goo"、
"タイプ": "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
例えば、既存の アカウント のデータを上書きしたい場合は、 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
例えば、 アカウント のデータを削除したい場合は、 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 ファイルとしてダウンロードされます。
ImportTask_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 Explorer には、すべての Headless Batch Engine サービスとスキーマが一覧表示され、各サービスを試すためのインターフェースがあります。
バッチエクスポートファイルからデータをインポートする
バッチエンジン経由でエクスポートしてダウンロードしたデータは、抽出後にインポートすることができます。
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"
外部参照コードパラメータを使用したデータのインポート
Liferay DXP 2025.Q2+
externalReferenceCode クエリ パラメータを含むデータをインポートすると、そのパラメータはインポート タスク自体の外部参照コードを設定しますが、指定された API エンドポイントには適用されません。 代わりに、 batchExternalReferenceCode パラメーターを使用して、外部参照コードをエンドポイントに渡します。 これは、インポートするデータとは別に、インポートタスクの外部参照コードを個別に設定します。
例えば、ここではインポートタスクの外部参照コードが 00000000-aaaa-1111-bbbb-2222222222222に設定され、インポートされた Able オブジェクトの外部参照コードは 33333333-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 パラメータは無視されます。
インポート時に既存のエントリを照合する
デフォルトでは、インポート時にすべての項目が新しいエントリとして挿入されるため、同じデータを2回インポートすると重複データが作成されます。 代わりに外部参照コードで一致する既存のエントリを更新するには、 createStrategy を UPSERT に設定します。 値については、 作成ストラテジー パラメーター および関連する updateStrategy パラメーターを参照してください。
外部参照コードによるデータの削除
Liferay DXP 2025.Q2+
外部参照コードを使用すると、データを一括削除できます。 外部参照コードは、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 オブジェクト( 名前 と 番号 フィールドを持つ)のエントリを 1 つインポートします。
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+/Portal 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 戦略が使用されます。
多くのエンティティは、ネストされたフィールドとして 作成者 を公開しており、エクスポートには要求した場合にのみ含まれます。 これらの場合、 batchNestedFields=creator を使用してエクスポートすると、データには KEEP_CREATOR がインポート時に読み取る作成者が含まれます。
インポートされた値のローカライズ
Liferay DXP 2026.Q3+
インポートされたデータのローカライズされたフィールド値は、 _i18n マップ、例えば value_i18n に格納されます。 キーが [$FOR_EACH_LANGUAGE_ID$] で、値が言語キーであるエントリを追加します。 インポート時に、そのエントリはLiferayインスタンスで有効になっている言語ごとに1つのエントリに展開されるため、すべての言語を手動でリストする必要はありません。
"value_i18n": {
"[$FOR_EACH_LANGUAGE_ID$]": "welcome-to-liferay"
}
言語キー解決有効化 設定は解決を制御し、デフォルトで有効になっています。 無効になっている場合、インポートは、記述されたとおりにリテラル [$FOR_EACH_LANGUAGE_ID$] キーを保存します。
言語の優先順位、設定の場所、および言語キーが解決されない場合の動作については、 バッチインポート値のローカライズ を参照してください。