對象中繼資料端點API操作

重要

API端點: platform.adobe.io/data/core/activation/authoring/audience-templates

此頁面列出並說明您可使用 /authoring/audience-templates API端點。 有關使用此端點的時間的說明,請閱讀 對象中繼資料管理.

對象範本API操作快速入門

繼續之前,請檢閱 快速入門手冊 若要成功呼叫API,需知的重要資訊,包括如何取得必要的目的地編寫權限和必要的標題。

建立新受眾範本

您可以向 /authoring/audience-templates 端點。

API格式

POST /authoring/audience-templates

要求

下列請求會建立新的受眾中繼資料範本,由裝載中提供的參數設定。 以下裝載包含接受的所有參數 /authoring/audience-templates 端點。 請注意,您不必在呼叫上新增所有參數,且可根據您的API需求自訂範本。

curl -X POST https://platform.adobe.io/data/core/activation/authoring/audience-templates \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}' \
 -d '
{
   "metadataTemplate":{
      "name":"string",
      "create":{
         "url":"string",
         "httpMethod":"string",
         "headers":[
            {
               "header":"string",
               "value":"string"
            }
         ],
         "requestBody":{

         },
         "responseFields":[
            {
               "name":"string",
               "value":"string"
            }
         ],
         "responseErrorFields":[
            {
               "name":"string",
               "value":"string"
            }
         ]
      },
      "update":{
         "url":"string",
         "httpMethod":"string",
         "headers":[
            {
               "header":"string",
               "value":"string"
            }
         ],
         "requestBody":{

         },
         "responseFields":[
            {
               "name":"string",
               "value":"string"
            }
         ],
         "responseErrorFields":[
            {
               "name":"string",
               "value":"string"
            }
         ]
      },
      "delete":{
         "url":"string",
         "httpMethod":"string",
         "headers":[
            {
               "header":"string",
               "value":"string"
            }
         ],
         "requestBody":{

         },
         "responseFields":[
            {
               "name":"string",
               "value":"string"
            }
         ],
         "responseErrorFields":[
            {
               "name":"string",
               "value":"string"
            }
         ]
      },
      "validate":{
         "url":"string",
         "httpMethod":"string",
         "headers":[
            {
               "header":"string",
               "value":"string"
            }
         ],
         "requestBody":{

         },
         "responseFields":[
            {
               "name":"string",
               "value":"string"
            }
         ],
         "responseErrorFields":[
            {
               "name":"string",
               "value":"string"
            }
         ]
      },
      "notify":{
         "url":"string",
         "httpMethod":"string",
         "headers":[
            {
               "header":"string",
               "value":"string"
            }
         ],
         "requestBody":{

         },
         "responseFields":[
            {
               "name":"string",
               "value":"string"
            }
         ],
         "responseErrorFields":[
            {
               "name":"string",
               "value":"string"
            }
         ]
      }
   },
   "validations":[
      {
         "field":"string",
         "regex":"string"
      }
   ]
}'
屬性 類型 說明
name 字串 目的地的對象中繼資料範本名稱。 此名稱將出現在Experience Platform使用者介面中任何特定於合作夥伴的錯誤訊息中,隨後將顯示從 metadataTemplate.create.errorSchemaMap.
url 字串 API的URL和端點,用於建立、更新、刪除或驗證平台中的對象/區段。 兩個行業例子是: https://adsapi.snapchat.com/v1/adaccounts/{{customerData.accountId}}/segmentshttps://api.linkedin.com/v2/dmpSegments/{{segment.alias}}.
httpMethod 字串 端點上用來以程式設計方式建立、更新、刪除或驗證目的地中的區段/對象的方法。 例如: POST, PUT, DELETE
headers.header 字串 指定應新增至對API的呼叫的任何HTTP標題。 例如, "Content-Type"
headers.value 字串 指定應新增至API呼叫的HTTP標題值。 例如, "application/x-www-form-urlencoded"
requestBody 字串 指定應傳送至API的訊息內文內容。 應新增至 requestBody 物件取決於API接受的欄位。 如需範例,請參閱 第一個範本範例 在「對象中繼資料」功能檔案中。
responseFields.name 字串 指定API在呼叫時傳回的任何回應欄位。 如需範例,請參閱 範本範例 在「對象中繼資料」功能檔案中。
responseFields.value 字串 指定呼叫API時傳回之任何回應欄位的值。
responseErrorFields.name 字串 指定API在呼叫時傳回的任何回應欄位。 如需範例,請參閱 範本範例 在「對象中繼資料」功能檔案中。
responseErrorFields.value 字串 剖析來自您目的地之API呼叫回應傳回的任何錯誤訊息。 這些錯誤訊息會在Experience Platform使用者介面中呈現給使用者。
validations.field 字串 指出在對您的目的地進行API呼叫之前,是否應對任何欄位執行驗證。 例如,您可以使用 {{validations.accountId}} 以驗證使用者的帳戶ID。
validations.regex 字串 指出欄位的結構方式,以便驗證通過。

