字段映射

使用字段映射将目标客户匹配工作流程的每个步骤从 Google Ads API 升级到 Data Manager API：

受众群体管理字段映射

使用表格中的映射关系，将 Google Ads API 中的 UserList 映射到数据管理器 API 中对应的 UserList。

UserList (Google Ads API) UserList（数据管理器 API） 备注
resource_name name 如需了解详情，请参阅资源名称。
id id
read_only read_only
name display_name 必需
description description 必需
membership_status membership_status
integration_code integration_code
membership_life_span membership_duration

受众群体成员被添加到名单后，在名单中保留的时长。该值必须对应于整数天数。如果未设置，则默认为最大值。

使用 Timestamp 格式设置值的格式。
size_for_display size_info.display_network_members_count
size_range_for_display 无对等项。 使用 size_info.display_network_members_count 获取尺寸信息。
size_for_search size_info.search_network_members_count
size_range_for_search 无对等项。 使用 size_info.search_network_members_count 获取尺寸信息。
type 无对等项。
access_reason access_reason
account_user_list_status account_access_status
closing_reason closing_reason
eligible_for_search target_network_info.eligible_for_search
eligible_for_display target_network_info.eligible_for_display
match_rate_percentage ingested_user_list_info.contact_id_info.match_rate_percentage
basic_user_list ingested_user_list_info.pseudonymous_id_info 不用于目标客户匹配。
crm_based_user_list ingested_user_list_info 必需。请参阅目标客户匹配受众群体信息。
无对等项。 ingested_user_list_info.pair_id_info 不用于目标客户匹配。
无对等项。 ingested_user_list_info.partner_audience_info 不用于目标客户匹配。
logical_user_list 无对等项。 不用于目标客户匹配。
logical_user_list 无对等项。 不用于目标客户匹配。
lookalike_user_list 无对等项。 不用于目标客户匹配。
rule_based_user_list 无对等项。 不用于目标客户匹配。
similar_user_list 无对等项。 不用于目标客户匹配。

目标客户匹配受众群体信息

在 Google Ads API 中，创建目标客户匹配受众群体时，crm_based_user_list 字段是必需的。

在 Data Manager API 中，通过将 ingested_user_list_info 字段设置为 IngestedUserListInfo 来设置等效属性，然后设置目标客户匹配所需的字段和用户数据类型。

联系信息

upload_key_types
设置为包含 CONTACT_INFO 的列表。
contact_id_info

设置为 ContactIdInfo。

将 data_source_type 设置为 DATA_SOURCE_TYPE_FIRST_PARTY。

移动 ID

upload_key_types
设置为包含 MOBILE_ID 的列表。
mobile_id_info

设置为 MobileIdInfo。

  • 将 data_source_type 设置为 DATA_SOURCE_TYPE_FIRST_PARTY。
  • 将 key_space 设置为 IOS 或 ANDROID。
  • 将 app_id 设置为唯一标识收集数据所用的移动应用的字符串。使用与 Google Ads API 中的应用 ID 相同的格式。

用户 ID

upload_key_types
设置为包含 USER_ID 的列表。
user_id_info

设置为 UserIdInfo。

将 data_source_type 设置为 DATA_SOURCE_TYPE_FIRST_PARTY。

资源名称

数据管理器 API 使用的资源名称格式与 Google Ads API 不同。

Google Ads API

在 Google Ads API 中，UserList 资源名称采用以下格式：

customers/{customer_id}/userLists/{user_list_id}

Data Manager API

在 Data Manager API 中，UserList 资源名称采用以下格式：

accountTypes/{accountType}/accounts/{account}/userLists/{userList}

上传字段映射

使用表格中的映射，将 Google Ads API 中的 AddOfflineUserDataJobOperationsRequest 映射到数据管理器 API 中对应的 IngestAudienceMembersRequest。

请求字段

AddOfflineUserDataJobOperationsRequest (Google Ads API) IngestAudienceMembersRequest (Data Manager API) 备注
  • customer_id 字段
  • OfflineUserDataJob 的 customer_match_user_list_metadata 字段
  • developer-token 请求标头
  • login-customer_id 请求标头
  • linked-customer-id 请求标头
 destinations 请参阅客户和受众群体字段。
consent来自 customer_match_user_list_metadata 的OfflineUserDataJob consent 请求中受众群体的可选默认用户意见征求设置。您可以为单个受众群体成员替换此值，只需设置 AudienceMember 的 consent 字段即可。
无对应报告 encoding 必需：设置为用于 UserIdentifier 值的 Encoding。
无对应报告 encryption_info 设置请求是否包含加密值。如需了解详情，请参阅加密。
job_id 无对应报告 使用响应中返回的 request_id 来检索诊断信息。
enable_partial_failure 无对应报告 Data Manager API 不支持部分失败。如果 IngestAudienceMembersRequest 的任何字段未能通过验证，Data Manager API 会拒绝整个请求。使用诊断检索处理错误。
enable_warnings 无对应报告 Data Manager API 不会在响应中报告警告。使用 diagnostics 检索处理警告。
validate_only validate_only
operations audience_members 观众成员列表。如需了解详情，请参阅“受众群体成员”字段部分。
无对应报告 terms_of_service 必需。设置为指示用户已接受或拒绝目标客户匹配服务条款。

客户和受众群体字段

