単一のHTTP リクエストで複数のメッセージを送信する

Last update: Tue May 05 2026 00:00:00 GMT+0000 (Coordinated Universal Time)

トピック：
データ取り込み

作成対象：

開発者

データを Adobe Experience Platform にストリーミングする場合、多数の HTTP 呼び出しを作成すると高コストになる可能性があります。例えば、1 KB のペイロードで 200 個の HTTP リクエストを作成するよりも、それぞれが 1 KB の 200 個のメッセージが含まれた 1 個の HTTP リクエスト（200 KB の単一ペイロード）を作成する方がはるかに効率的です。 1回のリクエスト内で複数のメッセージをグループ化することは、データをExperience Platformに送信するように最適化する優れた方法です。

このドキュメントでは、ストリーミング取り込みを使用して、1つのHTTP リクエスト内でExperience Platformに複数のメッセージを送信する方法について説明します。

はじめに

このチュートリアルでは、Adobe Experience Platform Data Ingestionに関する実務的な理解が必要です。このチュートリアルを始める前に、次のドキュメントを確認してください。

データ取り込みの概要：取り込み方法とデータコネクタなど、Experience Platform Data Ingestionの主要な概念について説明します。
ストリーミング取り込みの概要: ストリーミング接続、データセット、XDM Individual Profile、XDM ExperienceEventなど、ストリーミング取り込みのワークフローと構成要素。

このチュートリアルでは、Experience Platform APIへの呼び出しを正常に行うには、Adobe Experience Platformへの認証チュートリアルを完了する必要もあります。認証に関するチュートリアルを完了すると、このチュートリアルで必要な認証ヘッダーの値が提供されます。このヘッダーは、サンプル呼び出しで次のように示されます。

Authorization: Bearer {ACCESS_TOKEN}

すべての POST リクエストには、次の追加ヘッダーが必要です。

Content-Type: application/json

ストリーミング接続の作成

Experience Platformへのデータのストリーミングを開始する前に、まずストリーミング接続を作成する必要があります。ストリーミング接続の作成方法については、ストリーミング接続の作成に関するガイドを参照してください。

ストリーミング接続を登録すると、データプロデューサーとして、Experience Platformにデータをストリーミングするために使用できる一意のURLが取得されます。

データセットへのストリーミング stream-to-dataset

次の例は、単一の HTTP リクエスト内で複数のメッセージを特定のデータセットに送信する方法を示しています。メッセージヘッダーにデータセット ID を挿入して、そのメッセージが直接取得されるようにします。

既存のデータセットのIDは、Experience Platform UIまたはAPIのリスト操作を使用して取得できます。データセット IDは、Experience Platformで見つけることができます。「Datasets」タブに移動し、IDを取得するデータセットをクリックして、Info タブの「データセット ID」フィールドから文字列をコピーします。 API を使用してデータセットを取得する方法については、「カタログサービスの概要」を参照してください。

既存のデータセットを使用する代わりに、新しいデータセットを作成できます。 API を使用してデータセットを作成する方法の詳細については、API を使用したデータセットの作成のチュートリアルを参照してください。

API 形式

POST /collection/batch/{CONNECTION_ID}

プロパティ

説明

{CONNECTION_ID}

作成したストリーミング接続の ID。

リクエスト

