字段映射

使用表格中的映射，将 Google Ads API 方法和字段映射到数据管理器 API 中对应的 IngestEventsRequest。

身份验证

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

API 方法

借助 Data Manager API，您可以在单个 IngestEventsRequest 中上传每批实体店销售事件。

相比之下，Google Ads API 需要使用 OfflineUserDataJobService 执行三步流程：

  1. 使用 CreateOfflineUserDataJob 创建作业
  2. 使用 AddOfflineUserDataJobOperations 将操作添加到作业
  3. 使用 RunOfflineUserDataJob 运行作业

请求字段

每个 IngestEventsRequest 都受请求限制的约束。如果 AddOfflineUserDataJobOperations 请求中的操作数超过这些限制，您必须将其拆分为多个 Data Manager API 提取请求。

以下是 Google Ads API 请求的字段与数据管理器 API 的对应关系。

CreateOfflineUserDataJobRequest

下表显示了 CreateOfflineUserDataJobRequest 的字段与 IngestEventsRequest 的映射关系。

CreateOfflineUserDataJobRequest (Google Ads API) IngestEventsRequest（Data Manager API） 备注
customer_id destinations.operating_account 请参阅客户和转化操作字段。
  • developer-token 请求标头
  • login-customer_id 请求标头
  • linked-customer-id 请求标头
 destinations 请参阅客户和转化操作字段。
  • job.status
  • job.failure_reason
 诊断 使用 IngestEventsResponse 中返回的 request_id 来检索有关转化上传的诊断信息。
job.id request_id 使用 IngestEventsResponse 中返回的 request_id 来检索有关转化上传的诊断信息。
job.external_id 无对应报告
job.type 无对应报告
job.store_sales_metadata.third_party_metadata.partner_id destinations.login_account 上传实体店销售转化数据的数据合作伙伴将通过目标平台的 login_account 进行标识。如需了解详情，请参阅配置目的地。
job.store_sales_metadata.third_party_metadata.advertiser_upload_date_time 无对应报告
job.store_sales_metadata.third_party_metadata.valid_transaction_fraction 无对应报告
job.store_sales_metadata.third_party_metadata.partner_match_fraction 无对应报告
job.store_sales_metadata.third_party_metadata.partner_upload_fraction 无对应报告
job.store_sales_metadata.third_party_metadata.bridge_map_version_id 无对应报告
job.store_sales_metadata.loyalty_fraction 无对应报告
job.store_sales_metadata.transaction_upload_fraction 无对应报告
job.store_sales_metadata.custom_key
  • events[].custom_variables[].variable
  • events[].cart_data.items[].custom_variables[].variable
 在事件级映射到 CustomVariable 的 variable 字段，或在商品级映射到 ItemCustomVariable。
enable_match_rate_range_preview 无对应报告
validate_only validate_only
无对应报告 consent Google Ads API 仅支持在 UserData 中指定事件级 consent。对于 Data Manager API，您可以通过在 IngestEventsRequest 上设置 consent 字段，为请求中的所有事件指定意见征求情况。您可以通过设置 Event 的 consent 字段来替换单个事件的此值。
无对应报告 encoding 上传 UserData 时必需。设置为用于 UserIdentifier 值的 Encoding。
无对应报告 encryption_info 如果请求包含加密的 UserData 用户标识符，则进行设置。如需了解详情，请参阅加密。

AddOfflineUserDataJobOperationsRequest

下表显示了 AddOfflineUserDataJobOperationsRequest 的字段与 IngestEventsRequest 的映射关系。

AddOfflineUserDataJobOperationsRequest (Google Ads API) IngestEventsRequest（Data Manager API） 备注
  • developer-token 请求标头
  • login-customer_id 请求标头
  • linked-customer-id 请求标头
 destinations 请参阅客户和转化操作字段。
resource_name 无对应报告 Data Manager API 不需要更新作业资源。
enable_partial_failure 无对应报告 如果 IngestEventsRequest 成功，则下游处理期间发生的任何失败都会在事件级别进行处理，这可能会导致部分成功。使用诊断功能可检索上传状态以及各个事件的错误和警告。如果 IngestEventsRequest 失败（例如，由于 BadRequest），则不会处理任何事件，您需要解决该错误并重试请求。如需了解详情，请参阅了解 API 错误。
enable_warnings 无对应报告 使用 Diagnostics 检索有关 Data Manager API 请求的警告。您无需启用此功能。
operations events OfflineUserDataJobOperation.create 操作等效于发送 IngestEventsRequest。Data Manager API 不支持移除事件。
validate_only validate_only
无对应报告 consent Google Ads API 仅支持在 UserData 中指定事件级 consent。对于 Data Manager API，您可以通过在 IngestEventsRequest 上设置 consent 字段，为请求中的所有事件指定意见征求情况。您可以通过设置 Event 的 consent 字段来替换单个事件的此值。
无对应报告 encoding 上传 UserData 时必需。设置为用于 UserIdentifier 值的 Encoding。
无对应报告 encryption_info 如果请求包含加密的 UserData 用户标识符，则进行设置。如需了解详情，请参阅加密。

