文档Experience Platform目标指南

合作伙伴架构配置

Last update: Tue Nov 07 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

创建对象：

  • 管理员
  • 用户

Experience Platform 会使用架构，以便以可重用的一致方式描述数据结构。当数据被摄取到Platform中时，它会根据XDM架构进行构建。 有关架构组合模型的更多信息，包括设计原则和最佳实践，请参阅 模式组合基础.

使用Destination SDK构建目标时，您可以定义自己的合作伙伴架构以供目标平台使用。 这使用户能够将配置文件属性从Platform映射到目标平台可识别的特定字段，所有这些字段均在Platform UI中。

在为目标配置合作伙伴架构时，您可以优化目标平台支持的字段映射，例如：

  • 允许用户映射 phoneNumber XDM属性到 phone 目标平台支持的属性。
  • 创建动态合作伙伴架构，Experience Platform可以动态调用这些架构以检索目标中所有受支持属性的列表。
  • 定义目标平台所需的必填字段映射。

要了解此组件在何处适合使用Destination SDK创建的集成，请参阅中的图表 配置选项 文档或参阅指南，了解如何 使用Destination SDK配置基于文件的目标.

您可以通过以下方式配置架构设置 /authoring/destinations 端点。 有关详细的API调用示例，请参阅以下API参考页面，您可以在其中配置此页面中显示的组件。

本文介绍了可用于目标的所有受支持的架构配置选项，并显示了客户将在Platform UI中看到的内容。

IMPORTANT
Destination SDK支持的所有参数名称和值包括 区分大小写. 为避免出现区分大小写错误，请完全按照文档中的说明使用参数名称和值。

支持的集成类型 supported-integration-types

有关哪些类型的集成支持此页面上描述的功能，请参阅下表。

集成类型
支持功能
实时（流）集成
是
基于文件（批处理）的集成
是

支持的架构配置 supported-schema-types

Destination SDK支持多种架构配置：

  • 静态架构是通过 profileFields 中的数组 schemaConfig 部分。 在静态架构中，您定义了应在Experience PlatformUI中显示的每个目标属性 profileFields 数组。 如果需要更新架构，您必须 更新目标配置.
  • 动态架构使用其他目标服务器类型，称为 动态模式服务器，以动态检索支持的目标属性并根据您自己的API生成架构。 动态架构不使用 profileFields 数组。 如果需要更新架构，则无需 更新目标配置. 动态架构服务器而是从API中检索更新的架构。
  • 在架构配置中，您可以选择添加所需的（或预定义的）映射。 用户可以在Platform UI中查看这些映射，但在设置与目标的连接时，无法修改这些映射。 例如，您可以强制电子邮件地址字段始终发送到目标。

此 schemaConfig 部分会根据所需的架构类型使用多个配置参数，如下部分所示。

创建静态架构 attributes-schema

要创建具有配置文件属性的静态架构，请在 profileFields 数组，如下所示。

"schemaConfig":{
      "profileFields":[
           {
              "name":"phoneNo",
              "title":"phoneNo",
              "description":"This is a fixed attribute on your destination side that customers can map profile attributes to. For example, the mobilePhone.number value in Experience Platform could be phoneNo on your side.",
              "type":"string",
              "isRequired":false,
              "readOnly":false,
              "hidden":false
           },
                      {
              "name":"firstName",
              "title":"firstName",
              "description":"This is a fixed attribute on your destination side that customers can map profile attributes to. For example, the person.name.firstName value in Experience Platform could be firstName on your side.",
              "type":"string",
              "isRequired":false,
              "readOnly":false,
              "hidden":false
           },
                      {
              "name":"lastName",
              "title":"lastName",
              "description":"This is a fixed attribute on your destination side that customers can map profile attributes to. For example, the person.name.lastName value in Experience Platform could be phoneNo on your side.",
              "type":"string",
              "isRequired":false,
              "readOnly":false,
              "hidden":false
           }
        ],
      "useCustomerSchemaForAttributeMapping":false,
      "profileRequired":true,
      "segmentRequired":true,
      "identityRequired":true,
      "segmentNamespaceAllowList": ["someNamespace"],
      "segmentNamespaceDenyList": ["someOtherNamespace"]

}
参数
类型
必填/可选
描述
profileFields
数组
可选
定义目标平台接受的目标属性数组，客户可以将其配置文件属性映射到这些目标属性。 使用 profileFields 数组，您可以忽略 useCustomerSchemaForAttributeMapping 参数。
useCustomerSchemaForAttributeMapping
布尔值
可选