curl -X POST https://dcs.adobedc.net/collection/batch/{CONNECTION_ID} \
  -H 'Content-Type: application/json' \
  -d '{
  "messages": [
    {
      "header": {
        "schemaRef": {
          "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
          "contentType": "application/vnd.adobe.xed-full+json;version={SCHEMA_VERSION}"
        },
        "imsOrgId": "{ORG_ID}",
        "datasetId": "{DATASET_ID}",
        "createdAt": 1526283801869
      },
      "body": {
        "xdmMeta": {
          "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
            "contentType": "application/vnd.adobe.xed-full+json;version={SCHEMA_VERSION}"
          }
        },
        "xdmEntity": {
          "_id": "9af5adcc-db9c-4692-b826-65d3abe68c22",
          "timestamp": "2019-02-23T22:07:01Z",
          "environment": {
            "browserDetails": {
              "userAgent": "Mozilla/5.0 (Windows NT 5.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/29.0.1547.57 Safari/537.36 OPR/16.0.1196.62",
              "acceptLanguage": "en-US",
              "cookiesEnabled": true,
              "javaScriptVersion": "1.6",
              "javaEnabled": true
            },
            "colorDepth": 32,
            "viewportHeight": 799,
            "viewportWidth": 414
          },
          "productListItems": [
            {
              "SKU": "CC",
              "name": "Fernie Snow",
              "quantity": 30,
              "priceTotal": 7.8
            }
          ],
          "commerce": {
            "productViews": {
              "value": 1
            }
          },
          "_experience": {
            "campaign": {
              "message": {
                "profileSnapshot": {
                  "workEmail": {
                    "address": "gregdorcey@example.com"
                  }
                }
              }
            }
          }
        }
      }
    },
    {
      "header": {
        "schemaRef": {
          "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
          "contentType": "application/vnd.adobe.xed-full+json;version={SCHEMA_VERSION}"
        },
        "imsOrgId": "{ORG_ID}",
        "datasetId": "{DATASET_ID}",
        "createdAt": 1526283801869
      },
      "body": {
        "xdmMeta": {
          "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
            "contentType": "application/vnd.adobe.xed-full+json;version={SCHEMA_VERSION}"
          }
        },
        "xdmEntity": {
          "_id": "7af6adcc-dc9e-4692-b826-55d2abe68c11",
          "timestamp": "2019-02-23T22:07:31Z",
          "environment": {
            "browserDetails": {
              "userAgent": "Mozilla/5.0 (Windows NT 5.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/29.0.1547.57 Safari/537.36 OPR/16.0.1196.62",
              "acceptLanguage": "en-US",
              "cookiesEnabled": true,
              "javaScriptVersion": "1.6",
              "javaEnabled": true
            },
            "colorDepth": 32,
            "viewportHeight": 799,
            "viewportWidth": 414
          },
          "productListItems": [
            {
              "SKU": "CC",
              "name": "Carmine Santiago",
              "quantity": 10,
              "priceTotal": 5.5
            }
          ],
          "commerce": {
            "productViews": {
              "value": 1
            }
          },
          "_experience": {
            "campaign": {
              "message": {
                "profileSnapshot": {
                  "workEmail": {
                    "address": "emilyong@example.com"
                  }
                }
              }
            }
          }
        }
      }
    }
  ]
}'

応答

成功した応答は、HTTP ステータス 207 （マルチステータス）を返します。応答の本文では、リクエストで実行された各メソッドの成功または失敗に関する詳細を確認できます。リクエストメッセージ配列の各要素に対して応答が返されます。メッセージにエラーが発生しなかった、成功した応答の例を次に示します。

{
    "inletId": "9b0cb233972f3b0092992284c7353f5eead496218e8441a79b25e9421ea127f5",
    "batchId": "1565628583792:1485:153",
    "receivedTimeMs": 1565628583854,
    "responses": [
        {
            "xactionId": "1565628583792:1485:153:0"
        },
        {
            "xactionId": "1565628583792:1485:153:1"
        }
    ]
}

ステータスコードの詳細については、このチュートリアルの付録にある「応答コード」の表を参照してください。

失敗したメッセージの識別

単一のメッセージが含まれるリクエストを送信する場合とは異なり、複数のメッセージが含まれる HTTP リクエストを送信する場合は、データの送信に失敗した日時を識別する方法、送信に失敗した特定のメッセージの識別とその取得方法、同じリクエスト内の他のメッセージが失敗した場合に成功したデータに何が起こるかなど、追加の要素を考慮する必要があります。

このチュートリアルを進める前に、失敗したバッチの取得に関するガイドを確認することをお勧めします。

有効なメッセージと無効なメッセージを含むリクエストペイロードの送信

次の例は、バッチに有効なメッセージと無効なメッセージが含まれる場合の動作を示しています。

リクエストペイロードは、XDM スキーマのイベントを表す JSON オブジェクトの配列です。メッセージの検証を正しくおこなうには、次の条件が満たされている必要があります。

メッセージヘッダーの imsOrgId フィールドは、インレット定義と一致する必要があります。リクエストペイロードにimsOrgId フィールドが含まれていない場合、Data Collection Core Service （DCCS）はフィールドを自動的に追加します。
メッセージのヘッダーは、Experience Platform UIで作成された既存のXDM スキーマを参照する必要があります。
datasetId フィールドはExperience Platformの既存のデータセットを参照する必要があり、そのスキーマは、リクエスト本文に含まれる各メッセージ内のheader オブジェクトで提供されるスキーマと一致する必要があります。

API 形式

POST /collection/batch/{CONNECTION_ID}

プロパティ

説明

{CONNECTION_ID}

作成したデータインレットの ID。

リクエスト

