通过客户数据字段配置用户输入
在Experience PlatformUI中连接到目标时，您可能需要用户提供特定的配置详细信息或选择您向他们提供的特定选项。 在Destination SDK中，这些选项称为客户数据字段。
要了解此组件在何处适合使用Destination SDK创建的集成，请参阅配置选项文档中的关系图或查看以下目标配置概述页面：
客户数据字段的用例 use-cases
在需要用户将数据输入到Experience PlatformUI中的各种用例中使用客户数据字段。 例如，当用户需要提供以下内容时，请使用客户数据字段：
- 云存储段名称和路径，用于基于文件的目标。
- 客户数据字段接受的格式。
- 用户可以选择的可用文件压缩类型。
- 实时（流）集成的可用端点列表。
您可以通过/authoring/destinations端点配置客户数据字段。 有关详细的API调用示例，请参阅以下API参考页面，您可以在其中配置此页面中显示的组件。
本文介绍了可用于目标的所有受支持的客户数据字段配置类型，并显示了客户将在Experience PlatformUI中看到的内容。
支持的集成类型 supported-integration-types
有关哪些类型的集成支持此页面上描述的功能，请参阅下表。
支持的参数 supported-parameters
在创建自己的客户数据字段时，您可以使用下表中描述的参数来配置其行为。
nametitle字段为空或缺失。type指示您即将引入的自定义字段的类型。 接受的值：
stringobjectinteger
titlename值继承字段名称。descriptionisRequiredpattern^[A-Za-z]+$。enumdefaultenum列表中定义默认值。hiddenuniquereadOnly在以下示例中，customerDataFields部分定义了用户在连接到目标时必须在Platform UI中输入的两个字段：
Account ID：目标平台的用户帐户ID。Endpoint region：它们将连接到的API的区域终结点。enum部分创建一个下拉菜单，其中的值定义可供用户选择。
"customerDataFields":[
{
"name":"accountID",
"title":"User account ID",
"description":"User account ID for the destination platform.",
"type":"string",
"isRequired":true
},
{
"name":"region",
"title":"API endpoint region",
"description":"The API endpoint region that the user should connect to.",
"type":"string",
"isRequired":true,
"enum":[
"EU"
"US",
],
"readOnly":false,
"hidden":false
}
]
生成的UI体验如下图所示。
目标连接名称和描述 names-description
创建新目标时，Destination SDK会自动将 Name 和 Description 字段添加到Platform UI中的目标连接屏幕中。 如上面的示例所示，Name 和 Description 字段已在UI中呈现，但未包含在客户数据字段配置中。
订购客户数据字段 ordering
目标配置中添加客户数据字段的顺序反映在Platform UI中。
例如，以下配置将相应地反映在UI中，选项按 名称、描述、存储段名称、文件夹路径、文件类型、压缩格式 的顺序显示。
"customerDataFields":[
{
"name":"bucketName",
"title":"Bucket name",
"description":"Amazon S3 bucket name",
"type":"string",
"isRequired":true,
"pattern":"(?=^.{3,63}$)(?!^(\\d+\\.)+\\d+$)(^(([a-z0-9]|[a-z0-9][a-z0-9\\-]*[a-z0-9])\\.)*([a-z0-9]|[a-z0-9][a-z0-9\\-]*[a-z0-9])$)",
"readOnly":false,
"hidden":false
},
{
"name":"path",
"title":"Folder path",
"description":"Enter the path to your S3 bucket folder",
"type":"string",
"isRequired":true,
"pattern":"^[0-9a-zA-Z\\/\\!\\-_\\.\\*\\''\\(\\)]*((\\%SEGMENT_(NAME|ID)\\%)?\\/?)+$",
"readOnly":false,
"hidden":false
},
{
"name":"fileType",
"title":"File Type",
"description":"Select the exported file type.",
"type":"string",
"isRequired":true,
"readOnly":false,
"hidden":false,
"enum":[
"csv",
"json",
"parquet"
],
"default":"csv"
},
{
"name":"compression",
"title":"Compression format",
"description":"Select the desired file compression format.",
"type":"string",
"isRequired":true,
"readOnly":false,
"enum":[
"SNAPPY",
"GZIP",
"DEFLATE",
"NONE"
]
}
]
分组客户数据字段 grouping
您可以在一个部分中对多个客户数据字段进行分组。 在UI中设置与目标之间的连接时，用户可以查看类似字段的可视化分组并从中受益。
为此，请使用"type": "object"创建组，并在properties对象中收集所需的客户数据字段，如下图所示，其中高亮显示了 CSV选项 分组。
"customerDataFields":[
{
"name":"csvOptions",
"title":"CSV Options",
"description":"Select your CSV options",
"type":"object",
"properties":[
{
"name":"delimiter",
"title":"Delimiter",
"description":"Select your Delimiter",
"type":"string",
"isRequired":false,
"default":",",
"namedEnum":[
{
"name":"Comma (,)",
"value":","
},
{
"name":"Tab (\\t)",
"value":"\t"
}
],
"readOnly":false,
"hidden":false
}
]
}
]
为客户数据字段创建下拉选择器 dropdown-selectors
对于希望允许用户在多个选项之间进行选择的情况（例如，应使用哪个字符来分隔CSV文件中的字段），您可以向UI添加下拉字段。
为此，请使用如下所示的namedEnum对象，并为用户可以选择的选项配置default值。
"customerDataFields":[
{
"name":"csvOptions",
"title":"CSV Options",
"description":"Select your CSV options",
"type":"object",
"properties":[
{
"name":"delimiter",
"title":"Delimiter",
"description":"Select your Delimiter",
"type":"string",
"isRequired":false,
"default":",",
"namedEnum":[
{
"name":"Comma (,)",
"value":","
},
{
"name":"Tab (\\t)",
"value":"\t"
}
],
"readOnly":false,
"hidden":false
}
]
}
]
为客户数据字段创建动态下拉选择器 dynamic-dropdown-selectors
对于要动态调用API并使用响应动态填充下拉菜单中的选项的情况，您可以使用动态下拉选择器。
动态下拉列表选择器与UI中的常规下拉列表选择器相同。 唯一的区别是这些值是从API动态检索的。
要创建动态下拉选择器，您必须配置两个组件：
步骤1. 为动态API调用创建具有responseFields模板的目标服务器，如下所示。
{
"name":"Server for dynamic dropdown",
"destinationServerType":"URL_BASED",
"urlBasedDestination":{
"url":{
"templatingStrategy":"PEBBLE_V1",
"value":" <--YOUR-API-ENDPOINT-PATH--> "
}
},
"httpTemplate":{
"httpMethod":"GET",
"headers":[
{
"header":"Authorization",
"value":{
"templatingStrategy":"PEBBLE_V1",
"value":"My Bearer Token"
}
},
{
"header":"x-integration",
"value":{
"templatingStrategy":"PEBBLE_V1",
"value":"{{customerData.integrationId}}"
}
},
{
"header":"Accept",
"value":{
"templatingStrategy":"NONE",
"value":"application/json"
}
}
]
},
"responseFields":[
{
"templatingStrategy":"PEBBLE_V1",
"value":"{% set list = [] %} {% for record in response.body %} {% set list = list|merge([{'name' : record.name, 'value' : record.id }]) %} {% endfor %}{{ {'list': list} | toJson | raw }}",
"name":"list"
}
]
}
步骤2. 使用dynamicEnum对象，如下所示。 在下面的示例中，使用动态服务器检索User下拉列表。
"customerDataFields": [
{
"name": "integrationId",
"title": "Integration ID",
"type": "string",
"isRequired": true
},
{
"name": "userId",
"title": "User",
"type": "string",
"isRequired": true,
"dynamicEnum": {
"queryParams": [
"integrationId"
],
"destinationServerId": "<~dynamic-field-server-id~>",
"authenticationRule": "CUSTOMER_AUTHENTICATION",
"value": "$.list",
"responseFormat": "NAME_VALUE"
}
}
]
将destinationServerId参数设置为您在步骤1中创建的目标服务器的ID。 您可以在检索目标服务器配置 API调用的响应中看到目标服务器ID。
创建嵌套式客户数据字段 nested-fields
您可以为复杂的集成模式创建嵌套式客户数据字段。 这允许您为客户链接一系列选择。
例如，您可以添加嵌套的客户数据字段，以要求客户选择与您目标的集成类型，然后紧接着进行其他选择。 第二个选择是集成类型中的嵌套字段。
要添加嵌套字段，请使用properties参数，如下所示。 在下面的配置示例中，您可以在 您的目标 — 集成特定设置 客户数据字段中看到三个单独的嵌套字段。
isRequired参数。 例如，在下面的配置代码片段中，前两个嵌套字段被标记为必填字段（高亮显示的第xxx行），客户无法继续操作，除非他们为该字段选择值。 详细了解支持的参数部分中的必填字段。 {
"name": "yourdestination",
"title": "Yourdestination - Integration Specific Settings",
"type": "object",
"properties": [
{
"name": "agreement",
"title": "Advertiser data destination terms agreement. Enter I AGREE.",
"type": "string",
"isRequired": true,
"pattern": "I AGREE",
"readOnly": false,
"hidden": false
},
{
"name": "account-name",
"title": "Account name",
"type": "string",
"isRequired": true,
"readOnly": false,
"hidden": false
},
{
"name": "email",
"title": "Email address",
"type": "string",
"isRequired": false,
"pattern": "^[\\w-\\.]+@([\\w-]+\\.)+[\\w-]{2,4}$",
"readOnly": false,
"hidden": false
}
],
"isRequired": false,
"readOnly": false,
"hidden": false,
创建条件客户数据字段 conditional-options
您可以创建条件客户数据字段，这些字段仅在用户选择特定选项时才会显示在激活工作流中。
例如，您可以创建条件文件格式选项，以使其仅在用户选择特定文件导出类型时显示。
以下配置将为CSV文件格式选项创建条件分组。 只有在用户选择CSV作为导出所需的文件类型时，才会显示CSV文件选项。
要将字段设置为条件字段，请使用conditional参数，如下所示：
"conditional": {
"field": "fileType",
"operator": "EQUALS",
"value": "CSV"
}
在更广泛的上下文中，您可以看到以下目标配置中使用的conditional字段，以及在其中定义该字段的fileType字符串和csvOptions对象。 条件字段在properties参数中定义。
"customerDataFields":[
{
"name":"fileType",
"title":"File Type",
"description":"Select your file type",
"type":"string",
"isRequired":true,
"enum":[
"PARQUET",
"CSV",
"JSON"
],
"readOnly":false,
"hidden":false
},
{
"name":"csvOptions",
"title":"CSV Options",
"description":"Select your CSV options",
"type":"object",
"conditional":{
"field":"fileType",
"operator":"EQUALS",
"value":"CSV"
},
"properties":[
{
"name":"delimiter",
"title":"Delimiter",
"description":"Select your Delimiter",
"type":"string",
"isRequired":false,
"default":",",
"namedEnum":[
{
"name":"Comma (,)",
"value":","
},
{
"name":"Tab (\\t)",
"value":"\t"
}
],
"readOnly":false,
"hidden":false
},
{
"name":"quote",
"title":"Quote Character",
"description":"Select your Quote character",
"type":"string",
"isRequired":false,
"default":"",
"namedEnum":[
{
"name":"Double Quotes (\")",
"value":"\""
},
{
"name":"Null Character (\u0000)",
"value":"\u0000"
}
],
"readOnly":false,
"hidden":false
},
{
"name":"escape",
"title":"Escape Character",
"description":"Select your Escape character",
"type":"string",
"isRequired":false,
"default":"\\",
"namedEnum":[
{
"name":"Back Slash (\\)",
"value":"\\"
},
{
"name":"Single Quote (')",
"value":"'"
}
],
"readOnly":false,
"hidden":false
},
{
"name":"emptyValue",
"title":"Empty Value",
"description":"Select the output value of blank fields",
"type":"string",
"isRequired":false,
"default":"",
"namedEnum":[
{
"name":"Empty String",
"value":""
},
{
"name":"\"\"",
"value":"\"\""
},
{
"name":"null",
"value":"null"
}
],
"readOnly":false,
"hidden":false
},
{
"name":"nullValue",
"title":"Null Value",
"description":"Select the output value of 'null' fields",
"type":"string",
"isRequired":false,
"default":"null",
"namedEnum":[
{
"name":"Empty String",
"value":""
},
{
"name":"\"\"",
"value":"\"\""
},
{
"name":"null",
"value":"null"
}
],
"readOnly":false,
"hidden":false
}
],
"isRequired":false,
"readOnly":false,
"hidden":false
}
]
在下方，您可以根据上述配置查看生成的UI屏幕。 当用户选择文件类型CSV时，UI中会显示引用CSV文件类型的其他文件格式选项。
访问模板化的客户数据字段 accessing-templatized-fields
当您的目标需要用户输入时，您必须向用户提供一系列客户数据字段，用户可以通过Platform UI填写这些字段。 然后，您必须配置目标服务器，以从客户数据字段中正确读取用户输入。 这可以通过模板化字段完成。
模板化字段使用格式{{customerData.fieldName}}，其中fieldName是从中读取信息的客户数据字段的名称。 所有模板化的客户数据字段前面都有customerData.，并包含在双大括号{{ }}中。
例如，我们来考虑以下Amazon S3目标配置：
"customerDataFields":[
{
"name":"bucketName",
"title":"Enter the name of your Amazon S3 bucket",
"description":"Amazon S3 bucket name",
"type":"string",
"isRequired":true,
"pattern":"(?=^.{3,63}$)(?!^(\\d+\\.)+\\d+$)(^(([a-z0-9]|[a-z0-9][a-z0-9\\-]*[a-z0-9])\\.)*([a-z0-9]|[a-z0-9][a-z0-9\\-]*[a-z0-9])$)",
"readOnly":false,
"hidden":false
},
{
"name":"path",
"title":"Enter the path to your S3 bucket folder",
"description":"Enter the path to your S3 bucket folder",
"type":"string",
"isRequired":true,
"pattern":"^[0-9a-zA-Z\\/\\!\\-_\\.\\*\\''\\(\\)]*((\\%SEGMENT_(NAME|ID)\\%)?\\/?)+$",
"readOnly":false,
"hidden":false
}
]
此配置会提示您的用户在各自的客户数据字段中输入其Amazon S3存储段名称和文件夹路径。
为了使Experience Platform正确连接到Amazon S3，必须将目标服务器配置为从这两个客户数据字段中读取值，如下所示：
"fileBasedS3Destination":{
"bucketName":{
"templatingStrategy":"PEBBLE_V1",
"value":"{{customerData.bucketName}}"
},
"path":{
"templatingStrategy":"PEBBLE_V1",
"value":"{{customerData.path}}"
}
}
模板化值{{customerData.bucketName}}和{{customerData.path}}读取用户提供的值，以便Experience Platform能够成功连接到目标平台。
有关如何配置目标服务器以读取模板化字段的更多信息，请参阅有关硬编码字段与模板化字段的文档。
后续步骤 next-steps
阅读本文后，您应该更好地了解如何允许用户在Experience PlatformUI中通过客户数据字段输入信息。 您现在还知道如何为您的用例选择正确的客户数据字段，以及在Platform UI中配置、排序和分组客户数据字段。
要了解有关其他目标组件的更多信息，请参阅以下文章：