配置目的地

IngestAudienceMembersRequestIngestEventsRequest 中的每个 Destination 都会定义:

  1. 接收数据的账号。例如,Google Ads 账号或 Google Analytics 媒体资源。
  2. 账号内数据的目标实体,例如 Google Ads 转化操作或 Google Analytics 数据流。
  3. 请求的凭据到接收数据的账号的访问路径。

如果您是广告客户或代理机构,请跳到广告客户场景,查看有关如何构建 Destination 的示例:

如果您是数据合作伙伴,请跳至数据合作伙伴方案,查看如何构建 Destination 以将数据发送到与您的数据合作伙伴账号具有商品链接的账号的示例:

详细要求部分深入介绍了相关要求和验证规则。

广告客户场景

下面介绍了如何针对广告客户和代理机构的常见情况配置 Destination。此图显示了 Data Manager API 如何使用凭据和 Destination 字段来访问广告客户账号。

广告客户访问权限路径

Google Ads

下图展示了一组 Google Ads 账号和用户的示例。

Google Ads 账号和用户

经理账号 M1

M1 有两个直接子账号:

  1. 经理账号 M2
  2. 客户账号 C1

Google 账号 cloudysanfrancisco@gmail.com 是 M1 中的用户。

经理账号 M2

M2 有两个直接子账号:

  1. 客户账号 C1
  2. 客户账号 C2

Google 账号 baklavainthebalkans@gmail.com 是 M2 中的用户。

客户账号 C1

C1 有两个直接父级经理账号:

  1. 经理账号 M1
  2. 经理账号 M2

Google 账号 jeffersonloveshiking@gmail.com 是 C1 中的用户。

客户账号 C2

经理账号 M2 是客户账号 C2 的唯一直接父级账号。

所列出的 Google 账号都不是 C2 中的用户。

直接访问方案经理账号访问方案展示了如何配置目的地以将数据发送到这些账号。

直接访问方案

如果您想将数据发送到某个 Google Ads 账号,但您的凭据是 Google Ads 账号中某个用户的 Google 账号的凭据,请执行以下操作:

目的地
operating_account
account_id Google Ads 账号的客户 ID
account_type GOOGLE_ADS
login_account 请勿设置 login_account,或将其设置为与 operating_account 相同的值。
linked_account 请勿设置 linked_account 字段。
product_destination_id 相应受众群体或转化操作的 ID。

以下是直接访问方案的示例,其中使用了图表中的账号和 Google 账号 jeffersonloveshiking@gmail.com 的凭据。

{
  "destinations": [
    {
      "operatingAccount": {
        "accountId": "C1_CUSTOMER_ID",
        "accountType": "GOOGLE_ADS"

      },
      "loginAccount": {
        "accountId": "C1_CUSTOMER_ID",
        "accountType": "GOOGLE_ADS"

      },
      "productDestinationId": "USER_LIST_ID"
    }
  ]
}

经理账号访问权限场景

如果您想将数据发送到 Google Ads 账号,但您的凭据是 Google 账号的凭据,而该 Google 账号是 Google Ads 经理账号中的用户,并且广告客户账号是子账号,请执行以下操作:

目的地
operating_account
account_id Google Ads 客户账号的客户 ID
account_type GOOGLE_ADS
login_account
account_id Google Ads 经理账号的客户 ID
account_type GOOGLE_ADS
linked_account 请勿设置 linked_account 字段。
product_destination_id 相应受众群体或转化操作的 ID。

以下示例展示了图表中 Google Ads 客户账号 C2 的经理账号访问权限场景,以及 Google 账号 baklavainthebalkans@gmail.com 的凭据:

{
  "destinations": [
    {
      "operatingAccount": {
        "accountId": "C2_CUSTOMER_ID",
        "accountType": "GOOGLE_ADS"
      },
      "loginAccount": {
        "accountId": "M2_CUSTOMER_ID",
        "accountType": "GOOGLE_ADS"
      },
      "productDestinationId": "USER_LIST_ID"
    }
  ]
}

