Adobe Experience Platformデータ取り込みAPIを使用すると、データをバッチファイルとしてプラットフォームに取り込むことができます。 取り込まれるデータは、CRMシステムのフラットファイル(Parketファイルなど)のプロファイルデータ、またはExperience Data Model (XDM)レジストリの既知のスキーマに準拠するデータです。
データ取得 API のリファレンスはでは、これらの API 呼び出しに関する追加情報が提供されています。
次の図に、バッチインジェストプロセスの概要を示します。
Data Ingestion APIを使用すると、次の3つの基本的な手順でデータをバッチ(1つのユニットとして取り込まれる1つ以上のファイルから成るデータの1単位)としてExperience Platformに取り込むことができます。
512 MB を超えるファイルをアップロードする場合は、ファイルを小さなチャンクに分割する必要があります。サイズの大きなファイルをアップロードする手順については、こちらを参照してください。
ここでは、リクエストの形式を説明するために API 呼び出しの例を示します。これには、パス、必須ヘッダー、適切に書式設定されたリクエストペイロードが含まれます。また、API レスポンスで返されるサンプル JSON も示されています。ドキュメントで使用される API 呼び出し例の表記について詳しくは、 トラブルシューテングガイドのAPI 呼び出し例の読み方に関する節を参照してください。Experience Platform
Platform API を呼び出すには、まず認証チュートリアルを完了する必要があります。次に示すように、すべての Experience Platform API 呼び出しに必要な各ヘッダーの値は認証チュートリアルで説明されています。
{ACCESS_TOKEN}
{API_KEY}
{IMS_ORG}
Experience Platform内のすべてのリソースは、特定の仮想サンドボックスに分離されています。 Platform APIへのすべてのリクエストには、操作が行われるサンドボックスの名前を指定するヘッダーが必要です。
{SANDBOX_NAME}
Platformのサンドボックスについて詳しくは、サンドボックスの概要ドキュメントを参照してください。
ペイロード(POST、PUT、PATCH)を含むすべてのリクエストには、以下のような追加ヘッダーが必要です。
データをデータセットに追加するには、データをバッチにリンクする必要があります。その後、バッチは、指定したデータセットにアップロードされます。
POST /batches
リクエスト
curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
-H "Content-Type: application/json" \
-H "x-gw-ims-org-id: {IMS_ORG}" \
-H "x-sandbox-name: {SANDBOX_NAME}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key : {API_KEY}"
-d '{
"datasetId": "{DATASET_ID}"
}'
プロパティ | 説明 |
---|---|
datasetId |
ファイルのアップロード先のデータセットの ID。 |
レポンス
{
"id": "{BATCH_ID}",
"imsOrg": "{IMS_ORG}",
"updated": 0,
"status": "loading",
"created": 0,
"relatedObjects": [
{
"type": "dataSet",
"id": "{DATASET_ID}"
}
],
"version": "1.0.0",
"tags": {},
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}"
}
プロパティ | 説明 |
---|---|
id |
作成されたバッチの ID(後続のリクエストで使用します)。 |
relatedObjects.id |
ファイルのアップロード先のデータセットの ID。 |
アップロード用の新しいバッチが正常に作成されたら、ファイルを特定のデータセットにアップロードできます。
ファイルをアップロードするには、Small File Upload API を使用します。ただし、ファイルのサイズが大きすぎて、ゲートウェイの制限(拡張タイムアウト、リクエストの本文のサイズ、その他の制限)を超える場合は、Large File Upload API に切り替えることができます。この API は、ファイルをチャンク単位でアップロードし、その後 Large File Upload Complete API 呼び出しを使用してデータを統合します。
以下の例では、Apache Parketファイル形式を使用しています。 JSON ファイル形式の使用例については、『バッチ取得開発者ガイド』を参照してください。
バッチを作成したら、データを既存のデータセットにアップロードできます。アップロードするファイルは、参照されている XDM スキーマに一致している必要があります。
PUT /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
プロパティ | 説明 |
---|---|
{BATCH_ID} |
バッチの ID。 |
{DATASET_ID} |
ファイルをアップロードするデータセットの 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: {IMS_ORG}" \
-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} |
バッチの ID。 |
{DATASET_ID} |
ファイルを取り込むデータセットの 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: {IMS_ORG}" \
-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} |
バッチの ID。 |
{DATASET_ID} |
ファイルのアップロード先のデータセットの 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: {IMS_ORG}" \
-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} |
データセットにアップロードするバッチの ID。 |
curl -X POST "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE" \
-H "x-gw-ims-org-id: {IMS_ORG}" \
-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} |
確認するバッチの ID。 |
リクエスト
curl GET "https://platform.adobe.io/data/foundation/catalog/batch/{BATCH_ID}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-gw-ims-org-id: {IMS_ORG}" \
-H "x-sandbox-name: {SANDBOX_NAME}" \
-H "x-api-key: {API_KEY}"
レスポンス
{
"{BATCH_ID}": {
"imsOrg": "{IMS_ORG}",
"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} |
バッチを作成または更新したユーザーの ID。 |
"status"
フィールドに、リクエストしたバッチの現在のステータスが示されます。バッチの状態は次のいずれかです。
ステータス | 説明 |
---|---|
Abandoned | バッチは、予想期間内に完了しませんでした。 |
Aborted | 指定したバッチに対して、中止操作が明示的に(Batch Ingest API を介して)呼び出されました。バッチが「ロード済み」状態になると、中止できません。 |
アクティブ | バッチは正常に昇格しており、ダウンストリームで使用することができます。このステータスは、「成功」と同じように使用できます。 |
Deleted | バッチのデータは完全に削除されました。 |
Failed | 設定またはデータ、あるいはその両方が不正なために発生した、失敗の状態。失敗したバッチのデータは、表示されません。このステータスは、「Failure」と同じ意味で使用できます。 |
Inactive | バッチは正常に昇格しましたが、元に戻されたか、有効期限が切れています。バッチは、ダウンストリームで使用できません。 |
Loaded | バッチのデータのアップロードが完了し、バッチ昇格の準備ができています。 |
Loading | このバッチのデータはアップロード中です。現在、バッチ昇格の準備はできていません。 |
Retrying | このバッチのデータは処理中です。ただし、システムエラーまたは一時的なエラーが原因でバッチが失敗しました。その結果、このバッチは再試行中です。 |
Staged | バッチの昇進プロセスのステージング段階が完了し、インジェストジョブが実行されました。 |
Staging | バッチのデータは処理中です。 |
Stalled | バッチのデータは処理中です。ただし、バッチの昇進は、数回再試行した後に停止されました。 |