透過客戶資料欄位設定使用者輸入
在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：您目的地平台的使用者帳戶識別碼。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中，選項會依序顯示 Name、Description、Bucket名稱、資料夾路徑、檔案型別、壓縮格式。
"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建立的目的地伺服器識別碼。 您可以在擷取目的地伺服器組態 API呼叫的回應中看到目的地伺服器識別碼。
建立巢狀客戶資料欄位 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時，參考CSV檔案型別的其他檔案格式選項會顯示在UI中。
存取範本化客戶資料欄位 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中設定、訂購和分組客戶資料欄位。
若要深入瞭解其他目的地元件，請參閱下列文章：