バッチ取得 API の概要
Adobe Experience Platform Batch Ingestion API を使用すると、データをバッチファイルとしてExperience Platformに取り込むことができます。 取り込まれるデータは、フラットファイル（Parquet ファイルなど）のプロファイルデータや、Experience Data Model （XDM）レジストリ内の既知のスキーマに準拠するデータの場合があります。
バッチ取り込み API リファレンス は、これらの API 呼び出しに関する追加情報を提供します。
次の図に、バッチインジェストプロセスの概要を示します。
はじめに
このガイドで使用する API エンドポイントは、 バッチ取得 API の一部です。 先に進む前に、はじめる前にを参照し、関連ドキュメントへのリンク、このドキュメントのサンプル API 呼び出しを読み取るためのガイドおよび任意の Experience Platform API を正常に呼び出すために必要なヘッダーに関する重要な情報を確認してください。
Data Ingestion 前提条件
- アップロードするデータは、Parquet 形式または JSON 形式である必要があります。
- Catalog services で作成されたデータセット。
- Parquet ファイルのコンテンツは、にアップロードするデータセットのスキーマのサブセットと一致する必要があります。
- 認証後に固有のアクセストークンを取得する必要があります。
バッチインジェストのベストプラクティス
- 推奨されるバッチサイズは 256 MB～100 GB です。
- 各バッチには、最大 1,500 個のファイルを含めることができます。
バッチ取り込み制約
バッチデータ取得には、いくつかの制約があります。
- バッチあたりの最大ファイル数：1500
- 最大バッチサイズ：100GB
- 1 行あたりのプロパティまたはフィールドの最大数：10000
- ユーザーごとの 1 分あたりのデータレイク上のバッチの最大数：2000
タイプ
データを取り込む場合、Experience Data Model （XDM）スキーマの仕組みを理解することが重要です。 XDM のフィールドタイプを様々な形式にマップする方法について詳しくは、『スキーマレジストリ開発者ガイド』を参照してください。
データを取り込む際には、ある程度の柔軟性があります。タイプがターゲットスキーマのタイプと一致しない場合、データは表現されたターゲットタイプに変換されます。 できない場合は、バッチが TypeCompatibilityException で失敗します。
例えば、JSON も CSV も date タイプや date-time タイプはありません。 そのため、これらの値は ISO 8601 形式の文字列 （「2018-07-10T15:05:59.000-08:00」）またはミリ秒単位の Unix 時間（1531263959000）で表され、取り込み時にターゲット XDM タイプに変換されます。
次の表に、データの取得時にサポートされる変換を示します。
API の使用
Data Ingestion API を使用すると、データをバッチ（単一の単位として取り込む 1 つ以上のファイルで構成されるデータの単位）として、次の 3 つの基本的な手順で Experience Platform に取り込むことができます。
- 新しいバッチを作成します。
- データの XDM スキーマと一致する、指定したデータセットにファイルをアップロードします。
- バッチの終了を示します。
バッチの作成
データをデータセットに追加するには、データをバッチにリンクする必要があります。その後、バッチは、指定したデータセットにアップロードされます。
POST /batches
リクエスト
curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
-H "Content-Type: application/json" \
-H "x-gw-ims-org-id: {ORG_ID}" \
-H "x-sandbox-name: {SANDBOX_NAME}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key: {API_KEY}"
-d '{
"datasetId": "{DATASET_ID}"
}'
datasetIdレポンス
{
"id": "{BATCH_ID}",
"imsOrg": "{ORG_ID}",
"updated": 0,
"status": "loading",
"created": 0,
"relatedObjects": [
{
"type": "dataSet",
"id": "{DATASET_ID}"
}
],
"version": "1.0.0",
"tags": {},
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}"
}
idrelatedObjects.idファイルのアップロード
アップロード用の新しいバッチが正常に作成されたら、ファイルを特定のデータセットにアップロードできます。
小さいファイルアップロード API を使用してファイルをアップロードできます。 ただし、ファイルが大きすぎてゲートウェイの制限を超えている場合（拡張タイムアウト、本文サイズのリクエストを超えている、その他の制限など）は、大きなファイルアップロード API に切り替えることができます。 この API はファイルをチャンク単位でアップロードし、大きなファイルアップロード完了 API 呼び出しを使用してデータをステッチします。
サイズの小さなファイルのアップロード
バッチを作成したら、データを既存のデータセットにアップロードできます。アップロードするファイルは、参照されている XDM スキーマに一致している必要があります。
PUT /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
{BATCH_ID}{DATASET_ID}{FILE_NAME}リクエスト
curl -X PUT "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.parquet" \
-H "content-type: application/octet-stream" \
-H "x-gw-ims-org-id: {ORG_ID}" \
-H "x-sandbox-name: {SANDBOX_NAME}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key: {API_KEY}" \
--data-binary "@{FILE_PATH_AND_NAME}.parquet"
{FILE_PATH_AND_NAME}応答
#Status 200 OK, with empty response body
サイズの大きなファイルのアップロード - ファイルの作成
サイズの大きなファイルをアップロードするには、ファイルを小さなチャンクに分割し、一度に 1 つずつアップロードする必要があります。
POST /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}?action=initialize
{BATCH_ID}{DATASET_ID}{FILE_NAME}リクエスト
curl -X POST "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/part1=a/part2=b/{FILE_NAME}.parquet?action=initialize" \
-H "x-gw-ims-org-id: {ORG_ID}" \
-H "x-sandbox-name: {SANDBOX_NAME}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key: {API_KEY}"
レスポンス
#Status 201 CREATED, with empty response body
サイズの大きなファイルのアップロード - 後続チャンクのアップロード
ファイルを作成したら、ファイルの各セクションに対して 1 回ずつ、PATCH リクエストを繰り返しおこなうことで、以降のすべてのチャンクをアップロードできます。
PATCH /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
{BATCH_ID}{DATASET_ID}{FILE_NAME}リクエスト
curl -X PATCH "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/part1=a/part2=b/{FILE_NAME}.parquet" \
-H "content-type: application/octet-stream" \
-H "x-gw-ims-org-id: {ORG_ID}" \
-H "x-sandbox-name: {SANDBOX_NAME}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key: {API_KEY}" \
-H "Content-Range: bytes {CONTENT_RANGE}" \
--data-binary "@{FILE_PATH_AND_NAME}.parquet"
{FILE_PATH_AND_NAME}レスポンス
#Status 200 OK, with empty response
バッチ完了を示す
すべてのファイルをバッチにアップロードしたら、バッチの完了を示すことができます。これにより、完成したファイルに対して Catalog の DataSetFile エントリが作成され、上記で生成されたバッチに関連付けられます。 これにより、Catalog のバッチが成功とマークされ、ダウンストリームフローがトリガーされて使用可能なデータを取り込みます。
リクエスト
POST /batches/{BATCH_ID}?action=COMPLETE
{BATCH_ID}curl -X POST "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE" \
-H "x-gw-ims-org-id: {ORG_ID}" \
-H "x-sandbox-name: {SANDBOX_NAME}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key: {API_KEY}"
レスポンス
#Status 200 OK, with empty response
バッチステータスの確認
バッチにファイルがアップロードされるのを待つ間、バッチのステータスを確認して進行状況を確認できます。
API 形式
GET /batch/{BATCH_ID}
{BATCH_ID}リクエスト
curl GET "https://platform.adobe.io/data/foundation/catalog/batch/{BATCH_ID}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-gw-ims-org-id: {ORG_ID}" \
-H "x-sandbox-name: {SANDBOX_NAME}" \
-H "x-api-key: {API_KEY}"
レスポンス
{
"{BATCH_ID}": {
"imsOrg": "{ORG_ID}",
"created": 1494349962314,
"createdClient": "MCDPCatalogService",
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}",
"updated": 1494349963467,
"externalId": "{EXTERNAL_ID}",
"status": "success",
"errors": [
{
"code": "err-1494349963436"
}
],
"version": "1.0.3",
"availableDates": {
"startDate": 1337,
"endDate": 4000
},
"relatedObjects": [
{
"type": "batch",
"id": "foo_batch"
},
{
"type": "connection",
"id": "foo_connection"
},
{
"type": "connector",
"id": "foo_connector"
},
{
"type": "dataSet",
"id": "foo_dataSet"
},
{
"type": "dataSetView",
"id": "foo_dataSetView"
},
{
"type": "dataSetFile",
"id": "foo_dataSetFile"
},
{
"type": "expressionBlock",
"id": "foo_expressionBlock"
},
{
"type": "service",
"id": "foo_service"
},
{
"type": "serviceDefinition",
"id": "foo_serviceDefinition"
}
],
"metrics": {
"foo": 1337
},
"tags": {
"foo_bar": [
"stuff"
],
"bar_foo": [
"woo",
"baz"
],
"foo/bar/foo-bar": [
"weehaw",
"wee:haw"
]
},
"inputFormat": {
"format": "parquet",
"delimiter": ".",
"quote": "`",
"escape": "\\",
"nullMarker": "",
"header": "true",
"charset": "UTF-8"
}
}
}
{USER_ID}"status" フィールドに、リクエストしたバッチの現在のステータスが示されます。バッチの状態は次のいずれかです。