使用Destination SDK建立之目的地的範本規格

最後更新： 2026年10月23日

主題：
儀表板

建立對象：

使用者
管理員
開發人員
領導者

使用目的地伺服器設定的範本規格部分來設定如何格式化傳送到目的地的HTTP要求。

在範本規格中，您可以定義如何在XDM結構描述和平台支援的格式之間轉換設定檔屬性欄位。

範本規格是即時（串流）目的地的目的地伺服器設定的一部分。

若要瞭解此元件在何處適合使用Destination SDK建立的整合，請參閱設定選項檔案中的圖表，或參閱如何使用Destination SDK設定串流目的地的指南。

您可以透過/authoring/destination-servers端點設定您目的地的範本規格。請參閱下列API參考頁面，以取得詳細的API呼叫範例，您可在此範例設定本頁面中顯示的元件。

IMPORTANT

Destination SDK支援的所有引數名稱和值都會區分大小寫****。為避免區分大小寫錯誤，請完全按照檔案中所示使用引數名稱和值。

支援的整合型別 supported-integration-types

如需瞭解哪些型別的整合支援本頁面所述功能的詳細資訊，請參閱下表。

整合型別

支援功能

即時（串流）整合

是

檔案式（批次）整合

無

設定範本規格 configure-template-spec

Adobe使用類似Jinja的範本化語言，將XDM結構描述的欄位轉換為目的地支援的格式。

醒目提示的範本設定

如需轉換的詳細資訊，請造訪下列連結：

TIP

Adobe提供開發人員工具，可協助您建立和測試訊息轉換範本。

請參閱以下的HTTP要求範本範例，以及各個引數的說明。

{
   "httpTemplate":{
      "httpMethod":"POST",
      "requestBody":{
         "templatingStrategy":"PEBBLE_V1",
         "value":"{ \"attributes\": [ {% for ns in [\"external_id\", \"yourdestination_id\"] %} {% if input.profile.identityMap[ns] is not empty and first_namespace_encountered %} , {% endif %} {% set first_namespace_encountered = true %} {% for identity in input.profile.identityMap[ns]%} { \"{{ ns }}\": \"{{ identity.id }}\" {% if hasSegments(input.profile.segmentMembership) %} , \"AEPSegments\": { \"add\": [ {% for namespace in input.profile.segmentMembership %} {% for segment in input.profile.segmentMembership[namespace.key] %} {% if (segment.value.status == \"realized\" or segment.value.status == \"existing\") and destination.namespaceSegmentAliases[namespace.key][segment.key] is defined %} {% if added_segment_found %} , {% endif %} {% set added_segment_found = true %} \"{{ destination.namespaceSegmentAliases[namespace.key][segment.key] }}\" {% endif %} {% endfor %} {% endfor %} ], \"remove\": [ {% for namespace in input.profile.segmentMembership %} {% for segment in input.profile.segmentMembership[namespace.key] %} {% if segment.value.status == \"exited\" and destination.namespaceSegmentAliases[namespace.key][segment.key] is defined %} {% if removed_segment_found %} , {% endif %} {% set removed_segment_found = true %} \"{{ destination.namespaceSegmentAliases[namespace.key][segment.key] }}\" {% endif %} {% endfor %} {% endfor %} ] } {% set removed_segment_found = false %} {% set added_segment_found = false %} {% endif %} {% if input.profile.attributes is not empty %} , {% endif %} {% for attribute in input.profile.attributes %} \"{{ attribute.key }}\": {% if attribute.value is empty %} null {% else %} \"{{ attribute.value.value }}\" {% endif %} {% if not loop.last%} , {% endif %} {% endfor %} } {% if not loop.last %} , {% endif %} {% endfor %} {% endfor %} ] }"
      },
      "contentType":"application/json"
   }
}

參數

類型

說明

httpMethod

字串

必要。 Adobe將在對伺服器呼叫中使用的方法。支援的方法： GET、PUT、POST、DELETE、PATCH。

templatingStrategy

字串

必要。 使用PEBBLE_V1。

value

字串

必要。 此字串是範本的字元逸出版本，可將Experience Platform傳送的HTTP要求格式化為目的地預期的格式。
如需如何撰寫範本的詳細資訊，請使用範本🔗閱讀上的區段。
如需有關字元逸出的詳細資訊，請參閱RFC JSON標準第7節。
如需簡單轉換的範例，請參閱設定檔屬性轉換。