启用或禁用从客户架构到您在 profileFields 数组。

  • 如果设置为 true，用户仅可在映射字段中看到源列。 profileFields 不适用于此情况。
  • 如果设置为 false，用户可以将源属性从其架构映射到您在以下位置定义的属性： profileFields 数组。

默认值为 false。

profileRequired
布尔值
可选
使用 true 用户是否应该能够将配置文件属性从Experience Platform映射到目标平台上的自定义属性。
segmentRequired
布尔值
必需
此参数是Destination SDK的必需参数，应始终设置为 true.
identityRequired
布尔值
必需
设置为 true 用户是否应该能够映射 身份类型 从Experience Platform到您在 profileFields 数组。
segmentNamespaceAllowList
数组
可选
定义用户可以从中将受众映射到目标的特定受众命名空间。 使用此参数可限制Platform用户仅从您在数组中定义的受众命名空间导出受众。 此参数不能与一起使用 segmentNamespaceDenyList.

示例： "segmentNamespaceAllowList": ["AudienceManager"] 将允许用户仅映射以下目录中的受众： AudienceManager 命名空间指向此目标。

要允许用户将任何受众导出到您的目标，您可以忽略此参数。

如果两者 segmentNamespaceAllowList 和 segmentNamespaceDenyList 您的配置中缺少，用户将只能导出源自 分段服务.
segmentNamespaceDenyList
数组
可选
限制用户从数组中定义的受众命名空间将受众映射到目标。 不能与一起使用 segmentNamespaceAllowed.

示例： "segmentNamespaceDenyList": ["AudienceManager"] 将阻止用户从映射受众 AudienceManager 命名空间指向此目标。

要允许用户将任何受众导出到您的目标，您可以忽略此参数。

如果两者 segmentNamespaceAllowed 和 segmentNamespaceDenyList 您的配置中缺少，用户将只能导出源自 分段服务.

要允许导出所有受众，而不管其来源如何，请设置 "segmentNamespaceDenyList":[].

生成的UI体验如下图所示。

当用户选择目标映射时，他们将会看到中定义的字段。 profileFields 数组。

显示目标属性屏幕的UI图像。

选择属性后，他们可以在目标字段列中看到这些属性。

显示具有属性的静态目标架构的用户界面图像

创建动态架构 dynamic-schema-configuration

Destination SDK支持创建动态合作伙伴架构。 与静态架构不同，动态架构不使用 profileFields 数组。 动态架构会改用动态架构服务器，该服务器会连接到您自己的API，并在其中检索架构配置。

IMPORTANT
在创建动态架构之前，必须 创建动态模式服务器.

在动态模式配置中， profileFields 数组被替换为 dynamicSchemaConfig 部分，如下所示。

"schemaConfig":{
   "dynamicSchemaConfig":{
      "dynamicEnum": {
         "authenticationRule":"CUSTOMER_AUTHENTICATION",
         "destinationServerId":"DYNAMIC_SCHEMA_SERVER_ID",
         "value": "Schema Name",
         "responseFormat": "SCHEMA"
      }
   },
   "profileRequired":true,
   "segmentRequired":true,
   "identityRequired":true
}
参数
类型
必填/可选
描述
dynamicEnum.authenticationRule
字符串
必需

指示方式 Platform 客户连接到您的目标。 接受的值包括 CUSTOMER_AUTHENTICATION， PLATFORM_AUTHENTICATION， NONE.

  • 使用 CUSTOMER_AUTHENTICATION 如果Platform客户通过所描述的任何身份验证方法登录到您的系统 此处.
  • 使用 PLATFORM_AUTHENTICATION 如果Adobe与您的目的地之间有一个全局身份验证系统，并且 Platform 客户无需提供任何身份验证凭据即可连接到您的目标。 在这种情况下，您必须 创建凭据对象 使用凭据API。
  • 使用 NONE 如果不需要身份验证即可将数据发送到您的目标平台。
dynamicEnum.destinationServerId
字符串
必需
此 instanceId 动态架构服务器中的。 此目标服务器包括API端点，Experience Platform将调用该API端点以检索动态架构。
dynamicEnum.value
字符串
必需
动态架构的名称，如动态架构服务器配置中所定义。
dynamicEnum.responseFormat
字符串
必需
始终设置为 SCHEMA 定义动态模式时。
profileRequired
布尔值
可选
使用 true 用户是否应该能够将配置文件属性从Experience Platform映射到目标平台上的自定义属性。
segmentRequired
布尔值
必需
此参数是Destination SDK的必需参数，应始终设置为 true.
identityRequired
布尔值
必需
设置为 true 用户是否应该能够映射 身份类型 从Experience Platform到您在 profileFields 数组。

必需的映射 required-mappings

