オーディエンスメタデータの管理

最終更新日： 2026年9月24日

トピック：
プロファイル

作成対象：

ユーザー
管理

オーディエンスメタデータテンプレートを使用して、宛先のオーディエンスをプログラムで作成、更新または削除します。アドビは、マーケティング API の仕様に基づいて設定できる、拡張可能なオーディエンスメタデータテンプレートを提供します。設定を定義、テスト、送信すると、アドビはこの設定を使用して、宛先への API 呼び出しを構造化します。

/authoring/audience-templates API エンドポイントを使用して、このドキュメントで説明する機能を設定できます。エンドポイントで実行できる操作の完全なリストには、メタデータテンプレートの作成を参照してください。

オーディエンスメタデータ管理エンドポイントを使用するタイミング when-to-use

API の設定に応じて、Experience Platform で宛先を設定する際に、オーディエンスメタデータ管理エンドポイントを使用する必要がある場合と必要がない場合があります。以下の決定ツリー図を使用して、オーディエンスメタデータエンドポイントを使用するタイミングと、宛先に対するオーディエンスメタデータテンプレートの設定方法を理解します。

決定ツリー図

オーディエンスメタデータ管理でサポートされるユースケース use-cases

Destination SDKのオーディエンスメタデータのサポートにより、Experience Platformの宛先を設定する際に、Experience Platform ユーザーが宛先にオーディエンスをマッピングしてアクティブ化する際に、いくつかのオプションのいずれかを提供できます。宛先設定のオーディエンスメタデータ設定セクションのパラメーターで、ユーザーが利用できるオプションを制御できます。

ユースケース 1：サードパーティ APIとの自動同期 use-case-1

オーディエンスを作成、更新、削除するAPI エンドポイントがある場合は、オーディエンスメタデータテンプレートを使用して、オーディエンスの作成、更新、削除エンドポイントの仕様に合わせてDestination SDKを設定できます。 Experience Platformでは、オーディエンスをプログラムで作成、更新、削除し、メタデータをExperience Platformに同期できます。

Experience Platform ユーザーインターフェイス（UI）で宛先に対してオーディエンスをアクティブ化する場合、ユーザーはアクティベーションワークフローでオーディエンスマッピング ID フィールドに手動で入力する必要はありません。

ユースケース 2：手動マッピング IDが必要 use-case-2

オーディエンスおよびその他のメタデータを宛先でパートナーまたはユーザーが手動で作成する必要がある場合、ユーザーはアクティベーションワークフローのオーディエンスマッピング ID フィールドに手動で入力して、宛先とExperience Platform間でオーディエンスメタデータを同期する必要があります。

入力マッピング ID

ユースケース 3：ネイティブオーディエンス IDのサポート use-case-3

宛先のシステムで Experience Platform オーディエンス ID を使用できる場合は、オーディエンスメタデータテンプレートでそれを設定できます。オーディエンスをアクティベートする際に、オーディエンスマッピング IDを入力する必要はありません。

汎用で拡張可能なオーディエンステンプレート generic-and-extensible

前述の使用例をサポートするために、アドビでは、API の仕様に合わせてカスタマイズできる汎用テンプレートを提供しています。

お使いの API が以下をサポートしている場合、汎用テンプレートを使用して新しいオーディエンステンプレートを作成できます。

HTTP メソッド：POST、GET、PUT、DELETE、PATCH。
認証タイプは、OAuth 1、OAuth 2（更新トークン）、OAuth 2（Bearer トークン）です。
関数は、オーディエンスの作成、オーディエンスの更新、オーディエンスの取得、オーディエンスの削除、資格情報の検証を行うことができます。

ユースケースで必要な場合は、Adobeのエンジニアリングチームと協力して、カスタムフィールドを含む汎用テンプレートを拡張できます。

サポートされているテンプレートイベント supported-events

次の表に、オーディエンスメタデータテンプレートでサポートされるイベントを示します。

テンプレートセクション

説明

create

