部分バッチ取り込み

最終更新日： 2026年7月14日

トピック：
Data Ingestion

作成対象：

開発者

部分バッチ取り込みは、エラーを含むデータを特定のしきい値まで取り込む機能です。この機能を使用すると、正しいデータをすべて Adobe Experience Platform に正しく取得し、間違ったデータはその理由の詳細とともにすべて別々にバッチ処理されます。

このドキュメントでは、部分バッチ取り込みを管理するためのチュートリアルを提供します。

はじめに

このチュートリアルでは、部分バッチ取り込みに関わる様々な Adobe Experience Platform サービスに関する十分な知識が必要です。このチュートリアルを開始する前に、次のサービスのドキュメントを確認してください。

バッチ取り込み: Experience PlatformがCSVやParquetなどのデータファイルからデータを取り込んで保存するメソッド。
Experience Data Model (XDM)：Experience Platform が、カスタマーエクスペリエンスデータを整理する際に使用する、標準化されたフレームワーク。

以下の節では、Experience Platform API を正しく呼び出すために知っておく必要がある追加情報を示します。

API 呼び出し例の読み取り

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

必須ヘッダーの値の収集

Experience Platform API を呼び出すには、まず認証チュートリアルを完了する必要があります。次に示すように、すべての Experience Platform API 呼び出しに必要な各ヘッダーの値は認証チュートリアルで説明されています。

Authorization: Bearer {ACCESS_TOKEN}
x-api-key： {API_KEY}
x-gw-ims-org-id: {ORG_ID}

Experience Platform のすべてのリソースは、特定の仮想サンドボックスに分離されています。 Experience Platform API へのすべてのリクエストには、操作がおこなわれるサンドボックスの名前を指定するヘッダーが必要です。

x-sandbox-name：{SANDBOX_NAME}

NOTE

Experience Platform のサンドボックスについて詳しくは、サンドボックスの概要に関するドキュメントを参照してください。

APIでバッチの一部を取り込むバッチを有効にする enable-api

NOTE

この節では、APIを使用してバッチを部分的に取り込むためのバッチを有効にする方法について説明します。 UIの使用方法については、「UI ステップでバッチを部分的に取り込むためにバッチを有効にする」を参照してください。

部分取り込みを有効にして、新しいバッチを作成できます。

新しいバッチを作成するには、バッチ取り込み開発者ガイドの手順に従います。「バッチを作成」ステップに到達したら、リクエスト本文内に次のフィールドを追加します。

{
    "enableErrorDiagnostics": true,
    "partialIngestionPercent": 5
}

プロパティ

説明

enableErrorDiagnostics

バッチに関する詳細なエラーメッセージをExperience Platformが生成できるようにするフラグ。

partialIngestionPercent

バッチ全体が失敗する前に許容されるエラーの割合。したがって、この例では、バッチの最大5%が失敗する前にエラーになる可能性があります。

UIでバッチの一部を取り込むバッチを有効にする enable-ui

NOTE

この節では、UIを使用してバッチを部分的に取り込むためのバッチを有効にする方法について説明します。 APIを使用して部分的なバッチ取り込みのバッチを既に有効にしている場合は、次の節に進むことができます。

Experience Platform UIを使用して部分的な取り込みのバッチを有効にするには、ソース接続を使用して新しいバッチを作成するか、既存のデータセットで新しいバッチを作成するか、「CSVをXDM フローにマッピング」を使用して新しいバッチを作成します。

新しいソース接続の作成 new-source

新しいソース接続を作成するには、ソースの概要に記載されている手順に従います。 データフローの詳細 ステップに到達したら、部分取り込みおよびエラー診断 フィールドに注意してください。

部分取り込み トグルを使用すると、部分的なバッチ取り込みの使用を有効または無効にできます。

エラー診断 トグルは、部分取り込み トグルがオフの場合にのみ表示されます。この機能を使用すると、Experience Platformは取り込んだバッチに関する詳細なエラーメッセージを生成できます。 部分取り込み トグルがオンになっている場合、強化されたエラー診断が自動的に適用されます。

エラーしきい値を使用すると、バッチ全体が失敗する前に、許容されるエラーの割合を設定できます。デフォルトでは、この値は 5% に設定されています。

既存のデータセットを使用する existing-dataset

既存のデータセットを使用するには、まずデータセットを選択します。右側のサイドバーに、データセットに関する情報が表示されます。

部分取り込み トグルを使用すると、部分的なバッチ取り込みの使用を有効または無効にできます。

これで、「データを追加」ボタンを使用してデータをアップロードでき、部分取り込みを使用して取り込まれます。

「CSVをXDM スキーマにマッピング」フローを使用 map-flow