curl -X POST https://dcs.adobedc.net/collection/batch/{CONNECTION_ID} \
  -H 'Content-Type: application/json' \
  -d '{
  "messages": [
    {
      "header": {
        "schemaRef": {
          "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
          "contentType": "application/vnd.adobe.xed-full+json;version={SCHEMA_VERSION}"
        },
        "imsOrgId": "{ORG_ID}",
        "datasetId": "{DATASET_ID}",
        "createdAt": 1526283801869
      },
      "body": {
        "xdmMeta": {
          "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
            "contentType": "application/vnd.adobe.xed-full+json;version={SCHEMA_VERSION}"
          }
        },
        "xdmEntity": {
          "_id": "9af5adcc-db9c-4692-b826-65d3abe68c22",
          "timestamp": "2019-02-23T22:07:01Z",
          "environment": {
            "browserDetails": {
              "userAgent": "Mozilla/5.0 (Windows NT 5.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/29.0.1547.57 Safari/537.36 OPR/16.0.1196.62",
              "acceptLanguage": "en-US",
              "cookiesEnabled": true,
              "javaScriptVersion": "1.6",
              "javaEnabled": true
            },
            "colorDepth": 32,
            "viewportHeight": 799,
            "viewportWidth": 414
          },
          "productListItems": [
            {
              "SKU": "CC",
              "name": "Tip Top Collection",
              "quantity": 15,
              "priceTotal": 9.5
            }
          ],
          "commerce": {
            "productViews": {
              "value": 1
            }
          },
          "_experience": {
            "campaign": {
              "message": {
                "profileSnapshot": {
                  "workEmail": {
                    "address": "rogerkanagawa@example.com"
                  }
                }
              }
            }
          }
        }
      }
    },
    {
      "header": {
        "schemaRef": {
          "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
          "contentType": "application/vnd.adobe.xed-full+json;version={SCHEMA_VERSION}"
        },
        "imsOrgId": "{ORG_ID}",
        "datasetId": "{DATASET_ID}",
        "createdAt": 1526283801869
      }
    },
    {
      "header": {
        "schemaRef": {
          "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
          "contentType": "application/vnd.adobe.xed-full+json;version={SCHEMA_VERSION}"
        },
        "imsOrgId": "invalidIMSOrg@AdobeOrg",
        "datasetId": "{DATASET_ID}",
        "createdAt": 1526283801869
      },
      "body": {
        "xdmMeta": {
          "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
            "contentType": "application/vnd.adobe.xed-full+json;version={SCHEMA_VERSION}"
          }
        },
        "xdmEntity": {
          "_id": "9af5adcc-db9c-4692-b826-65d3abe68c22",
          "timestamp": "2019-02-23T22:07:01Z",
          "environment": {
            "browserDetails": {
              "userAgent": "Mozilla/5.0 (Windows NT 5.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/29.0.1547.57 Safari/537.36 OPR/16.0.1196.62",
              "acceptLanguage": "en-US",
              "cookiesEnabled": true,
              "javaScriptVersion": "1.6",
              "javaEnabled": true
            },
            "colorDepth": 32,
            "viewportHeight": 799,
            "viewportWidth": 414
          },
          "productListItems": [
            {
              "SKU": "CC",
              "name": "Carmine Santiago",
              "quantity": 10,
              "priceTotal": 5.5
            }
          ],
          "commerce": {
            "productViews": {
              "value": 1
            }
          },
          "_experience": {
            "campaign": {
              "message": {
                "profileSnapshot": {
                  "workEmail": {
                    "address": "mohandeewar@example.com"
                  }
                }
              }
            }
          }
        }
      }
    },
   {
      "header": {
        "schemaRef": {
          "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
          "contentType": "application/vnd.adobe.xed-full+json;version={SCHEMA_VERSION}"
        },
        "imsOrgId": "{ORG_ID}",
        "datasetId": "{DATASET_ID}",
        "createdAt": 1526283801869
      },
      "body": {
        "xdmMeta": {
          "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
            "contentType": "application/vnd.adobe.xed-full+json;version={SCHEMA_VERSION}"
          }
        },
        "xdmEntity": {
          "_id": "9af5adcc-db9c-4692-b826-65d3abe68c22",
          "timestamp": "2019-02-23T22:07:01Z",
          "environment": {
            "browserDetails": {
              "userAgent": "Mozilla/5.0 (Windows NT 5.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/29.0.1547.57 Safari/537.36 OPR/16.0.1196.62",
              "acceptLanguage": "en-US",
              "cookiesEnabled": true,
              "javaScriptVersion": "1.6",
              "javaEnabled": true
            },
            "colorDepth": 32,
            "viewportHeight": 799,
            "viewportWidth": 414
          },
          "productListItems": [
            {
              "SKU": "CC",
              "name": "Tip Top Collection",
              "quantity": 15,
              "priceTotal": 9.5
            }
          ],
          "commerce": {
            "productViews": {
              "value": 1
            }
          }
        }
      }
    },
    {
      "header": {
        "msgType": "xdmEntityCreate",
        "msgId": "79d2e715-f25f-4c36",
        "xdmSchema": {
          "name": "_xdm.context.experienceevent"
        },
        "imsOrgId": "{ORG_ID}",
        "datasetId": "{DATASET_ID}",
        "createdAt": 1526283801869
      },
      "body": {
        "xdmMeta": {
          "xdmSchema": {
            "name": "_xdm.context.experienceevent"
          }
        },
        "xdmEntity": {
          "_id": "abc",
          "dataSource": {
            "_id": "http://abc.com/abc"
          },
          "timestamp": "2018-05-18T15:28:25Z",
          "endUserIDs": {
            "_vendor": {
              "adobe": {
                "experience": {
                  "mcId": {
                    "id": "http://abc.com/abc"
                  }
                }
              }
            }
          }
        }
      }
    }
  ]
}'

