欄位對應

使用表格中的對應項目，將 Google Ads API 方法和欄位對應至 Data Manager 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 要求的欄位如何對應至 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
 診斷 使用 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 使用者 ID。詳情請參閱「加密」一文。

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 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 使用者 ID。詳情請參閱「加密」一文。

客戶和轉換動作欄位

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 相同，但表示使用者 ID 來自第三方來源，而非第一方廣告主資料。

只有在登入帳戶是資料合作夥伴 (login_account.account_type 為 DATA_PARTNER) 的情況下，才能填入 third_party_user_data。

詳情請參閱「使用者 ID 欄位」。

consent consent 這兩個 API 都使用類似的 Consent 物件 (ad_user_data、ad_personalization)。對於 Data Manager API，您也可以在 IngestEventsRequest 上設定 consent 欄位，為要求中的所有事件設定同意聲明。

使用者 ID 欄位

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 相同，但表示使用者 ID 來自第三方來源，而非第一方廣告主資料。

只有在登入帳戶是資料合作夥伴 (login_account.account_type 為 DATA_PARTNER) 的情況下，才能填入 third_party_user_data。

詳情請參閱「使用者 ID 欄位」。

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 無對應報告 目前版本的 Data Manager API 不支援這項功能。
address_info.state 無對應報告 目前版本的 Data Manager API 不支援這項功能。
address_info.hashed_street_address 無對應報告 目前版本的 Data Manager API 不支援這項功能。
上一頁
升級步驟