下面是另一个示例,展示了 Google Ads 客户账号 C2 的经理访问权限场景,以及 Google 账号 cloudysanfrancisco@gmail.com 的凭据(该账号是 Google Ads 经理账号 M1 的用户):

{
  "destinations": [
    {
      "operatingAccount": {
        "accountId": "C2_CUSTOMER_ID",
        "accountType": "GOOGLE_ADS"
      },
      "loginAccount": {
        "accountId": "M1_CUSTOMER_ID",
        "accountType": "GOOGLE_ADS"
      },
      "productDestinationId": "USER_LIST_ID"
    }
  ]
}

Display & Video 360

您可以使用以下两种方法将数据发送到 Display & Video 360:

  1. 直接访问,即凭据属于 Display & Video 360 广告客户账号或合作伙伴账号中的用户所用的 Google 账号。
  2. Display & Video 360 合作伙伴访问权限,其中凭据是 Display & Video 360 合作伙伴账号中用户的 Google 账号,而操作账号是相应合作伙伴账号下的 Display & Video 360 广告客户账号。

直接访问方案

如果您想将数据发送到 Display & Video 360 广告客户账号,但您的凭据所对应的 Google 账号是该广告客户账号中的用户,请执行以下操作:

目的地
operating_account
account_id Display & Video 360 广告客户账号的 ID
account_type DISPLAY_VIDEO_ADVERTISER
login_account 请勿设置 login_account,或将其设置为与 operating_account 相同的值。
linked_account 请勿设置 linked_account 字段。
product_destination_id 受众群体的 ID。

以下示例展示了直接访问场景的 Destination,用于将数据发送给 Display & Video 360 广告客户

{
  "destinations": [
    {
      "operatingAccount": {
        "accountId": "ADVERTISER_ID",
        "accountType": "DISPLAY_VIDEO_ADVERTISER"
      },
      "loginAccount": {
        "accountId": "ADVERTISER_ID",
        "accountType": "DISPLAY_VIDEO_ADVERTISER"
      },
      "productDestinationId": "AUDIENCE_ID"
    }
  ]
}

同样,如果您想将数据发送到 Display & Video 360 合作伙伴账号,但您的凭据对应的 Google 账号是该合作伙伴账号中的用户,则:

目的地
operating_account
account_id Display & Video 360 合作伙伴账号的 ID
account_type DISPLAY_VIDEO_PARTNER
login_account 请勿设置 login_account,或将其设置为与 operating_account 相同的值。
linked_account 请勿设置 linked_account 字段。
product_destination_id 受众群体的 ID。

以下示例展示了直接访问场景中用于将数据发送给 Display & Video 360 合作伙伴Destination

{
  "destinations": [
    {
      "operatingAccount": {
        "accountId": "PARTNER_ID",
        "accountType": "DISPLAY_VIDEO_PARTNER"
      },
      "loginAccount": {
        "accountId": "PARTNER_ID",
        "accountType": "DISPLAY_VIDEO_PARTNER"
      },
      "productDestinationId": "AUDIENCE_ID"
    }
  ]
}

Display & Video 360 合作伙伴访问权限方案

如果您想将数据发送给 Display & Video 360 广告客户,并且您的凭据对应的 Google 账号是该广告客户的父 Display & Video 360 合作伙伴账号中的用户,请执行以下操作:

目的地
operating_account
account_id Display & Video 360 广告客户账号的 ID
account_type DISPLAY_VIDEO_ADVERTISER
login_account
account_id Display & Video 360 合作伙伴账号的 ID
account_type DISPLAY_VIDEO_PARTNER
linked_account 请勿设置 linked_account 字段。
product_destination_id 受众群体的 ID。

以下示例展示了合作伙伴访问权限场景的 Destination,用于将数据发送给 Display & Video 360 广告客户。在这种情况下,凭据必须是 Display & Video 360 合作伙伴账号 PARTNER_ID 中的用户的 Google 账号凭据,并且 Display & Video 360 广告客户账号 ADVERTISER_ID 必须是合作伙伴账号 PARTNER_ID 的子账号。