APIにHTTP呼び出しを行うために必要なすべてのコンポーネント（URL、HTTP メソッド、ヘッダー、リクエストおよび応答本文）を含め、プラットフォームでセグメント/オーディエンスをプログラムで作成し、情報をAdobe Experience Platformに同期します。

update

APIへのHTTP呼び出しを行うために必要なすべてのコンポーネント（URL、HTTP メソッド、ヘッダー、リクエストおよび応答本文）を含め、プラットフォームのセグメントまたはオーディエンスをプログラムで更新し、情報をAdobe Experience Platformに同期します。

delete

API への HTTP 呼び出しに必要なすべてのコンポーネント（URL、HTTP メソッド、ヘッダー、リクエストおよび応答本文）を含めて、プラットフォームのセグメントやオーディエンスをプログラムで削除します。

validate

パートナー API を呼び出す前に、テンプレート設定のすべてのフィールドの検証を実行します。例えば、ユーザーのアカウント ID が正しく入力されていることを検証できます。

notify

ファイルベースの宛先にのみ適用されます。 API への HTTP 呼び出しに必要なすべてのコンポーネント（URL、HTTP メソッド、ヘッダー、リクエストおよび応答本文）を含めて、ファイルの書き出しが正常に行われたことを通知します。

createDestination

APIにHTTP呼び出しを行うために必要なすべてのコンポーネント（URL、HTTP メソッド、ヘッダー、リクエストおよび応答本文）を含め、プラットフォームでプログラムによってデータフローを作成し、情報をAdobe Experience Platformに同期します。

updateDestination

APIへのHTTP呼び出しを行うために必要なすべてのコンポーネント（URL、HTTP メソッド、ヘッダー、リクエストおよび応答本文）を含め、プラットフォームのデータフローをプログラムで更新し、情報をAdobe Experience Platformに同期します。

deleteDestination

APIへのHTTP呼び出しを行い、プラットフォームからデータフローをプログラムで削除するために必要なすべてのコンポーネント（URL、HTTP メソッド、ヘッダー、リクエストおよび応答本文）が含まれます。

設定例 configuration-examples

この節では、参照用に、一般的なオーディエンスメタデータ設定の例を示します。

URL、ヘッダー、リクエスト本文が、3つの設定例で異なることに注意してください。これは、3 つのサンプルプラットフォームのマーケティング API の仕様が異なるためです。

一部の例では、{{authData.accessToken}} または {{segment.name}} などのマクロフィールドは URL で、その他の例ではヘッダーまたはリクエスト本文で使用されます。使用方法は、マーケティング APIの仕様によって異なります。

TIP

オーディエンスメタデータテンプレートのヘッダー値は、小石テンプレートをサポートしています。例えば、宛先で基本認証を使用しており、特定のBase64 エンコードされたAuthorization ヘッダーが必要な場合は、create、update、delete、validate、createDestination、updateDestination、deleteDestinationなど、APIを呼び出し、認証を必要とする各操作ブロックにヘッダーを追加します。

code language-json

{
      "metadataTemplate": {
          "create": {
              "headers": [
                  {
                      "header": "Authorization",
                      "value": "Basic {{ (authData.username + ':' + authData.password) | base64encode }}"
                  }
              ]
          },
          "update": {
              "headers": [
                  {
                      "header": "Authorization",
                      "value": "Basic {{ (authData.username + ':' + authData.password) | base64encode }}"
                  }
              ]
          }
      }
    }

詳しくは、基本認証ヘッダーのカスタマイズを参照してください。

ストリーミングの例 1

code language-json

{
   "instanceId":"34ab9cc2-2536-44a5-9dc5-b2fea60b3bd6",
   "createdDate":"2021-07-26T19:30:52.012490Z",
   "lastModifiedDate":"2021-07-27T21:25:42.763478Z",
   "metadataTemplate":{
      "create":{
         "url":"https://adsapi.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/{{segment.alias}}",
         "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/adaccounts/{{customerData.accountId}}/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"
   }
}

ストリーミングの例 2

code language-json

{
   "instanceId":"12c78017-5af3-4d4e-8f9c-d330c547c482",
   "createdDate":"2021-07-20T13:27:37.029490Z",
   "lastModifiedDate":"2021-07-20T18:53:03.622306Z",
   "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"
            }
         ]
      }
   }
}

