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

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

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

データのインポート

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

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

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

それでは、以下の手順に従ってください。

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

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

    unzip liferay-g4j2.zip

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

  3. 以下の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
}

  4. 現在の 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フィールドで、何が問題だったかを確認します。

  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

    例えば、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に置き換えてください。 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 クラスは、 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 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 ファイルとしてダウンロードされます。

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 パラメータは無視されます。

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

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 戦略が使用されます。

Capability:
Platform
Resource Type:
Official Documentation
Feature:
API Development
Multi-Channel Experiences (Headless Delivery)
Deployment Approach:
Liferay PaaS
Liferay SaaS
Liferay Self-Hosted