欄位對應

請使用表格中的對應關係，將 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 要求標頭 無對應報告 使用 Data Manager 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 無對應報告 不支援 Google Ads 目的地。
address_info.state 無對應報告 不支援 Google Ads 目的地。
address_info.hashed_street_address 無對應報告 不支援 Google Ads 目的地。
上一頁
升級步驟