応答

リクエストペイロードには、各メッセージのステータスに加えて、トレースに使用できる xactionId の GUID が含まれます。

{
    "inletId": "9b0cb233972f3b0092992284c7353f5eead496218e8441a79b25e9421ea127f5",
    "batchId": "1565638336649:1750:244",
    "receivedTimeMs": 1565638336705,
    "responses": [
        {
            "xactionId": "1565650704337:2124:92:3"
        },
        {
            "statusCode": 400,
            "message": "inletId: [9b0cb233972f3b0092992284c7353f5eead496218e8441a79b25e9421ea127f5] imsOrgId: [{ORG_ID}] Message has unknown xdm format"
        },
        {
            "statusCode": 400,
            "message": "inletId: [9b0cb233972f3b0092992284c7353f5eead496218e8441a79b25e9421ea127f5] imsOrgId: [{ORG_ID}] Message has an absent or wrong ims org in the header"
        },
        {
            "statusCode": 400,
            "message": "inletId: [9b0cb233972f3b0092992284c7353f5eead496218e8441a79b25e9421ea127f5] imsOrgId: [{ORG_ID}] Message has unknown xdm format"
        }
    ]
}

上記の応答例は、前のリクエストのエラーメッセージを示しています。この応答を以前の有効な応答と比較すると、リクエストが部分的に成功し、1 つのメッセージが正常に取得され、3 つのメッセージが失敗したことがわかります。どちらの応答も「207」ステータスコードを返していることに注意してください。ステータスコードの詳細については、このチュートリアルの付録にある「応答コード」の表を参照してください。

最初のメッセージはExperience Platformに正常に送信され、他のメッセージの結果の影響を受けません。そのため、失敗したメッセージを再送信する場合は、このメッセージを再度含める必要はありません。

2 番目のメッセージは、メッセージの本文がないため失敗しました。コレクションリクエストでは、メッセージ要素に有効なヘッダーセクションと本文セクションが含まれている必要があります。 2 番目のメッセージのヘッダーの後に次のコードを追加すると、リクエストが修正され、2 番目のメッセージが検証に合格するようになります。

      "body": {
        "xdmMeta": {
          "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
            "contentType": "application/vnd.adobe.xed-full+json;version={SCHEMA_VERSION}"
          }
        },
        "xdmEntity": {
          "_id": "9af5adcc-db9c-4692-b826-65d3abe68c22",
          "timestamp": "2019-02-23T22:07:01Z",
        }
    },

ヘッダーで無効な組織IDが使用されているため、3番目のメッセージは失敗しました。組織は、投稿しようとしている{CONNECTION_ID}と一致する必要があります。使用しているストリーミング接続と一致する組織IDを判断するには、Streaming Ingestion APIを使用してGET inlet リクエストを実行できます。以前に作成したストリーミング接続の取得方法の例については、ストリーミング接続の取得に関する節を参照してください。

4 番目のメッセージは、予期された XDM スキーマに従わなかったため失敗しました。リクエストのヘッダーと本文に含まれる xdmSchema が、{DATASET_ID} の XDM スキーマと一致していません。メッセージヘッダーと本文のスキーマを修正すると、DCCS検証を渡してExperience Platformに正常に送信できます。 Experience Platformでストリーミング検証を渡すには、メッセージ本文を更新して{DATASET_ID}のXDM スキーマと一致させる必要があります。 Experience Platformに正常にストリーミングされたメッセージの詳細については、このチュートリアルの「取り込まれたメッセージの確認」セクションを参照してください。