在架构配置中，除了静态或动态架构外，您还可以选择添加所需的（或预定义的）映射。 用户可以在Platform UI中查看这些映射，但在设置与目标的连接时，无法修改这些映射。

例如，您可以强制电子邮件地址字段始终发送到目标。

NOTE
当前支持以下必需的映射组合：
  • 您可以配置必填源字段和必填目标字段。 在这种情况下，用户无法编辑或选择这两个字段中的任何一个，并且只能查看所选内容。
  • 您只能配置必需的目标字段。 在这种情况下，允许用户选择要映射到目标的源字段。
仅配置必需源字段当前为 非 受支持。

请参阅以下两个具有所需映射的架构配置示例，以及它们在的映射步骤中会是什么样子 将数据激活到批处理目标工作流.

必需的源和目标映射

以下示例显示了所需的源映射和目标映射。 当源字段和目标字段均指定为必需映射时，用户无法选择或编辑这两个字段中的任何一个，并且只能查看预定义的选择。

code language-json 
"schemaConfig": {
    "requiredMappingsOnly": true,
    "requiredMappings": [
      {
        "sourceType": "text/x.schema-path",
        "source": "personalEmail.address",
        "destination": "personalEmail.address"
      }
    ]
}
table 0-row-4 1-row-4 2-row-4 3-row-4 4-row-4 layout-auto
参数 类型 必填/可选 描述
requiredMappingsOnly 布尔值 可选 当此项设置为true时，用户无法映射激活流中的其他属性和身份，除非您在 requiredMappings 数组。
requiredMappings.sourceType 字符串 必需

指示 source 字段。 支持的值：

  • text/x.schema-path：此值用于 source 字段是XDM架构中的配置文件属性。
  • text/x.aep-xl：在以下情况下使用此值： source 字段由正则表达式定义。 示例：iif(segmentMembership.ups.aep_seg_id.status==\"exited\", \"1\", \"0\")
  • text/plain：在以下情况下使用此值： source 字段由宏模板定义。 目前，唯一支持的宏模板是 metadata.segment.alias.
requiredMappings.source 字符串 必需

指示源字段的值。 支持的值类型：

  • XDM配置文件属性。 示例: personalEmail.address. 当源属性是XDM配置文件属性时，设置 sourceType 参数至 text/x.schema-path.
  • 正则表达式. 示例: iif(segmentMembership.ups.aep_seg_id.status==\"exited\", \"1\", \"0\"). 当源属性为正则表达式时，设置 sourceType 参数至 text/x.aep-xl.
  • 宏模板。 示例:metadata.segment.alias. 当源属性是宏模板时，设置 sourceType 参数至 text/plain. 目前，唯一支持的宏模板是 metadata.segment.alias.
requiredMappings.destination 字符串 必需 指示目标字段的值。 当源字段和目标字段均指定为必需映射时，用户无法选择或编辑这两个字段中的任何一个，并且只能查看所选内容。

因此， 源字段 和 目标字段 Platform UI中的部分显示为灰色。

UI激活流程中所需映射的图像。

必需的目标映射

以下示例显示了所需的目标映射。 如果仅将目标字段指定为必填字段，则用户可以选择要映射到它的源字段。

code language-json 
"schemaConfig": {
    "requiredMappingsOnly": true,
    "requiredMappings": [
      {
        "destination": "identityMap.ExamplePartner_ID",
        "mandatoryRequired": true,
        "primaryKeyRequired": true
      }
    ]
}
table 0-row-4 1-row-4 2-row-4 3-row-4 4-row-4 layout-auto
参数 类型 必填/可选 描述
requiredMappingsOnly 布尔值 可选 当此项设置为true时，用户无法映射激活流中的其他属性和身份，除非您在 requiredMappings 数组。
requiredMappings.destination 字符串 必需 指示目标字段的值。 当仅指定目标字段时，用户可以选择要映射到目标的源字段。
mandatoryRequired 布尔值 可选 指示映射是否应标记为 必需属性.
primaryKeyRequired 布尔值 可选 指示映射是否应标记为 重复数据删除键.

因此， 目标字段 Platform UI中的部分呈灰显状态，而 源字段 区域处于活动状态，用户可以与其进行交互。 此 必需键 和 重复数据删除键 选项处于活动状态，用户无法更改它们。

UI激活流程中所需映射的图像。

后续步骤 next-steps

阅读本文后，您应该更好地了解Destination SDK支持哪些架构类型，以及如何配置架构。

要了解有关其他目标组件的更多信息，请参阅以下文章：

recommendation-more-help
7f4d1967-bf93-4dba-9789-bb6b505339d6