客户和转化操作字段

Google Ads API 需要 developer-token 请求标头，您可以根据不同的身份验证场景设置 login-customer-id 和 linked-customer-id 请求标头。

Data Manager API 不需要开发者令牌，您可以使用 Destination 的字段指定登录信息和关联的客户信息，而不是使用请求标头。如需详细了解目的地，请参阅配置目的地。

Google Ads API Destination（Data Manager API） 备注
请求的 customer_id operating_account 将 account_id 设置为 Google Ads 转化账号的客户 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 字段。
conversion_action product_destination_id 设置为转化操作的数字 ID。请勿使用资源名称。

事件字段

下表显示了实体店销售转化在两个 API 之间的字段映射方式。

与 Google Ads API（仅支持使用 ItemAttribute 在每笔交易中添加单个商品）不同，Data Manager API 支持在 CartData 中为每个事件添加多个商品。

OfflineUserDataJobOperation.create (Google Ads API) Event（Data Manager API） 备注
无对应报告 event_source 必需。对于实体店销售转化，请设置为 IN_STORE。
transaction_attribute.conversion_action destinations.product_destination_id 请参阅客户和转化操作字段。请使用转化操作的数字 ID，而不是资源名称。
transaction_attribute.transaction_date_time event_timestamp
如需了解详情，请参阅时间戳格式。
transaction_attribute.transaction_amount_micros
  • conversion_value （必需）
  • cart_data.items[].conversion_value
 设置为币种值，而不是以微为单位的值。例如，对于 5.23 美元的转化价值，请使用值 5.23。
transaction_attribute.currency_code currency 必填。
transaction_attribute.order_id transaction_id 必填。
transaction_attribute.store_attribute.store_code event_location.store_id 必需：在 EventLocation 对象的 store_id 字段中设置实体店代码。
transaction_attribute.custom_value
  • custom_variables[].value
  • cart_data.items[].custom_variables[].value
 在事件级映射到 CustomVariable 的 value 字段，或在商品级映射到 ItemCustomVariable。
transaction_attribute.item_attribute.item_id cart_data.items[].merchant_product_id
transaction_attribute.item_attribute.merchant_id
  • cart_data.merchant_id
  • cart_data.items[].merchant_id
 如果您设置了 cart_data.merchant_id，它将作为所有商品的默认值，但您可以针对个别商品替换该值。
transaction_attribute.item_attribute.country_code
  • cart_data.merchant_feed_label
  • cart_data.items[].merchant_feed_label
 如果您设置了 cart_data.merchant_feed_label，它将作为所有商品的默认值，但您可以针对个别商品替换该值。
transaction_attribute.item_attribute.language_code
  • cart_data.merchant_feed_language_code
  • cart_data.items[].merchant_feed_language_code
 如果您设置了 cart_data.merchant_feed_language_code，它将作为所有商品的默认值，但您可以针对个别商品替换该值。
transaction_attribute.item_attribute.quantity cart_data.items[].quantity
无对应报告 cart_data.items[].unit_price 设置为相应商品的单价（不含税、运费和事件级 [交易级] 折扣）。
user_identifiers
  • user_data.user_identifiers
  • third_party_user_data.user_identifiers
 必需。

third_party_user_data 使用与 user_data 相同的结构，但表示用户标识符来自第三方来源，而不是第一方广告客户数据。

只有当登录账号是数据合作伙伴（login_account.account_type 为 DATA_PARTNER）时，才允许填充 third_party_user_data。

如需了解详情，请参阅用户标识符字段。

consent consent 这两个 API 都使用类似的 Consent 对象（ad_user_data、ad_personalization）。对于 Data Manager API，您还可以通过在 IngestEventsRequest 上设置 consent 字段，为请求中的所有事件设置意见征求。

用户标识符字段

UserIdentifier (Google Ads API) UserIdentifier（Data Manager API） 备注
user_identifier_source

来源决定了要在 Data Manager API Event 上填充哪个字段：

  • user_data
  • third_party_user_data

third_party_user_data 使用与 user_data 相同的结构，但表示用户标识符来自第三方来源，而不是第一方广告客户数据。

只有当登录账号是数据合作伙伴（login_account.account_type 为 DATA_PARTNER）时，才允许填充 third_party_user_data。

如需了解详情，请参阅用户标识符字段。

hashed_email email_address 设置为经过格式化和哈希处理的电子邮件地址。您还可以加密哈希处理后的电子邮件地址。
hashed_phone_number phone_number 设置为已格式化和哈希处理的电话号码。您还可以对哈希处理后的电话号码进行加密。
address_info address 设置为 AddressInfo 对象。遵循格式设置和哈希处理指南。您还可以加密地址的哈希属性。
address_info.hashed_first_name address.given_name
address_info.hashed_last_name address.family_name
address_info.country_code address.region_code
address_info.postal_code address.postal_code
address_info.city 无对应报告 当前版本的数据管理器 API 不支持此功能。
address_info.state 无对应报告 当前版本的数据管理器 API 不支持此功能。
address_info.hashed_street_address 无对应报告 当前版本的数据管理器 API 不支持此功能。
上一页
升级步骤