回應

成功的回應會傳回HTTP狀態200,並包含新建立之對象範本的詳細資訊。

更新受眾範本

您可以向 /authoring/audience-templates 端點,並提供您要更新之對象範本的例項ID。 在呼叫內文中,提供更新的範本。

API格式

PUT /authoring/audience-templates/{INSTANCE_ID}
參數 說明
{INSTANCE_ID} 您要更新之對象中繼資料範本的ID。

要求

下列要求會更新現有的受眾中繼資料範本,由裝載中提供的參數設定。

curl -X PUT https://platform.adobe.io/data/core/activation/authoring/audience-templates/bd4ec8f0-e98f-4b6a-8064-dd7adbfffec9 \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}' \
 -d '
{
   "metadataTemplate":{
      "create":{
         "url":"https://api.moviestar.com/v1.0/{{customerData.accountId}}/customaudiences?fields=name,description,account_id&subtype=CUSTOM&name={{segment.name}}&customer_file_source={{segment.metadata.customer_file_source}}&access_token={{authData.accessToken}}",
         "httpMethod":"POST",
         "headers":[
            {
               "value":"application/x-www-form-urlencoded",
               "header":"Content-Type"
            }
         ],
         "responseFields":[
            {
               "value":"{{response.id}}",
               "name":"externalAudienceId"
            }
         ],
         "responseErrorFields":[
            {
               "value":"{{error.message}}",
               "name":"message"
            }
         ]
      },
      "update":{
         "url":"https://api.moviestar.com/v1.0/{{segment.alias}}?field=name,description,account_id&access_token={{authData.accessToken}}&customerAudienceId={{segment.alias}}&&name={{segment.name}}&description={{segment.description}}&customer_file_source={{segment.metadata.customer_file_source}}",
         "httpMethod":"POST",
         "headers":[
            {
               "value":"application/x-www-form-urlencoded",
               "header":"Content-Type"
            }
         ],
         "responseFields":[
            {
               "value":"{{response.id}}",
               "name":"externalAudienceId"
            }
         ],
         "responseErrorFields":[
            {
               "value":"{{error.message}}",
               "name":"message"
            }
         ]
      },
      "delete":{
         "url":"https://api.moviestar.com/v1.0/{{segment.alias}}?fields=name,description,account_id&access_token={{authData.accessToken}}&customerAudienceId={{segment.alias}}",
         "httpMethod":"DELETE",
         "headers":[
            {
               "value":"application/x-www-form-urlencoded",
               "header":"Content-Type"
            }
         ],
         "responseErrorFields":[
            {
               "value":"{{error.message}}",
               "name":"message"
            }
         ]
      },
      "validate":{
         "url":"https://api.moviestar.com/v1.0/permissions?access_token={{authData.accessToken}}",
         "httpMethod":"GET",
         "headers":[
            {
               "value":"application/x-www-form-urlencoded",
               "header":"Content-Type"
            }
         ],
         "responseFields":[
            {
               "value":"{{response.data[0].permission}}",
               "name":"Id"
            }
         ],
         "responseErrorFields":[
            {
               "value":"{{error.message}}",
               "name":"message"
            }
         ]
      }
   }
}

