バッチ取得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 Time形式のミリ秒（1531263959000）で表され、取り込み時にターゲット XDM タイプに変換されます。
次の表に、データの取得時にサポートされる変換を示します。
API の使用
Data Ingestion APIを使用すると、データをバッチ（単一のユニットとして取り込む1つ以上のファイルで構成されるデータのユニット）として、Experience Platformに3つの基本的な手順で取り込むことができます。
- 新しいバッチを作成します。
- データの 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ファイルのアップロード
アップロード用の新しいバッチが正常に作成されたら、ファイルを特定のデータセットにアップロードできます。
Small File Upload APIを使用してファイルをアップロードできます。 ただし、ファイルが大きすぎて、ゲートウェイの制限（拡張タイムアウト、ボディサイズの要求、その他の制約など）を超えた場合は、Large File Upload APIに切り替えることができます。 このAPIは、ファイルをチャンクにアップロードし、Large File Upload Complete 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" フィールドに、リクエストしたバッチの現在のステータスが示されます。バッチの状態は次のいずれかです。