字段映射

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

身份验证

Data Manager API 需要的凭据范围与 Google Ads API 不同。按照设置 API 访问权限中的步骤生成包含 Data Manager API 范围的新凭据。

受众群体管理字段映射

使用表格中的映射关系，将 Google Ads API 中的 UserList 映射到 Data Manager 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 字段设置为 CrmBasedUserListInfo。

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

联系信息

upload_key_types
设置为包含 CONTACT_ID 的列表。这相当于在 Google Ads API 中将 upload_key_type 设置为 CONTACT_INFO。
contact_id_info

设置为 ContactIdInfo。

将 data_source_type 设置为 DATA_SOURCE_TYPE_FIRST_PARTY。这相当于在 Google Ads API 中将 data_source_type 设置为 FIRST_PARTY。

移动 ID

upload_key_types
设置为包含 MOBILE_ID 的列表。这相当于在 Google Ads API 中将 upload_key_type 设置为 MOBILE_ADVERTISING_ID。
mobile_id_info

设置为 MobileIdInfo。

  • 将 data_source_type 设置为 DATA_SOURCE_TYPE_FIRST_PARTY。这相当于在 Google Ads API 中将 data_source_type 设置为 FIRST_PARTY。
  • 将 key_space 设置为 IOS 或 ANDROID。Data Manager API 需要此值。这与 Google Ads API 不同，在 Google Ads API 中，密钥空间是从 app_id 推断出来的。
  • 将 app_id 设置为唯一标识收集数据所用的移动应用的字符串。使用与 Google Ads API 中 app_id 相同的格式。

用户 ID

upload_key_types
设置为包含 USER_ID 的列表。这相当于在 Google Ads API 中将 upload_key_type 设置为 CRM_ID。
user_id_info

设置为 UserIdInfo。

将 data_source_type 设置为 DATA_SOURCE_TYPE_FIRST_PARTY。这相当于在 Google Ads API 中将 data_source_type 设置为 FIRST_PARTY。

资源名称

Data Manager 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 映射到 Data Manager 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 如果您是通过合作伙伴链接访问 operating_account，请将 account_id 设置为关联账号的客户 ID，并将 account_type 设置为 DATA_PARTNER。否则，请勿设置 linked_account 字段。
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_data
  • user_id_data
  • composite_data
    • user_data
    • ip_data

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

用户标识符字段

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

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

联系信息

如果使用电子邮件地址、电话号码或地址信息等联系信息，请将 composite_data 设置为 CompositeData，并在 user_data.user_identifiers 中为每个联系信息项设置单独的条目。

虽然我们仍支持 user_data，但建议您使用 composite_data，以确保您的集成已为未来的改进做好准备。如需了解详情，请参阅复合数据。

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

地址字段

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

OfflineUserAddressInfo (Google Ads API) AddressInfo （Data Manager API） 备注
city 无对等项。
country_code region_code 必需
hashed_first_name given_name

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

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

IP 地址

除了用户标识符之外，Data Manager API 还支持在目标客户匹配上传中包含 IP 地址。这些功能在 CompositeData 中提供，该软件包捆绑了 UserData 和 IpData。同时提供这些字段有助于提高匹配率。

如需了解详情，请参阅 目标客户匹配的 IP 提取。

Google Ads API CompositeData （Data Manager API） 备注
无对等项。 ip_data.ip_address 设置为原始 IPv4 或 IPv6 地址。请参阅 IP 地址格式指南。
无对等项。 ip_data.observe_start_time 设置为首次观测到相应 IP 地址的时间戳（采用 RFC 3339 格式）。
无对等项。 ip_data.observe_end_time 设置为上次观测到相应 IP 地址的时间戳（采用 RFC 3339 格式）。
user_identifiers user_data 设置为 UserData 对象。

移动 ID

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

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

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

user_identifier_source 无对等项。

用户 ID

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

UserIdentifier (Google Ads API) UserIdData （Data Manager 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 无对等项。
上一页
升级步骤