Real-Time Customer Profileを使用して行の部分的な更新をData Prepに送信します
-
DCS インレットを介したプロファイル更新のExperience Data Model （XDM） Entity Update メッセージ（JSON PATCH操作を含む）の取り込みは非推奨になりました。 代替案として、このガイドで説明した手順に従ってください。
-
また、HTTP API ソースを使用して生データをDCS インレット に取り込み、必要なデータマッピングを指定して、データをXDM準拠のメッセージに変換してプロファイルを更新することもできます。
-
ストリーミングアップサートで配列を使用する場合、操作の明確な意図を定義するために
upsert_array_appendまたはupsert_array_replaceを明示的に使用する必要があります。 これらの関数が見つからない場合は、エラーが発生する可能性があります。
Data Prepでのストリーミングアップサートを使用して、部分的な行の更新をReal-Time Customer Profile データに送信すると同時に、単一のAPI リクエストで新しいID リンクを作成および確立します。
アップサートをストリーミングすることで、取り込み中にデータをReal-Time Customer Profile件のPATCH リクエストに変換する際に、データのフォーマットを保持できます。 入力に基づいて、Data Prepでは、1つのAPI ペイロードを送信し、データをReal-Time Customer Profile個のPATCHとIdentity Service個のCREATE リクエストの両方に変換できます。
Data Prepは、挿入とアップサートを区別するためにヘッダーパラメーターを使用します。 アップサートを使用するすべての行にはヘッダーが必要です。 ID記述子の有無にかかわらずアップサートを使用できます。 IDを持つアップサートを使用する場合は、ID データセットの設定の節で説明されている設定手順に従う必要があります。 IDなしでアップサートを使用している場合は、リクエストでID設定を指定する必要はありません。 詳しくは、IDを持たないアップサートのストリーミング に関する節を参照してください。
このドキュメントでは、Data Prepでアップサートをストリーミングする方法について説明します。
はじめに
この概要では、Adobe Experience Platform の次のコンポーネントに関する十分な知識が必要です。
- Data Prep: Data Prepを使用すると、データ エンジニアはExperience Data Model （XDM）との間でデータをマッピング、変換、検証できます。
- Identity Service: デバイスとシステム間でIDを橋渡しすることで、個々の顧客とその行動をより詳細に把握します。
- リアルタイム顧客プロファイル：複数のソースから集約されたデータに基づいて、統合された顧客プロファイルをリアルタイムに提供します。
- ソース : Experience Platformを使用すると、様々なソースからデータを取り込むことができますが、Experience Platform サービスを使用して着信データを構造化、ラベル付け、強化することができます。
Data Prepでのストリーミングアップサートの使用 streaming-upserts-in-data-prep
ストリーミングアップサートの上位レベルのワークフロー
Data Prepのストリーミングアップサートは次のように機能します。
-
最初に、Profileの使用に対してデータセットを作成し、有効にする必要があります。 詳しくは、のデータセットを有効にする Profileに関するガイドを参照してください。
-
新しいIDをリンクする必要がある場合は、データセットと同じスキーマを使用して、追加のデータセット Profileも作成する必要があります。
-
データセットを準備したら、受信リクエストをProfile データセットにマッピングするためのデータフローを作成する必要があります。
-
次に、必要なヘッダーを含めるように、受信リクエストを更新する必要があります。 これらのヘッダーは次のように定義します。
- Profileで実行する必要があるデータ操作：
create、merge、およびdelete。 - Identity Serviceで実行するオプション ID操作：
create。
- Profileで実行する必要があるデータ操作：
ID データセットの設定 configure-the-identity-dataset
新しいIDをリンクする必要がある場合は、追加のデータセットを作成して受信ペイロードに渡す必要があります。 ID データセットを作成する場合は、次の要件が満たされていることを確認する必要があります。
- ID データセットには、Profile データセットとして関連付けられたスキーマが必要です。 スキーマの不一致は、システム動作の一貫性を損なう可能性があります。
- ただし、ID データセットがProfile データセットと異なることを確認する必要があります。 データセットが同じ場合、データは更新されずに上書きされます。
- Profileに対して初期データセットを有効にする必要がありますが、に対してID データセットを有効にすることはできませんProfile。 そうでない場合は、データも更新されずに上書きされます。 ただし、に対してID データセットを有効にする必要がありますIdentity Service。
ID データセットに関連付けられたスキーマの必須フィールド identity-dataset-required-fileds
スキーマに必須フィールドが含まれている場合、Identity ServiceがIDのみを受信できるようにするには、データセットの検証を抑制する必要があります。 disabled値をacp_validationContext パラメーターに適用することで、検証を抑制できます。 次の例を参照してください。
curl -X POST 'https://platform.adobe.io/data/foundation/catalog/dataSets/62257bef7a75461948ebcaaa' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"tags": {
"acp_validationContext": [
"disabled"
],
"unifiedProfile": [
"enabled:false"
],
"unifiedIdentity": [
"enabled:true"
]
}
}'
受信ペイロード構造
次に、新しいID リンクを確立する受信ペイロード構造の例を示します。
ID設定を使用したペイロード
{
"header": {
"flowId": "923e2ac3-3869-46ec-9e6f-7012c4e23f69",
"imsOrgId": "{ORG_ID}",
"datasetId": "621fc19ab33d941949af16c8",
"operations": {
"data": "create" (default)/"merge"/"delete",
"identity": "create",
"identityDatasetId": "621fc19ab33d941949af16d9"
}
}
... //The raw data attributes are included here as the key/value pairs of the "body" property.
}
flowIddatasetId パラメーターとしても使用されます。imsOrgIddatasetIdoperationsoperations.dataoperations.identityoperations.identityDatasetIdサポートされる操作
次の操作はReal-Time Customer Profileによってサポートされています：
createmergedelete次の操作はIdentity Serviceによってサポートされています：
createcreateがoperations.identityの値として渡された場合、Data PrepはIdentity Serviceに対するXDM エンティティ作成リクエストを生成します。 IDが既に存在する場合、そのIDは無視されます。 メモ： operations.identityがcreateに設定されている場合は、identityDatasetIdも指定する必要があります。 Data Prep コンポーネントによって内部で生成されたXDM エンティティ作成メッセージは、このデータセット IDに対して生成されます。ID設定のないペイロード payload-without-identity-configuration
新しいIDをリンクする必要がない場合は、操作でidentityとidentityDatasetIdのパラメーターを省略できます。 これにより、データはReal-Time Customer Profileにのみ送信され、Identity Serviceはスキップされます。 例については、以下のペイロードを参照してください。
{
"header": {
"flowId": "923e2ac3-3869-46ec-9e6f-7012c4e23f69",
"imsOrgId": "{ORG_ID}",
"datasetId": "621fc19ab33d941949af16c8",
"operations": {
"data": "create"/"merge"/"delete",
}
}
... //The raw data attributes are included here as the key/value pairs of the "body" property.
}
プライマリ IDを動的に渡す
XDMを更新するには、スキーマをProfileに対して有効にし、プライマリ IDを含める必要があります。 XDM スキーマのプライマリ IDは、次の2つの方法で指定できます。
- XDM スキーマのプライマリ IDとして静的フィールドを指定します。
- XDM スキーマのID マップフィールドグループを使用して、いずれかのID フィールドをプライマリ IDとして指定します。
静的フィールドをXDM スキーマのプライマリ ID フィールドとして指定します
次の例では、state、homePhone.numberおよびその他の属性が、それぞれ指定された値でProfileに挿入され、プライマリ IDがsampleEmail@gmail.comになります。 次に、ストリーミング Data Prep コンポーネントによってXDM エンティティの更新メッセージが生成されます。 次に、Real-Time Customer Profileは、プロファイルレコードをアップサートするためのXDM更新メッセージを確認します。
curl -X POST 'https://dcs.adobedc.net/collection/9aba816d350a69c4abbd283eb5818ec3583275ffce4880ffc482be5a9d810c4b' \
-H 'Content-Type: application/json' \
-H 'x-adobe-flow-id: d5262d48-0f47-4949-be6d-795f06933527' \
-d '{
"header": {
"flowId" : "d5262d48-0f47-4949-be6d-795f06933527",
"imsOrgId": "{ORG_ID}",
"datasetId": "62259f817f62d71947929a7b",
"operations": {
"data": "create"
}
},
{
"body": {
"homeAddress": {
"country": "US",
"state": "GA",
"region": "va7"
},
"homePhone": {
"number": "123.456.799"
},
"identityMap": {
"Email": [{
"id": "sampleEmail@gmail.com",
"primary": true
}]
},
"personalEmail": {
"address": "sampleEmail@gmail.com",
"primary": true
},
"personID": "346576345",
"_id": "346576345",
"timestamp": "2021-05-05T17:51:45.1880+02",
"workEmail": "sampleWorkEmail@gmail.com"
}
}'
XDM スキーマのID マップフィールドグループを使用して、いずれかのID フィールドをプライマリ IDとして指定します
この例では、ヘッダーにoperationsおよびidentity プロパティを持つidentityDatasetId属性が含まれています。 これにより、データをReal-Time Customer Profileと結合したり、IDをIdentity Serviceに渡したりできます。
curl -X POST 'https://dcs.adobedc.net/collection/9aba816d350a69c4abbd283eb5818ec3583275ffce4880ffc482be5a9d810c4b' \
-H 'Content-Type: application/json' \
-H 'x-adobe-flow-id: d5262d48-0f47-4949-be6d-795f06933527' \
-d '{
"header": {
"flowId" : "d5262d48-0f47-4949-be6d-795f06933527",
"imsOrgId": "{ORG_ID}",
"datasetId": "62259f817f62d71947929a7b",
"operations": {
"data": "merge",
"identity": "create",
"identityDatasetId": "6254a93b851ecd194b64af9e"
}
},
{
"body": {
"homeAddress": {
"country": "US",
"state": "GA",
"region": "va7"
},
"homePhone": {
"number": "123.456.799"
},
"identityMap": {
"Email": [{
"id": "sampleEmail@gmail.com",
"primary": true
}]
},
"personalEmail": {
"address": "sampleEmail@gmail.com",
"primary": true
},
"personID": "346576345",
"_id": "346576345",
"timestamp": "2021-05-05T17:51:45.1880+02",
"workEmail": "sampleWorkEmail@gmail.com"
}
}'
既知の制限事項と主な考慮事項
次に、Data Prepを使用してアップサートをストリーミングする際に考慮すべき既知の制限事項のリストを示します。
- ストリーミングアップサートメソッドは、部分的な行の更新をReal-Time Customer Profileに送信する場合にのみ使用する必要があります。 一部の行の更新は、データレイクで使用される not です。
- ストリーミングアップサートメソッドでは、IDの更新、置換、削除はサポートされていません。 存在しない場合は、新しいIDが作成されます。 したがって、
identity操作は常に作成するように設定する必要があります。 IDが既に存在する場合、操作はno-opです。 - 現在、ストリーミングアップサートメソッドは、Adobe Experience Platform Web SDKまたはAdobe Experience Platform Mobile SDKをサポートしていません。
次の手順
このドキュメントを読むことで、1つのAPI リクエストでIDを作成およびリンクしながら、Data PrepでアップサートをストリーミングしてReal-Time Customer Profile データに部分的な行の更新を送信する方法を理解できるようになりました。 その他Data Prep機能について詳しくは、Data Prep 概要を参照してください。 Data Prep API内でマッピングセットを使用する方法については、Data Prep 開発者ガイド を参照してください。