ストリーミング取り込み検証

ストリーミング取り込みでは、ストリーミングエンドポイントを使用して、データをAdobe Experience Platformにリアルタイムでアップロードできます。 ストリーミング取得 API は、同期と非同期の 2 つの検証モードをサポートしています。

はじめに

このガイドは、Adobe Experience Platform の次のコンポーネントを実際に利用および理解しているユーザーを対象としています。

API 呼び出し例の読み取り

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

必須ヘッダーの値の収集

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

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

ペイロード（POST、PUT、PATCH）を含んだすべてのリクエストには、以下の追加ヘッダーが必要です。

検証の範囲

標準XDM イベントペイロードの場合、Streaming Validation Serviceは次の領域の検証をカバーします。

同期検証

同期検証は、取り込みが失敗した理由に関するフィードバックを即座に提供する検証方法です。 ただし、検証に失敗すると、検証に失敗したレコードは破棄され、ダウンストリームに送信されなくなります。 そのため、同期検証は開発プロセス中にのみ使用する必要があります。 同期検証をおこなうと、呼び出し元には、XDM 検証の結果が通知され、失敗した場合はさらに失敗の理由も通知されます。

デフォルトでは、同期検証はオンになっていません。 有効にするには、API 呼び出しをおこなう際に、オプションのクエリパラメーター syncValidation=true を渡す必要があります。 また、現時点では、同期検証は、ストリームエンドポイントが VA7 データセンターにある場合にのみ使用できます。

同期検証中にメッセージが失敗した場合、そのメッセージは出力キューに書き込まれず、ユーザーに対して即座にフィードバックが提供されます。

API 形式

POST /collection/{CONNECTION_ID}?syncValidation=true

リクエスト

同期検証を使用してデータをデータインレットに取り込むには、次のリクエストを送信します。

curl -X POST https://dcs.adobedc.net/collection/{CONNECTION_ID}?syncValidation=true \
  -H "Content-Type: application/json" \
  -d '{JSON_PAYLOAD}'

応答

同期検証が有効な場合、成功時の応答のペイロードには、検出された検証エラーが含まれています。

{
    "type": "http://ns.adobe.com/adobecloud/problem/data-collection-service/inlet",
    "status": 400,
    "title": "Invalid XDM Message Format",
    "report": {
        "message": "inletId: [6aca7aa2d87ebd6b2780ca5724d94324a14475f140a2b69373dd5c714430dfd4] imsOrgId: [7BF122A65C5B3FE40A494026@AdobeOrg] Message is invalid",
        "cause": {
            "_streamingValidation": [
                {
                    "schemaLocation": "#",
                    "pointerToViolation": "#",
                    "causingExceptions": [
                        {
                            "schemaLocation": "#",
                            "pointerToViolation": "#",
                            "causingExceptions": [],
                            "keyword": "additionalProperties",
                            "message": "extraneous key [workEmail] is not permitted"
                        },
                        {
                            "schemaLocation": "#",
                            "pointerToViolation": "#",
                            "causingExceptions": [],
                            "keyword": "additionalProperties",
                            "message": "extraneous key [person] is not permitted"
                        },
                        {
                            "schemaLocation": "#/properties/_id",
                            "pointerToViolation": "#/_id",
                            "causingExceptions": [],
                            "keyword": "type",
                            "message": "expected type: String, found: Long"
                        }
                    ],
                    "message": "3 schema violations found"
                }
            ]
        }
    }
}

上記の応答では、スキーマ違反の検出数と内容がリスト表示されます。 例えば、この応答では、キー workEmail と person がスキーマに定義されていないので使用できないということを述べています。 また、_id の値が正しくないとも警告しています。スキーマが string を想定していたにもかかわらず、実際には long が挿入されたからです。 5 つのエラーが発生すると、検証サービスはそのメッセージの処理を​ 停止 ​します。 ただし、他のメッセージは引き続き解析されます。

非同期検証

非同期検証は、即座にフィードバックを提供しない検証方法です。 代わりに、データが失われるのを防ぐために、Data Lakeで失敗したバッチにデータが送信されます。 この失敗したデータを、後で取得して、さらに分析と再現をおこなうことができます。 この方法は、本番環境で使用する必要があります。 特に要求されない限り、ストリーミング取り込みは非同期検証モードで動作します。

API 形式

POST /collection/{CONNECTION_ID}

リクエスト

非同期検証を使用してデータをデータインレットに取り込むには、次のリクエストを送信します。

curl -X POST https://dcs.adobedc.net/collection/{CONNECTION_ID} \
  -H "Content-Type: application/json" \
  -d '{JSON_PAYLOAD}'

応答

非同期検証が有効な場合、成功時の応答は以下を返します。

{
    "inletId": "f6ca9706d61de3b78be69e2673ad68ab9fb2cece0c1e1afc071718a0033e6877",
    "xactionId": "1555445493896:8600:8",
    "receivedTimeMs": 1555445493932,
    "syncValidation": {
        "skipped": true
    }
}

明示的に要求されていないので、同期検証がスキップされたことが応答に示されている点に注意してください。

付録

この節では、様々なステータスコードと、データ取り込みの応答での意味について説明します。

ステータスコード