contentType

字串

必要。 您的伺服器接受的內容型別。視轉換範本產生的輸出型別而定，這可以是任何支援的HTTP應用程式內容型別。在大多數情況下，這個值應該設定為application/json。

轉換範本以支援外部對象 template-converter-tool

較舊的範本只會從ups名稱空間讀取對象成員資格。更新這些範本，以便在segmentMembership中逐一檢視每個名稱空間，讓他們也能讀取外部對象的成員資格。

如需有關如何設定您的目的地以支援外部對象的資訊，請參閱設定外部對象的支援。

使用 範本轉換器 工具自動轉換您現有的範本。此工具會將只讀取ups名稱空間的範本重寫為反複讀取segmentMembership中的所有名稱空間（包括外部對象）的範本。

下載範本轉換工具

此工具需要Java Runtime Environment (JRE) 11或更新版本。它支援兩種模式：

命令列介面(CLI)模式：從終端機執行工具，並將現有的範本作為引數傳遞。

code language-shell
`java -jar templates-converter-cli.jar "your-existing-template-string"`

工具會將轉換的範本列印到終端機。

使用者介面(UI)模式：使用圖形介面執行工具。此模式需要JavaFX SDK，這包含在下載的封存檔中。

code language-shell
`java --module-path="./javafx-sdk-17.0.7/lib" --add-modules=javafx.controls,javafx.fxml -jar templates-converter-ui.jar`

轉換範本後，請使用轉譯範本API針對多個範例設定檔測試它，以確認它仍正確轉譯，然後再將其新增到目的地伺服器設定。

IMPORTANT

範本轉換工具只會重寫範本的語法。它不會驗證轉換後範本的商業邏輯。在生產中使用轉換的範本之前，請務必先對其進行測試。

設定請求標頭 headers

除了要求內文外，您也可以新增自訂HTTP標頭，以呼叫Experience Platform前往您的目的地。每個標題專案使用相同的templatingStrategy和value欄位，如同目的地伺服器中的其他範本化欄位。

"httpTemplate": {
  "httpMethod": "POST",
  "headers": [
    {
      "header": "Authorization",
      "value": {
        "templatingStrategy": "PEBBLE_V1",
        "value": "Basic {{ (authData.username + ':' + authData.password) | base64encode }}"
      }
    },
    {
      "header": "x-integration",
      "value": {
        "templatingStrategy": "PEBBLE_V1",
        "value": "{{customerData.integrationId}}"
      }
    },
    {
      "header": "Amazon-Advertising-API-ClientId",
      "value": {
        "templatingStrategy": "PEBBLE_V1",
        "value": "{{authData.clientId}}"
      }
    },
    {
      "header": "Accept",
      "value": {
        "templatingStrategy": "NONE",
        "value": "application/json"
      }
    }
  ]
}

參數

類型

說明

header

字串

必要。 標頭名稱，例如Authorization、Content-Type或自訂標頭。

value.templatingStrategy

字串

必要。 當標頭值為動態或使用Pebble運算式時，請使用PEBBLE_V1。使用NONE作為靜態值。

value.value

字串

必要。 標頭值。支援參考客戶資料或驗證資料欄位的Pebble運算式，例如{{customerData.integrationId}}、{{authData.clientId}}或{{ (authData.username + ':' + authData.password) | base64encode }}。

某些合作夥伴API需要自訂標頭填入客戶提供的驗證認證值，而不是標準Authorization標頭。上面顯示的Amazon-Advertising-API-ClientId標頭是此模式的範例，其中標頭值直接來自authData欄位。

NOTE

此結構僅適用於目的地伺服器標頭。對象中繼資料範本標題使用較簡單的表單，其中value是純字串，而不是具有templatingStrategy和value欄位的物件。如需範例，請參閱對象中繼資料管理。

對於使用需要自訂Base64編碼標頭之基本驗證的目的地，請參閱自訂基本驗證標頭。

後續步驟 next-steps

閱讀本文後，您應該更瞭解什麼是範本規格，以及如何進行設定。

若要深入瞭解其他目的地伺服器元件，請參閱下列文章：

recommendation-more-help

experience-platform-help-destinations