文档Experience Platform数据准备指南

使用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 ProfilePATCH请求时保留数据的格式。 根据您提供的输入，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的目标数据集的ID也用作datasetId参数。
imsOrgId
与您的组织相对应的ID。
datasetId
您的数据流已启用Profile的目标数据集的ID。 注意：此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