Show Menu
トピック×

Batch Ingestion 概要

The Batch Ingestion API allows you to ingest data into Adobe Experience Platform as batch files. Data being ingested can be the profile data from a flat file in a CRM system (such as a parquet file), or data that conforms to a known schema in the Experience Data Model (XDM) registry.
データ取得 API のリファレンスは では、これらの API 呼び出しに関する追加情報が提供されています。
次の図に、バッチインジェストプロセスの概要を示します。

API の使用

The Data Ingestion API allows you to ingest data as batches (a unit of data that consists of one or more files to be ingested as a single unit) into Experience Platform in three basic steps:
  1. 新しいバッチを作成します。
  2. データの XDM スキーマと一致する、指定したデータセットにファイルをアップロードします。
  3. バッチの終了を示します。

Data Ingestion 前提条件

  • アップロードするデータは、Parquet 形式または JSON 形式である必要があります。
  • A dataset created in the Catalog services .
  • Parquet ファイルの内容は、アップロード先のデータセットのスキーマのサブセットと一致している必要があります。
  • 認証後に固有のアクセストークンを取得する必要があります。

バッチインジェストのベストプラクティス

  • 推奨されるバッチサイズは 256 MB~100 GB です。
  • 各バッチには、最大 1,500 個のファイルを含めることができます。
512 MB を超えるファイルをアップロードする場合は、ファイルを小さなチャンクに分割する必要があります。サイズの大きなファイルをアップロードする手順については、 こちら を参照してください。

API 呼び出し例の読み取り

ここでは、リクエストの形式を説明するために API 呼び出しの例を示します。これには、パス、必須ヘッダー、適切に書式設定されたリクエストペイロードが含まれます。また、API レスポンスで返されるサンプル JSON も示されています。ドキュメントで使用される API 呼び出し例の表記について詳しくは、 トラブルシューテングガイドの API 呼び出し例の読み方 に関する節を参照してください。Experience Platform

必須ヘッダーの値の収集

In order to make calls to Platform APIs, you must first complete the authentication tutorial . Completing the authentication tutorial provides the values for each of the required headers in all Experience Platform API calls, as shown below:
  • Authorization: Bearer {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}
All resources in Experience Platform are isolated to specific virtual sandboxes. All requests to Platform APIs require a header that specifies the name of the sandbox the operation will take place in:
  • x-sandbox-name: {SANDBOX_NAME}
For more information on sandboxes in Platform, see the sandbox overview documentation .
ペイロード(POST、PUT、PATCH)を含むすべてのリクエストには、以下のような追加ヘッダーが必要です。
  • Content-Type: application/json

バッチの作成

データをデータセットに追加するには、データをバッチにリンクする必要があります。その後、バッチは、指定したデータセットにアップロードされます。
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 呼び出しを使用してデータを統合します。
次の例では、 Parquet ファイル形式を使用しています。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

バッチ完了を示す

すべてのファイルをバッチにアップロードしたら、バッチの完了を示すことができます。By doing this, the Catalog DataSetFile entries are created for the completed files and associated with the batch generated above. The Catalog batch is then marked as successful, which triggers downstream flows to ingest the available data.
リクエスト
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 を介して)呼び出されました。バッチの状態が「 Loaded 」の場合、バッチを中止することはできません。
アクティブ
バッチは正常に昇格しており、ダウンストリームで使用することができます。このステータスは、 Success と同じ意味で使用できます。
Deleted
バッチのデータは完全に削除されました。
Failed
設定またはデータ、あるいはその両方が不正なために発生した、失敗の状態。失敗したバッチのデータは、表示​ されません 。このステータスは、 Failure と同じ意味で使用できます。
Inactive
バッチは正常に昇格しましたが、元に戻されたか、有効期限が切れています。バッチは、ダウンストリームで使用できません。
Loaded
バッチのデータのアップロードが完了し、バッチ昇格の準備ができています。
Loading
このバッチのデータはアップロード中です。現在、バッチ昇格の準備はできて​ いません
Retrying
このバッチのデータは処理中です。ただし、システムエラーまたは一時的なエラーが原因でバッチが失敗しました。その結果、このバッチは再試行中です。
Staged
バッチの昇進プロセスのステージング段階が完了し、インジェストジョブが実行されました。
Staging
バッチのデータは処理中です。
Stalled
バッチのデータは処理中です。ただし、バッチの昇進は、数回再試行した後に停止されました。