Experience Platformから失敗したメッセージを取得

失敗したメッセージは、応答配列のエラーステータスコードで識別されます。
無効なメッセージは、{DATASET_ID} で指定されたデータセット内の「エラー」バッチに収集および格納されます。

失敗したバッチメッセージの回復の詳細については、失敗したバッチの取得に関するガイドを参照してください。

複数のXDM エンティティをデータフローに送信する send-multiple-xdm-entities-to-a-dataflow

複数のXDM エンティティをデータフローに送信するには、次のいずれかを実行できます。

1つのHTTP リクエスト内のmessages配列内の1つ以上のエンティティをストリーミングエンドポイントに送信します。
バッチ取り込みを使用して、複数のエンティティを持つファイルをアップロードします。

データ量とユースケースに合わせた方法を選択します。

HTTP リクエスト内のエンティティをグループ化

ストリーミング取り込みエンドポイントに対する1つのHTTP リクエスト内のmessages配列に複数のXDM エンティティを含めることができます。すべてのメッセージは、same組織とサンドボックスに属している限り、同じまたは異なるデータセットとスキーマをターゲットにできます。

このオプションは、次の場合に使用します。

1つのHTTP呼び出しで複数のXDM エンティティを送信することで、リクエストを削減します。
取り込みエンドポイントを通じて、データをリアルタイムでストリーミングします。

リクエストの送信方法について詳しくは、「データセットへのストリーミング」の節を参照してください。

バッチファイルをアップロード

1つ以上のXDM エンティティを含むバッチファイルをデータフローにアップロードできます。同じバッチでアップロードされたすべてのファイルは、単一の取り込み単位として処理されます。

この方法は、次の場合に使用します。

大きなデータボリューム（CSV、JSON、Parquet ファイルなど）を取り込みます。
アップストリームシステムからのファイルベースの書き出しを操作しています。
スケジュール済みまたは一括取り込みを好む。

ステップバイステップの手順については、バッチ取り込みガイドを参照してください。

取得したメッセージの確認

DCCS検証に合格したメッセージはExperience Platformにストリーミングされます。 Experience Platformでは、バッチメッセージは、Data Lakeに取り込まれる前にストリーミング検証によってテストされます。バッチのステータスは、成功したかどうかに関わらず、{DATASET_ID} で指定されたデータセット内に表示されます。

Experience Platform UIを使用してExperience Platformへのストリーミングに成功したバッチメッセージのステータスを表示するには、Datasets タブに移動し、ストリーミング先のデータセットをクリックして、Dataset Activity タブを確認します。

Experience Platformでストリーミング検証に合格したバッチメッセージは、Data Lakeに取り込まれます。その後、メッセージを分析または書き出しすることができます。

次の手順

1回のリクエストで複数のメッセージを送信し、メッセージがターゲットデータセットに正常に取り込まれたかどうかを確認する方法を理解したので、独自のデータをExperience Platformにストリーミングできます。 Experience Platformから取り込んだデータをクエリおよび取得する方法の概要については、Data Access ガイドを参照してください。

付録

この節では、このチュートリアルの補足情報を提供します。

応答コード

次の表に、成功した応答メッセージと失敗した応答メッセージによって返されるステータスコードを示します。

ステータスコード

説明

207

'207'は全体的な応答ステータスコードとして使用されますが、受信者は、メソッド実行の成功または失敗に関する詳細な情報を得るために、マルチステータス応答本文の内容を参照する必要があります。この応答コードは、成功や部分的な成功のほか、失敗した状況でも使用されます。

400

リクエストに問題がありました。より具体的なエラーメッセージ（例えば、メッセージペイロードに必須フィールドがなかった、またはメッセージが不明な XDM 形式だった）については、応答の本文を参照してください。

401

未認証：リクエストに有効な認証ヘッダーがありません。このコードは、認証が有効になっているインレットのみに対して返されます。

403

未認証：指定された認証トークンが無効か期限切れです。このコードは、認証が有効になっているインレットのみに対して返されます。

413

ペイロードが大きすぎる：ペイロードリクエストの合計が 1 MB を超えた場合に返されます。

429

指定された期間内のリクエストが多すぎます。

500

ペイロードの処理中にエラーが発生しました。より具体的なエラーメッセージについては、応答本文を参照してください（例えば、メッセージペイロードスキーマが指定されていないか、Experience PlatformのXDM定義と一致しませんでした）。

503

サービスは現在利用できません。クライアントは、指数バックオフ戦略を使用して、少なくとも 3 回再試行する必要があります。

recommendation-more-help

2ee14710-6ba4-4feb-9f79-0aad73102a9a