Google Ads API 仅支持将受众群体成员上传到每个作业的一个受众群体。此外，您需要提供 developer-token 请求标头，并针对不同的身份验证场景设置 login-customer-id 和 linked-customer-id 请求标头。

Data Manager API 支持在单个请求中发送多个受众群体的受众群体成员。Data Manager API 不需要开发者令牌，您可以使用 Destination 的字段（而不是请求标头）指定登录信息和关联的客户信息。如需详细了解目的地，请参阅配置目的地。

Data Manager API 不支持移除受众群体的所有成员。在 Google Ads API 中，您可以通过将 OfflineUserDataJobOperation 的 remove_all 字段设置为 true 来移除受众群体的所有成员。

下面展示了如何将单个受众群体的 Google Ads API 字段映射到 Destination 中的等效字段：

Google Ads API Destination (Data Manager API) 备注
请求的 customer_id operating_account 将 account_id 设置为受众群体的客户 ID。将 operating_account 的 account_type 设置为 GOOGLE_ADS。
developer-token 请求标头 无对应报告 数据管理器 API 不需要开发者令牌。
login-customer-id 请求标头 login_account 将 account_id 设置为登录账号的客户 ID。如果登录账号是 Google Ads 账号，请将 account_type 设置为 GOOGLE_ADS；如果登录账号是数据合作伙伴账号，请将 account_type 设置为 DATA_PARTNER。
linked-customer-id 请求标头 linked_account 将 account_id 设置为关联账号的客户 ID。将 account_type 设为 DATA_PARTNER。
user_list，来自 OfflineUserDataJob 的 customer_match_user_list_metadata product_destination_id 必需。设置为相应受众群体的数字 ID。请勿使用 UserList 的资源名称。
无对应报告 reference Destination 的用户定义标识符。如果您在单个请求中为多个受众群体发送受众群体成员，请设置此字段。

受众群体成员字段

UserData (Google Ads API) AudienceMember (Data Manager API) 备注
consent consent

设置为指定观众成员的同意情况。

这两个 API 都使用类似的 Consent 对象（ad_user_data、ad_personalization）。

对于 Data Manager API，您还可以通过设置请求级 consent 字段，为请求中的所有受众群体成员设置意见征求。
transaction_attribute 无对等项。 不适用于目标客户匹配。
user_attribute 无对等项。 不适用于目标客户匹配。
user_identifiers
  • mobile_id_data
  • user_id_data
  • user_identifiers

填充与您为受众群体成员发送的数据类型对应的字段。如需了解详情，请参阅用户标识符字段。

用户标识符字段

在 Google Ads API 中，无论您发送的是联系信息、移动设备 ID 还是用户 ID，都使用 UserIdentifier。Data Manager API 采用不同的方法，为每种类型的数据使用不同的字段。

在 Data Manager API 中，填充与您要发送的数据类型对应的字段：

联系信息

如果使用电子邮件地址、电话号码或地址信息等联系信息，请将 user_data 设置为 UserData，并在 user_identifiers 中为每项联系信息分别添加一个条目。

UserIdentifier (Google Ads API) UserIdentifier （数据管理器 API） 备注
address_info address 如需了解详情，请参阅地址字段。
hashed_email email_address 设置为已格式化和哈希处理的电子邮件地址。您还可以加密哈希处理后的电子邮件地址。
hashed_phone_number phone_number 设置为已格式化和哈希处理的电话号码。您还可以对哈希处理后的电话号码进行加密。
user_identifier_source 无对等项。

地址字段

下表列出了 Google Ads API 中的 OfflineUserAddressInfo 与数据管理器 API 中的 AddressInfo 之间的字段映射。如果您使用联系信息来填充目标客户匹配受众群体，请使用这些映射。

OfflineUserAddressInfo (Google Ads API) AddressInfo （数据管理器 API） 备注
city 无对等项。
country_code region_code
hashed_first_name given_name

设置为格式化和哈希处理的给定名称。您还可以加密哈希处理后的指定名称。
hashed_last_name family_name

设置为已格式化和哈希处理的系列名称。您还可以对哈希处理后的家人姓名进行加密。
hashed_street_address 无对等项。
postal_code postal_code
state 无对等项。

移动 ID

如果使用移动 ID，请将 mobile_data 设置为 MobileData，并在 mobile_ids 中为每个 ID 添加一个条目。

UserIdentifier (Google Ads API) MobileData （数据管理器 API） 备注
mobile_id mobile_ids 设置为受众群体成员的移动 ID 列表。

在 Google Ads API 中，您需要为每位受众群体成员的每个移动设备 ID 添加一个包含 mobile_id 的单独的 UserIdentifier。在 Data Manager API 中，添加一个 MobileData，其中 mobile_ids 设置为受众群体成员的所有移动 ID 的列表。

user_identifier_source 无对等项。

用户 ID

如果使用用户 ID，请将 user_id_data 设置为 UserIdData，并将 user_id 设置为受众群组成员的用户 ID。

UserIdentifier (Google Ads API) UserIdData （数据管理器 API） 备注
third_party_user_id user_id

在 Google Ads API 中，您需要为受众群体成员的每个用户 ID 添加一个具有 third_party_user_id 的单独 UserIdentifier。

在 Data Manager API 中，将 user_id_data 字段设置为 UserIdData，并将其 user_id 字段设置为相应受众群成员的用户 ID。您无法为同一位受众群体成员发送多个用户 ID。

user_identifier_source 无对等项。
上一页
升级步骤