字段映射

使用表格中的映射，将 Google Ads API 方法和字段映射到 其 IngestEventsRequest 在 Data Manager API 中的等效项。

身份验证

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 请求的字段如何映射到 Data Manager 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
 诊断 使用 request_id 中返回的 IngestEventsResponse 检索有关转化上传的 诊断信息。
job.id request_id 使用 request_id 中返回的 IngestEventsResponse 检索有关转化上传的 诊断信息。
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 无对应字段 使用 诊断功能 检索有关 Data Manager API 请求的警告。您无需启用此功能。
operations events The 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 请求标头 无对应字段 Data Manager API 不需要开发者令牌。
login-customer-id 请求标头 login_account 将 account_id 设置为登录账号的客户 ID。如果登录账号是 Google Ads 账号，请将 account_type 设置为 GOOGLE_ADS；如果登录账号是数据合作伙伴账号，请将 设置为 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 无对应字段 Google Ads 目标不支持。
address_info.state 无对应字段 Google Ads 目标不支持。
address_info.hashed_street_address 无对应字段 Google Ads 目标不支持。
上一页
升级步骤