擷取對象範本清單

您可以向提出GET請求,以擷取IMS組織的所有對象範本清單 /authoring/audience-templates 端點。

API格式

GET /authoring/audience-templates

要求

下列請求會根據IMS組織和沙箱設定,擷取您有權存取的對象範本清單。

curl -X GET https://platform.adobe.io/data/core/activation/authoring/audience-templates \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

回應

下列回應會根據您使用的IMS組織ID和沙箱名稱,傳回HTTP狀態200,並包含您可存取的對象中繼資料範本清單。 一 instanceId 對應至一個目的地的範本。 回應會為簡潔而截斷。

{
   "items":[
      {
         "instanceId":"12a3238f-b509-4a40-b8fb-0a5006e7901d",
         "createdDate":"2021-07-20T13:30:30.843054Z",
         "lastModifiedDate":"2021-07-21T16:33:05.787472Z",
         "metadataTemplate":{
            "create":{
               "url":"https://api.moviestar.com/v2/dmpSegments",
               "httpMethod":"POST",
               "headers":[
                  {
                     "value":"application/json",
                     "header":"Content-Type"
                  },
                  {
                     "value":"Bearer {{authData.accessToken}}",
                     "header":"Authorization"
                  }
               ],
               "requestBody":{
                  "json":{
                     "name":"{{segment.name}}",
                     "type":"USER",
                     "account":"{{customerData.accountId}}",
                     "accessPolicy":"PRIVATE",
                     "destinations":[
                        {
                           "destination":"MOVIESTAR"
                        }
                     ],
                     "sourcePlatform":"ADOBE"
                  }
               },
               "responseFields":[
                  {
                     "value":"{{headers.x-moviestar-id}}",
                     "name":"externalAudienceId"
                  }
               ],
               "responseErrorFields":[
                  {
                     "value":"{{message}}",
                     "name":"message"
                  }
               ]
            },
            "update":{
               "url":"https://api.moviestar.com/v2/dmpSegments/{{segment.alias}}",
               "httpMethod":"POST",
               "headers":[
                  {
                     "value":"application/json",
                     "header":"Content-Type"
                  },
                  {
                     "value":"Bearer {{authData.accessToken}}",
                     "header":"Authorization"
                  }
               ],
               "requestBody":{
                  "json":{
                     "patch":{
                        "$set":{
                           "name":"{{segment.name}}"
                        }
                     }
                  }
               },
               "responseErrorFields":[
                  {
                     "value":"{{message}}",
                     "name":"message"
                  }
               ]
            },
            "delete":{
               "url":"https://api.moviestar.com/v2/dmpSegments/{{segment.alias}}",
               "httpMethod":"DELETE",
               "headers":[
                  {
                     "value":"application/json",
                     "header":"Content-Type"
                  },
                  {
                     "value":"Bearer {{authData.accessToken}}",
                     "header":"Authorization"
                  }
               ],
               "responseErrorFields":[
                  {
                     "value":"{{message}}",
                     "name":"message"
                  }
               ]
            },
            "name":"Moviestar audience template - Third example"
         }
      }
   ]
}

擷取特定對象範本

您可以向提出GET要求,以擷取特定對象範本的詳細資訊 /authoring/audience-templates 端點,並提供您要擷取之對象範本的例項ID。

API格式

GET /authoring/audience-templates/{INSTANCE_ID}
參數 說明
{INSTANCE_ID} 您要擷取的對象中繼資料範本ID。

要求

