使用Data Prep傳送部分資料列更新至Real-Time Customer Profile

Last update: Fri Aug 09 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

主題：
資料準備

建立對象：

開發人員

IMPORTANT

已棄用透過DCS入口擷取用於設定檔更新的體驗資料模型(XDM)實體更新訊息(含JSONPATCH作業)。作為替代方法，請遵循本指南中概述的步驟。
您也可以使用HTTP API來源來將原始資料擷取到DCS入口，並指定必要的資料對應，以將您的資料轉換為符合XDM規範的訊息以進行設定檔更新。
在串流更新插入中使用陣列時，您必須明確使用upsert_array_append或upsert_array_replace來定義作業的明確目的。如果缺少這些函式，您可能會收到錯誤。

在Data Prep中使用串流更新插入，傳送部分資料列更新至Real-Time Customer Profile資料，同時透過單一API要求建立和建立新的身分連結。

透過串流更新插入，您可以在擷取期間將該資料轉譯為Real-Time Customer Profile個PATCH請求時保留資料格式。根據您提供的輸入，Data Prep可讓您傳送單一API裝載，並將資料轉譯為Real-Time Customer ProfilePATCH和Identity Service建立要求。

Data Prep使用標頭引數來區分插入和更新插入。所有使用更新插入的列都必須有標題。您可以使用包含或不包含身分描述元的更新插入。如果您使用含身分的upsert，您必須遵循設定身分資料集一節中概述的設定步驟。如果您使用沒有身分的upsert，則不需要在請求中提供身分設定。如需詳細資訊，請閱讀不含身分的串流更新插入的區段。

NOTE

若要利用更新插入功能，建議您在資料擷取期間關閉XDM相容的設定，並使用資料準備對應程式重新對應傳入裝載。

本檔案提供如何在Data Prep中串流更新插入的資訊。

快速入門

此概覽需要深入瞭解下列Adobe Experience Platform元件：

Data Prep： Data Prep可讓資料工程師對應、轉換及驗證與Experience Data Model (XDM)之間的資料。
Identity Service：跨裝置和系統橋接身分，以更清楚瞭解個別客戶及其行為。
即時客戶個人檔案：根據來自多個來源的彙總資料，即時提供統一的客戶個人檔案。
來源：Experience Platform允許從各種來源擷取資料，同時讓您能夠使用Platform服務來建構、加標籤以及增強傳入的資料。

在Data Prep中使用串流更新插入 streaming-upserts-in-data-prep

NOTE

下列來源支援使用串流更新插入：

串流更新插入高階工作流程

Data Prep中的串流更新插入的運作方式如下：

您必須先建立並啟用Profile使用量的資料集。如需詳細資訊，請參閱啟用 Profile的資料集指南。
如果新身分必須連結，則您也必須建立其他資料集 ，其結構描述 與您的Profile資料集相同。
準備好資料集後，您必須建立資料流，將傳入的請求對應至Profile資料集；
接下來，您必須更新傳入請求以包含必要的標頭。這些標頭會定義：
- 需要對Profile執行的資料操作： create、merge和delete。
- 要與Identity Service一起執行的選擇性身分作業： create。

設定身分資料集 configure-the-identity-dataset

如果新身分必須連結，則您必須在傳入裝載中建立並傳遞額外的資料集。建立身分資料集時，您必須確保符合下列需求：

身分資料集必須具有關聯的結構描述做為Profile資料集。結構描述不相符可能會導致不一致的系統行為。
不過，您必須確保身分資料集與Profile資料集不同。如果資料集相同，則會覆寫資料而非更新資料。
雖然必須為Profile啟用初始資料集，但身分資料集 不應為Profile啟用。否則，也會覆寫資料，而非更新資料。但是，應該為Identity Service啟用身分資料集。

與身分資料集相關聯之結構描述中的必填欄位 identity-dataset-required-fileds

如果您的結構描述包含必填欄位，則必須隱藏資料集的驗證，以允許Identity Service僅接收身分識別。您可以將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"
        ]
    }
}'

