バッチ取得トラブルシューティングガイド

このドキュメントは、Adobe Experience Platform Batch Data Ingestion API に関してよくある質問への回答に役立ちます。

バッチ API 呼び出し

バッチは、CompleteBatch API から HTTP 200 OK を受け取った後すぐにアクティブになりますか？

API からの 200 OK の応答は、バッチの処理が受理されたことを意味します。バッチは、「アクティブ」や「失敗」などの最終状態にトランジションするまでアクティブになりません。

失敗した後で CompleteBatch API 呼び出しを再試行しても問題はありませんか？

はい — API 呼び出しを再試行しても安全です。失敗したにもかかわらず、操作が実際に成功し、バッチが正常に受け入れられた可能性があります。ただし、クライアントには API に障害が発生した場合に備えた再試行メカニズムが必要となり、実際に再試行は推奨されています。操作が実際に成功した場合、API は再試行後も成功を返します。

Large File Upload API は、いつ使用する必要がありますか？

Large File Upload API を使用する場合の推奨ファイルサイズは 256 MB 以上です。Large File Upload API の使用方法について詳しくは、こちらを参照してください。

Large File Complete API 呼び出しが失敗するのはなぜですか？

大きなファイルのチャンクが重なっているか、見つからない場合、サーバーは HTTP 400（不正なリクエスト）を返します。これは、ファイルチャンクが繋がり合わされる際に、範囲検証がファイルの完了時に行われるので、重なり合うチャンクをアップロードできる場合があるためです。

取得サポート

サポートされている取得形式を教えてください。

現在、Parquet と JSON の両方がサポートされています。CSV はレガシーベースでサポートされています。データはマスターにプロモーションされ、事前確認が行われますが、コンバージョン、パーティション化、行の検証などの最新の機能はサポートされません。

バッチ入力形式はどこで指定しますか。

入力形式は、ペイロード内でのバッチ作成時に指定する必要があります。バッチ入力形式の指定方法の例を次に示します。

curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
  -H "accept: application/json" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"
  -d '{
          "datasetId": "{DATASET_ID}",
           "inputFormat": {
                "format": "json"
           }
    }'

アップロードされたデータがデータセットに表示されないのはなぜですか？

データをデータセットに表示するには、バッチが完了とマークされている必要があります。取得するすべてのファイルをアップロードしてから、バッチを完了としてマークする必要があります。バッチを完了としてマークする例を次に示します。

curl -X POST "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE" \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

複数行の JSON はどのように取得されますか？

複数行の JSON を取得するには、バッチ作成時に isMultiLineJson フラグを設定する必要があります。この例を次に示します。

curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
  -H "accept: application/json" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"
  -d '{
          "datasetId": "{DATASET_ID}",
           "inputFormat": {
                "format": "json",
                "isMultiLineJson": true
           }
      }'

JSON 行（1 行 JSON）と複数行 JSON の違いを教えてください。

JSON 行の場合、1 行に 1 つの JSON オブジェクトがあります。以下に例を示します。

{"string":"string1","int":1,"array":[1,2,3],"dict": {"key": "value1"}}
{"string":"string2","int":2,"array":[2,4,6],"dict": {"key": "value2"}}
{"string":"string3","int":3,"array":[3,6,9],"dict": {"key": "value3", "extra_key": "extra_value3"}}

複数行の JSON の場合、1 つのオブジェクトが複数行を占め、すべてのオブジェクトが JSON 配列に含まれます。以下に例を示します。

[
    {"string":"string1","int":1,"array":[1,2,3],"dict": {"key": "value1"}},
    {"string":"string2","int":2,"array":[2,4,6],"dict": {"key": "value2"}},
    {
        "string": "string3",
        "int": 3,
        "array": [
            3,
            6,
            9
        ],
        "dict": {
            "key": "value3",
            "extra_key": "extra_value3"
        }
    }
]

デフォルトでは、Batch Data Ingestion は 1 行の JSON を使用します。

CSV の取得はサポートされていますか？

CSV の取得は、フラットなスキーマのみサポートされています。現在、CSV での階層データの取り込みはサポートされていません。

すべてのデータ取得機能を使用するには、JSON または Parquet 形式が必要です。

データに対して実行される検証のタイプを教えてください。

データに対して実行される検証には、次の 3 つのレベルがあります。

既に取得されたバッチを置き換える方法を教えてください。

既に取得されたバッチは、バッチ再生機能を使用して置き換えることができます。バッチ再生の詳細については、こちらを参照してください。

バッチ取得はどのように監視されますか？

バッチがバッチプロモーション用に通知されたら、次のリクエストでバッチ取得の進行状況を監視できます。

curl -X GET "https://platform.adobe.io/data/foundation/catalog/batches/{BATCH_ID}" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"

このリクエストを使用すると、次のような応答が返されます。

200 OK

{
    "{BATCH_ID}":{
        "imsOrg":"{ORG_ID}",
        "created":1494349962314,
        "createdClient":"{API_KEY}",
        "createdUser":"{USER_ID}",
        "updatedUser":"{USER_ID}",
        "completed":1494349963467,
        "externalId":"{EXTERNAL_ID}",
        "status":"staging",
        "errors":[],
    }
}

バッチ状態

可能なバッチ状態を教えてください。

バッチは、そのライフサイクルで、次のステータスを経由できます。

バッチの「Staging」とは何を意味しますか？

バッチが「ステージング」の場合、それは、バッチがプロモーションのために正常に通知され、データがダウンストリームで消費するためにステージングされていることを意味します。

バッチの「Retrying」とは何を意味しますか？

バッチが「再試行中」の場合は、断続的な問題が原因でバッチのデータ取得が一時的に停止しています。この場合、顧客の介入は必要ありません。

バッチの「Stalled」とは何を意味しますか？

バッチが「停止」の場合は、Data Ingestion Services によるバッチ取得が困難で、すべての再試行が使い果たされています。

バッチの「Loading」とは何を意味しますか？

バッチが「読み込み中」の場合、CompleteBatch API が呼び出されていないので、バッチをプロモートします。

バッチが正常に取得されたかどうかを知る方法はありますか？

はい。バッチステータスが「アクティブ」になると、バッチは正常に取り込まれました。 バッチのステータスを確認するには、前述の手順に従います。

バッチが失敗した後はどうなりますか？ what-if-a-batch-fails

バッチが失敗すると、プロセスが停止し、Failure のステータスが返されます。 失敗する理由は、ペイロードの errors セクションで特定できます。 エラーの例を次に示します。

    "errors":[
        {
            "code":"106",
            "description":"Dataset file is empty. Please upload file with data.",
            "rows":[]
        },
        {
            "code":"118",
            "description":"CSV file contains empty header row.",
            "rows":[]
        }
    ]

エラーが修正されると、バッチを再度アップロードできます。

バッチサポート

バッチを削除する方法を教えてください。

バッチは、Catalog から直接削除する代わりに、次のいずれかの方法を使用して削除する必要があります。

使用できるバッチレベルの指標を教えてください。

Active／Success 状態のバッチに対しては、次のバッチレベルの指標を使用できます。

指標が一部のバッチで使用できないのはなぜですか？

指標がバッチで使用できない理由は 2 つあります。

異なるステータスコードの意味を教えてください。