「CSVをXDM スキーマにマッピング」フローを使用するには、CSV ファイルをマッピングのチュートリアルに記載されている手順に従います。 データを追加 ステップに到達したら、部分取り込みおよびエラー診断 フィールドに注意してください。

部分取り込み トグルを使用すると、部分的なバッチ取り込みの使用を有効または無効にできます。

既存のデータフローの部分取り込みとエラー診断を有効にする

Experience Platformのデータフローが部分的な取り込みやエラー診断を有効にせずに作成された場合でも、フローを再作成しなくても、これらの機能を有効にすることができます。部分取り込みと堅牢なエラー診断を有効にすることで、データ取り込みワークフローにおける信頼性とトラブルシューティングの容易性を大幅に向上させることができます。 Flow Service APIを使用して既存のデータフローの部分取り込みとエラー診断を有効にする方法については、以下の節を参照してください。

デフォルトでは、データフローで部分的な取り込みやエラー診断が有効になっていない場合があります。これらの機能は、データの取り込み中に問題を特定し、分離するのに役立ちます。 Flow Service APIを使用すると、現在のデータフロー設定を取得し、PATCH リクエストを使用して必要な変更を適用できます。

既存のデータフローの部分取り込みとエラー診断を有効にするには、次の手順に従います。

フローの詳細の取得

データフロー設定を取得するには、/flows/{FLOW_ID} エンドポイントにGET リクエストを行い、データフローのIDを指定します。データフローの詳細の取得について詳しくは、 Flow Service API🔗 ガイドを使用したデータフローの更新を参照してください。

応答で返されるetag フィールドの値を必ず保存してください。これは、バージョンの一貫性を確保するために更新リクエストに必要です。

フロー設定の更新

次に、/flows/ エンドポイントに対してPATCH リクエストを行い、部分取り込みとエラー診断を有効にするデータフローのIDを指定します。

IMPORTANT

If-Match キーを使用して、以前に保存したetag値をリクエストヘッダーに含めます。
特定のニーズに合わせてpartialIngestionPercent値を変更できます。

API 形式

PATCH /flows/{FLOW_ID}

リクエスト

curl -X PATCH \
    'https://platform.adobe.io/data/foundation/flowservice/flows/2edc08ac-4df5-4fe6-936f-81a19ce92f5c' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {ORG_ID}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}'
    -H 'If-Match: "1a0037e4-0000-0200-0000-602e06f60000"' \
    -d '[
        {
            "op": "add",
            "path": "/options",
            "value": {
                "partialIngestionPercent": "10"
            }
        },
        {
            "op": "add",
            "path": "/options/errorDiagnosticsEnabled",
            "value": true
        }
    ]'

応答

応答が成功すると、データフローのidと更新されたetagが返されます。

{
    "id": "2edc08ac-4df5-4fe6-936f-81a19ce92f5c",
    "etag": "\"2c000802-0000-0200-0000-613976440000\""
}

更新を確認

PATCHが完了したら、GET リクエストを実行し、データフローを取得して、変更が正常に完了したことを確認します。

API 形式

GET /flows/{FLOW_ID}

リクエスト

次のリクエストでは、フロー ID に関する更新済み情報を取得します。

curl -X GET \
  'https://platform.adobe.io/data/foundation/flowservice/flows/2edc08ac-4df5-4fe6-936f-81a19ce92f5c' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

応答

応答が成功すると、データフローの詳細が返され、部分的な取り込みとエラー診断がoptions セクションで有効になっていることが確認されます。

"options": {
    "partialIngestionPercent": 10,
    "errorDiagnosticsEnabled": true
}

次の手順 next-steps

このチュートリアルでは、部分バッチ取り込みを有効にするデータセットの作成または変更方法について説明しました。バッチ取り込みについて詳しくは、バッチ取り込み開発者ガイドを参照してください。

部分取り込みエラーの監視について詳しくは、バッチ取り込みエラー診断ガイドを参照してください。

recommendation-more-help

experience-platform-help-ingestion

部分バッチ取り込み

はじめに

API 呼び出し例の読み取り

必須ヘッダーの値の収集

APIでバッチの一部を取り込むバッチを有効にする enable-api

UIでバッチの一部を取り込むバッチを有効にする enable-ui

新しいソース接続の作成 new-source

既存のデータセットを使用する existing-dataset

「CSVをXDM スキーマにマッピング ​」フローを使用 map-flow

既存のデータフローの部分取り込みとエラー診断を有効にする

フローの詳細の取得

フロー設定の更新

更新を確認

次の手順 next-steps

「CSVをXDM スキーマにマッピング」フローを使用 map-flow