TIP

如果與身分資料集相關聯的結構描述沒有任何必填欄位，則不需要進行任何其他設定。

傳入裝載結構

以下顯示可建立新身分連結之傳入裝載結構的範例。

具有身分設定的裝載

{
  "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.
}

參數

說明

flowId

用於識別資料流的唯一ID。此資料流ID應該對應到使用Amazon Kinesis、Azure Event Hubs或HTTP API建立的來源連線。此資料流也應該有Profile啟用的資料集作為目標資料集。注意：已啟用Profile的目標資料集的識別碼也會當作您的datasetId引數使用。

imsOrgId

與您的組織相對應的ID。

datasetId

您的資料流已啟用Profile的目標資料集識別碼。注意：此ID與您資料流中具有Profile功能的目標資料集ID相同。

operations

此引數概述Data Prep根據傳入的請求將採取的動作。

operations.data

定義必須在Real-Time Customer Profile中執行的動作。

operations.identity

定義Identity Service允許對資料執行的作業。

operations.identityDatasetId

（選用）只有在必須連結新身分時才需要身分資料集的ID。

支援的作業

Real-Time Customer Profile支援下列作業：

運作

說明

create

預設操作。這會為Real-Time Customer Profile產生XDM實體建立方法。

merge

這會產生Real-Time Customer Profile的XDM實體更新方法。

delete

這會產生Real-Time Customer Profile的XDM實體刪除方法，並從Profile store永久移除資料。

Identity Service支援下列作業：

運作

說明

create

此引數唯一允許的作業。如果create傳遞為operations.identity的值，則Data Prep會產生Identity Service的XDM實體建立請求。如果身分已經存在，則會忽略身分。 注意： 如果operations.identity設定為create，則必須同時指定identityDatasetId。將針對此資料集ID產生由Data Prep元件內部產生的XDM實體建立訊息。

沒有身分設定的裝載 payload-without-identity-configuration

如果新身分不需要連結，則您可以在操作中省略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.
}

動態傳遞主要身分

針對XDM更新，結構描述必須啟用Profile並包含主要身分。您可以透過兩種方式指定XDM結構描述的主要身分：

在XDM結構中指定一個靜態欄位作為主要身分；
透過XDM結構描述中的身分對應欄位群組，將其中一個身分欄位指定為主要身分。

將靜態欄位指定為XDM結構描述中的主要身分欄位

在下列範例中，state、homePhone.number和其他屬性會以其各自的指定值更新插入Profile，主要識別碼為sampleEmail@gmail.com。然後，串流Data Prep元件會產生XDM實體更新訊息。 Real-Time Customer Profile接著確認XDM更新訊息以更新插入設定檔記錄。

NOTE

在此範例中，身分將不會連結在一起，因為沒有定義身分的操作。

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結構描述中的身分對應欄位群組，將其中一個身分欄位指定為主要身分

在此範例中，標頭包含具有identity和identityDatasetId屬性的operations屬性。這允許資料與Real-Time Customer Profile合併，也允許將身分傳遞給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時，才應該使用串流更新插入方法。部分資料列更新不是由資料湖使用。
串流更新插入方法不支援更新、取代和移除身分。如果新身分不存在，則會建立新身分。因此，identity作業必須一律設定為建立。如果身分已經存在，則操作是無操作。
串流更新插入方法目前不支援Adobe Experience Platform Web SDK和Adobe Experience Platform Mobile SDK。

後續步驟

閱讀本檔案後，您現在應該瞭解如何在Data Prep中串流更新插入，以傳送您Real-Time Customer Profile資料的部分列更新，同時使用單一API請求建立和連結身分識別。如需其他Data Prep功能的詳細資訊，請閱讀Data Prep 概觀。若要瞭解如何在Data Prep API中使用對應集，請閱讀Data Prep 開發人員指南。

recommendation-more-help

461cc884-c234-4a0c-ac75-6efbaafc1394