{
  "destinations": [
    {
      "operatingAccount": {
        "accountId": "ADVERTISER_ID",
        "accountType": "DISPLAY_VIDEO_ADVERTISER"
      },
      "loginAccount": {
        "accountId": "PARTNER_ID",
        "accountType": "DISPLAY_VIDEO_PARTNER"
      },
      "productDestinationId": "AUDIENCE_ID"
    }
  ]
}

Google Analytics

注意:当目标是 Google Analytics 账号时,operating_accountlogin_account 必须完全相同。否则,请求将失败并显示错误 OPERATING_ACCOUNT_LOGIN_ACCOUNT_MISMATCH

目的地
operating_account
account_id Google Analytics 媒体资源的 ID
account_type GOOGLE_ANALYTICS_PROPERTY
login_account 请勿设置 login_account,或将其设置为与 operating_account 相同的值。
linked_account 请勿设置 linked_account 字段。
product_destination_id 数据流的衡量 ID

以下是一个用于向 Google Analytics 发送事件的 Destination 示例:

{
  "destinations": [
    {
      "operatingAccount": {
        "accountId": "PROPERTY_ID",
        "accountType": "GOOGLE_ANALYTICS_PROPERTY"
      },
      "loginAccount": {
        "accountId": "PROPERTY_ID",
        "accountType": "GOOGLE_ANALYTICS_PROPERTY"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ]
}

数据合作伙伴方案

以下是针对数据合作伙伴的常见场景配置 Destination 的方法,该数据合作伙伴会将数据发送到与数据合作伙伴账号建立产品关联的广告客户账号。

此图显示了 Data Manager API 如何使用凭据和 Destination 字段通过产品关联访问广告客户账号。

数据合作伙伴访问路径

Google Ads

下图显示了一组 Google Ads 账号和数据合作伙伴账号的示例。该图还显示了每个 Google Ads 或数据合作伙伴账号中的用户所用的 Google 账号,以及账号之间的产品关联。

数据合作伙伴、Google Ads 账号和用户

数据合作伙伴 D1

D1 与 Google Ads 经理账号 M2 之间存在产品关联。

Google 账号 222larabrown@gmail.com 是 D1 中的用户。

数据合作伙伴 D2

D2 与 Google Ads 客户账号 C1 之间存在产品关联。

Google 账号 jeffersonloveshiking@gmail.com 是 D2 中的用户。

经理账号 M1

M1 有两个直接子账号:

  1. 经理账号 M2
  2. 客户账号 C1
经理账号 M2

M2 有两个直接子账号:

  1. 客户账号 C1
  2. 客户账号 C2
客户账号 C1

C1 有两个直接父级经理账号:

  1. 经理账号 M1
  2. 经理账号 M2
客户账号 C2

经理账号 M2 是客户账号 C2 的唯一直接父级账号。

您可以使用这组账号执行以下操作:

作为数据合作伙伴 D1

如需充当数据合作伙伴 D1,请使用 Google 账号 222larabrown@gmail.com 的凭据,通过将 login_account 设置为数据合作伙伴账号 D1 且将 linked_account 设置为经理账号 M2 的目的地,将数据发送到经理账号 M2、客户账号 C1 或客户账号 C2。

作为数据合作伙伴 D1,您无法向经理账号 M1 发送数据,因为 D1 和 M1 之间没有产品关联。

以数据合作伙伴 D2 的身份行事

如需充当数据合作伙伴 D2,请使用 Google 账号 jeffersonloveshiking@gmail.com 的凭据将数据发送到客户账号 C1,并使用将 login_account 设置为数据合作伙伴账号 D2 且将 linked_account 设置为客户账号 C1 的目的地。

作为数据合作伙伴 D2,您无法向经理账号 M1、经理账号 M2 或客户账号 C2 发送数据,因为 D2 与这些账号或其父级经理账号之间没有商品关联。

数据合作伙伴 D1 和 D2 之间的主要区别在于数据合作伙伴与 Google Ads 账号的关联方式。

直接商品链接方案

如果您想将数据发送到 Google Ads 账号,并且产品关联是在 Google Ads 账号与您的数据合作伙伴账号之间建立的,请执行以下操作:

目的地
operating_account
account_id Google Ads 账号的客户 ID
account_type GOOGLE_ADS
login_account
account_id 数据合作伙伴账号的客户 ID
account_type DATA_PARTNER
linked_account 请勿设置 linked_account 字段。
product_destination_id 相应受众群体或转化操作的 ID。

下面是一个使用图表中账号的直接商品链接方案示例。在这种情况下,数据合作伙伴 D2 使用 D2 与 Google Ads 客户 C1 之间的产品关联以及 Google 账号 jeffersonloveshiking@gmail.com 的凭据,将受众群体成员数据发送给 Google Ads 客户 C1:

{
  "destinations": [
    {
      "operatingAccount": {
        "accountId": "C1_CUSTOMER_ID",
        "accountType": "GOOGLE_ADS"
      },
      "loginAccount": {
        "accountId": "D2_CUSTOMER_ID",
        "accountType": "DATA_PARTNER"
      },
      "productDestinationId": "USER_LIST_ID"
    }
  ]
}

经理账号产品关联方案

如果您想将数据发送到 Google Ads 账号,并且产品关联是在父 Google Ads 经理账号与数据合作伙伴账号之间建立的,请执行以下操作:

目的地
operating_account
account_id Google Ads 客户账号的客户 ID
account_type GOOGLE_ADS
login_account
account_id 数据合作伙伴账号的客户 ID
account_type DATA_PARTNER
linked_account
account_id Google Ads 经理账号的客户 ID
account_type GOOGLE_ADS
product_destination_id 相应受众群体或转化操作的 ID。

下面是一个使用图表中的账号的经理账号商品关联方案示例。在这种情况下,数据合作伙伴 D1 使用 D1 与 M2 之间的产品关联以及 Google 账号 222larabrown@gmail.com 的凭据,将受众群体成员数据发送给 Google Ads 客户 C2:

{
  "destinations": [
    {
      "operatingAccount": {
        "accountId": "C2_CUSTOMER_ID",
        "accountType": "GOOGLE_ADS"
      },
      "loginAccount": {
        "accountId": "D1_CUSTOMER_ID",
        "accountType": "DATA_PARTNER"
      },
      "linkedAccount": {
        "accountId": "M2_CUSTOMER_ID",
        "accountType": "GOOGLE_ADS"
      },
      "productDestinationId": "USER_LIST_ID"
    }
  ]
}

Display & Video 360

作为数据合作伙伴,您可以使用以下两种方法将数据发送到 Display & Video 360 账号:

  1. 使用数据合作伙伴账号与 Display & Video 360 合作伙伴账号或广告客户账号之间的直接产品关联。
  2. 使用数据合作伙伴账号与广告客户的父 Display & Video 360 合作伙伴账号之间的产品关联,将数据发送给 Display & Video 360 广告客户。

如果您想将数据发送给 Display & Video 360 广告客户,并且产品关联是在 Display & Video 360 广告客户账号与您的数据合作伙伴账号之间建立的,请执行以下操作:

目的地
operating_account
account_id Display & Video 360 广告客户账号的 ID
account_type DISPLAY_VIDEO_ADVERTISER
login_account
account_id 数据合作伙伴账号的客户 ID
account_type DATA_PARTNER
linked_account 请勿设置 linked_account 字段。
product_destination_id 相应受众群体或转化操作的 ID。

以下示例展示了直接产品关联方案的 Destination,用于将数据发送给 Display & Video 360 广告客户:

{
  "destinations": [
    {
      "operatingAccount": {
        "accountId": "ADVERTISER_ID",
        "accountType": "DISPLAY_VIDEO_ADVERTISER"
      },
      "loginAccount": {
        "accountId": "DATA_PARTNER_ID",
        "accountType": "DATA_PARTNER"
      },
      "productDestinationId": "AUDIENCE_ID"
    }
  ]
}

如果您想将数据发送到 Display & Video 360 合作伙伴账号,则必须在 Display & Video 360 合作伙伴账号与您的数据合作伙伴账号之间建立产品关联。

目的地
operating_account
account_id Display & Video 360 合作伙伴账号的 ID
account_type DISPLAY_VIDEO_PARTNER
login_account
account_id 数据合作伙伴账号的客户 ID
account_type DATA_PARTNER
linked_account 请勿设置 linked_account 字段。
product_destination_id 相应受众群体或转化操作的 ID。

以下示例展示了如何使用 Destination 在直接产品链接方案中向 Display & Video 360 合作伙伴发送数据:

{
  "destinations": [
    {
      "operatingAccount": {
        "accountId": "DISPLAY_VIDEO_PARTNER_ID",
        "accountType": "DISPLAY_VIDEO_PARTNER"
      },
      "loginAccount": {
        "accountId": "DATA_PARTNER_ID",
        "accountType": "DATA_PARTNER"
      },
      "productDestinationId": "AUDIENCE_ID"
    }
  ]
}

如果您想将数据发送到 Display & Video 360 广告客户,并且您与数据合作伙伴账号的产品关联是与 Display & Video 360 合作伙伴账号建立的,而该广告客户账号是该合作伙伴账号的子账号,请执行以下操作:

目的地
operating_account
account_id Display & Video 360 广告客户账号的 ID
account_type DISPLAY_VIDEO_ADVERTISER
login_account
account_id 数据合作伙伴账号的客户 ID
account_type DATA_PARTNER
linked_account
account_id Display & Video 360 合作伙伴账号的 ID
account_type DISPLAY_VIDEO_PARTNER
product_destination_id 相应受众群体或转化操作的 ID。

以下示例展示了合作伙伴产品关联方案的 Destination,该方案使用数据合作伙伴与广告客户的父 Display & Video 360 合作伙伴之间的产品关联,将数据发送给 Display & Video 360 广告客户:

{
  "destinations": [
    {
      "operatingAccount": {
        "accountId": "DISPLAY_VIDEO_ADVERTISER_ID",
        "accountType": "DISPLAY_VIDEO_ADVERTISER"
      },
      "loginAccount": {
        "accountId": "DATA_PARTNER_ID",
        "accountType": "DATA_PARTNER"
      },
      "linkedAccount": {
        "accountId": "DISPLAY_VIDEO_PARTNER_ID",
        "accountType": "DISPLAY_VIDEO_PARTNER"
      },
      "productDestinationId": "AUDIENCE_ID"
    }
  ]
}

Google Analytics

Data Manager API 不支持通过产品关联将数据发送到 Google Analytics 账号。请改用 Google Analytics 的广告客户方案方法。

详细要求

本部分包含有关 Destination账号字段的详细要求、有关如何设置 product_destination_id 的提示,以及如何确定您的凭据具有哪些访问权限

账户字段

一张 Destination 最多可关联 3 个不同的账号:

operating_account

operating_account必需的。

operating_account 用于指明请求中的数据将发送到哪个账号。operating_account 可以是以下任一值:

login_account

login_account 并非始终必需,默认值为 operating_account

Data Manager API 会验证以下内容:

  1. 凭据的 Google 账号是 login_account 中的用户。

  2. login_account 是以下类型之一:

    • operating_account 相同。如果您未设置 login_account,则此值为默认值。

    • operating_account 的父级 Google Ads 经理账号或 Display & Video 360 合作伙伴账号。

    • 数据合作伙伴账号,其中包含指向 linked_account 的产品链接。

linked_account

linked_account 表示哪个账号与 login_account 之间存在产品关联。

商品目的地 ID

Destinationproduct_destination_id 用于标识 operating_account 中的哪个对象接收数据。例如,这可以是 Google Ads 或 Display & Video 360 的受众群体 ID、Google Ads 的转化操作 ID,也可以是 Google Analytics 数据流的衡量 ID

下面介绍了如何查找每种类型的商品目标平台的 ID。

Google Ads 受众群体

用于接收受众群体的商品目的地 ID 是受众群体 ID。

如需从 Google Ads 界面获取受众群体 ID,请执行以下操作:

  1. 前往 Google Ads 界面中的受众群体管理器
  2. 点击受众群体名称即可查看详细信息。
  3. 受众群体 ID 列在名单 ID 旁边。

如需通过 Google Ads API 获取受众群体 ID,请执行以下操作:

  1. GoogleAdsService 发送 SearchSearchStream 请求,并包含以下查询:

    SELECT
      user_list.id,
      user_list.name
    FROM user_list
    WHERE user_list.name = 'USER_LIST_NAME'
    
  2. 从响应中 user_listid 字段获取受众群体 ID。

    [
      {
        "results": [
          {
            "userList": {
              "resourceName": "customers/CUSTOMER_ID/userLists/USER_LIST_ID",
              "id": "USER_LIST_ID",
              "name": "USER_LIST_NAME"
            }
          }
        ]
      }
    ]
    

Google Ads 活动

用于提取事件的产品目标 ID 是转化操作 ID。

如需从 Google Ads 界面获取转化操作 ID,请执行以下操作:

  1. 前往 Google Ads 界面中的转化
  2. 点击转化操作名称即可查看详情。
  3. 转化操作 ID 是名为 ctId 的网址查询参数的值。

    https://ads.google.com/aw/conversions/detail?ocid=...&ctId=CONVERSION_ACTION_ID&...
    

如需通过 Google Ads API 获取转化操作 ID,请执行以下操作:

  1. GoogleAdsService 发送 SearchSearchStream 请求,并包含以下查询:

    SELECT
      conversion_action.id,
      conversion_action.name
    FROM conversion_action
    WHERE conversion_action.name = 'CONVERSION_ACTION_NAME'
    
  2. 从响应中 conversion_actionid 字段获取转化操作 ID。

    [
      {
        "results": [
          {
            "conversionAction": {
              "resourceName": "customers/CUSTOMER_ID/conversionActions/CONVERSION_ACTION_ID",
              "id": "CONVERSION_ACTION_ID",
              "name": "CONVERSION_ACTION_NAME"
            }
          }
        ]
      }
    ]
    

Display & Video 360 受众群体

用于接收受众群体的商品目的地 ID 是受众群体 ID。

如需从 Display & Video 360 界面获取受众群体 ID,请执行以下操作:

  1. 登录 Display & Video 360 界面 (https://displayvideo.google.com)。
  2. 前往您用于operating_account的 Display & Video 360 合作伙伴或广告客户。
  3. 前往左侧菜单中的受众群体,然后选择所有受众群体
  4. 在列表中找到相应受众群体。受众群体 ID 是名称列中名称旁边的数字。

Google Analytics 事件

用于接收事件的产品目标 ID 是数据流的衡量 ID

确定凭据的访问范围

您用于授权 Data Manager API 请求的凭据与特定的 Google 账号相关联。

  • 如果您使用用户凭据,则请求会以用户的 Google 账号进行授权,该用户在您生成凭据时授予了代表其执行操作的权限。
  • 如果您使用服务账号凭据,则请求会以服务账号的 Google 账号身份获得授权。

以下是验证您的凭据所对应的 Google 账号是否具有 Google Ads、Display & Video 360 或 Google Analytics 账号的访问权限的方法。

Google Ads 或数据合作伙伴

  1. 在 Google Ads 界面中,前往 login_account访问权限和安全
  2. 选择用户标签。
  3. 如果 login_account 是 Google Ads 经理账号,请关闭显示整个层次结构中的用户切换开关,以隐藏子级账号中的用户。
  4. 验证您的凭据所对应的 Google 账号是否位于用户标签页上显示的账号列表中。

Display & Video 360

  1. 在 Display & Video 360 界面中,前往用户管理和电子邮件接收设置
  2. 验证用户管理是否显示您的凭据所对应的 Google 账号是 login_account 上的用户。

Google Analytics

  1. 前往 Google Analytics 界面中的媒体资源访问权限管理
  2. 确认已选择 login_account 中指定的 Google Analytics 媒体资源。
  3. 验证您的凭据所对应的 Google 账号是否拥有相应媒体资源的“编辑者”或“管理员”角色