ストリーミングの例 3

code language-json

{
   "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"
   }
}

ファイルベースの例

code language-json

{
   "instanceId":"34ab9cc2-2536-44a5-9dc5-b2fea60b3bd6",
   "createdDate":"2021-07-26T19:30:52.012490Z",
   "lastModifiedDate":"2021-07-27T21:25:42.763478Z",
   "metadataTemplate":{
      "create":{
         "url":"https://adsapi.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/{{segment.alias}}",
         "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"
            }
         ]
      },
      "notify":{
         "url":"https://adsapi.moviestar.com/v1/adaccounts/{{customerData.accountId}}/segments/{{segment.alias}}",
         "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/adaccounts/{{customerData.accountId}}/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"
   }
}

テンプレートのすべてのパラメーターについては、オーディエンステンプレートの作成 API リファレンスを参照してください。

オーディエンスメタデータテンプレートで使用されるマクロ macros

Experience Platform と API の間でオーディエンス ID、アクセストークン、エラーメッセージなどの情報を渡すために、オーディエンステンプレートには使用できるマクロが含まれています。次の表に、このページの3つの設定例で使用されるマクロを示します。

マクロ

説明

{{segment.alias}}

Experience Platformのオーディエンスエイリアスにアクセスします。

{{segment.name}}

Experience Platformのオーディエンス名にアクセスします。

{{segment.id}}

Experience Platformのオーディエンス IDにアクセスします。

{{customerData.accountId}}

宛先設定で設定したアカウント ID フィールドにアクセスします。

{{oauth2ServiceAccessToken}}

OAuth 2設定に基づいてアクセストークンを動的に生成します。

{{authData.accessToken}}

アクセストークンをAPI エンドポイントに渡します。 Experience Platform が期限切れでないトークンを使用して宛先に接続する場合は、{{authData.accessToken}} を使用します。そうでない場合は、{{oauth2ServiceAccessToken}} を使用してアクセストークンを生成します。

{{body.segments[0].segment.id}}

作成されたオーディエンスの一意の ID をキー externalAudienceId の値として返します。

{{error.message}}

Experience Platform UI でユーザーに表示されるエラーメッセージを返します。

{{{segmentEnrichmentAttributes}}}

特定のオーディエンスに対するすべてのエンリッチメント属性にアクセスします。このマクロは、create、update、delete イベントでサポートされています。エンリッチメント属性は、カスタムアップロードオーディエンスでのみ使用できます。エンリッチメント属性の選択がどのように機能するかについては、バッチオーディエンスアクティベーションガイドを参照してください。

{{destination.name}}

宛先の名前を返します。

{{destination.sandboxName}}

宛先が設定されているExperience Platform サンドボックスの名前を返します。

{{destination.id}}

宛先設定のIDを返します。

{{destination.imsOrgId}}

宛先が設定されているIMS組織IDを返します。

{{destination.enrichmentAttributes}}

宛先にマッピングされたすべてのオーディエンスのすべてのエンリッチメント属性にアクセスします。このマクロは、createDestination、updateDestination、deleteDestination イベントでサポートされています。エンリッチメント属性は、カスタムアップロードオーディエンスでのみ使用できます。エンリッチメント属性の選択がどのように機能するかについては、バッチオーディエンスアクティベーションガイドを参照してください。

{{destination.enrichmentAttributes.<namespace>.<segmentId>}}

宛先にマッピングされた特定の外部オーディエンスのエンリッチメント属性にアクセスします。エンリッチメント属性は、カスタムアップロードオーディエンスでのみ使用できます。エンリッチメント属性の選択がどのように機能するかについては、バッチオーディエンスアクティベーションガイドを参照してください。

recommendation-more-help

experience-platform-help-destinations