curl -X GET https://platform.adobe.io/data/core/activation/authoring/audience-templates/bd4ec8f0-e98f-4b6a-8064-dd7adbfffec9 \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

回應

成功的回應會傳回HTTP狀態200,並包含指定對象範本的詳細資訊。

{
   "instanceId":"34ab9cc2-2536-44a5-9dc5-b2fea60b3bd6",
   "createdDate":"2021-07-26T19:30:52.012490Z",
   "lastModifiedDate":"2021-07-27T21:25:42.763478Z",
   "metadataTemplate":{
      "create":{
         "url":"https://api.moviestar.com/v1/adaccounts/{{customerData.accountId}}/segments",
         "httpMethod":"POST",
         "headers":[
            {
               "value":"application/json",
               "header":"Content-Type"
            },
            {
               "value":"Bearer {{oauth2ServiceAccessToken}}",
               "header":"Authorization"
            }
         ],
         "requestBody":{
            "json":{
               "segments":[
                  {
                     "name":"{{segment.name}}",
                     "description":"{{segment.description}}",
                     "source_type":"FIRST_PARTY",
                     "ad_account_id":"{{customerData.accountId}}",
                     "retention_in_days":180
                  }
               ]
            }
         },
         "responseFields":[
            {
               "value":"{{body.segments[0].segment.id}}",
               "name":"externalAudienceId"
            }
         ],
         "responseErrorFields":[
            {
               "value":"{{root}}",
               "name":"message"
            }
         ]
      },
      "update":{
         "url":"https://adsapi.moviestar.com/v1/adaccounts/{{customerData.accountId}}/segments",
         "httpMethod":"PUT",
         "headers":[
            {
               "value":"application/json",
               "header":"Content-Type"
            },
            {
               "value":"Bearer {{oauth2ServiceAccessToken}}",
               "header":"Authorization"
            }
         ],
         "requestBody":{
            "json":{
               "segments":[
                  {
                     "id":"{{segment.alias}}",
                     "name":"{{segment.name}}",
                     "description":"{{segment.description}}"
                  }
               ]
            }
         },
         "responseFields":[
            {
               "value":"{{body.segments[0].segment.id}}",
               "name":"externalAudienceId"
            }
         ],
         "responseErrorFields":[
            {
               "value":"{{root}}",
               "name":"message"
            }
         ]
      },
      "delete":{
         "url":"https://adsapi.moviestar.com/v1/segments/{{segment.alias}}",
         "httpMethod":"DELETE",
         "headers":[
            {
               "value":"application/json",
               "header":"Content-Type"
            },
            {
               "value":"Bearer {{oauth2ServiceAccessToken}}",
               "header":"Authorization"
            }
         ],
         "responseErrorFields":[
            {
               "value":"{{root}}",
               "name":"message"
            }
         ]
      },
      "name":"Moviestar destination audience template - Example 1"
   }
}

刪除特定對象範本

您可以透過向 /authoring/audience-templates 端點,並提供您要在請求路徑中刪除之對象範本的ID。

API格式

DELETE /authoring/audience-templates/{INSTANCE_ID}
參數 說明
{INSTANCE_ID} id 對象範本中。

要求

curl -X DELETE https://platform.adobe.io/data/core/activation/authoring/audience-templates/bd4ec8f0-e98f-4b6a-8064-dd7adbfffec9 \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}' \

回應

成功的回應會傳回HTTP狀態200,並傳回空的HTTP回應。

API錯誤處理

Destination SDKAPI端點遵循一般Experience PlatformAPI錯誤訊息原則。 請參閱 API狀態代碼請求標題錯誤 (位於平台疑難排解指南中)。

後續步驟

閱讀本檔案後,您現在知道何時該使用對象中繼資料範本,以及如何使用設定對象中繼資料範本 /authoring/audience-templates API端點。 閱讀 如何使用Destination SDK來設定您的目的地 了解此步驟在設定目的地程式中的適用位置。

本頁內容