欄位對應

使用欄位對應，將目標顧客比對工作流程的每個步驟從 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 (Data Manager 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

目標對象成員加入名單後，在名單中保留的時間長度。值必須對應整天。如未設定，預設值為上限。

使用時間戳記格式設定值的格式。
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 不同，後者會從 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 欄位
  • customer_match_user_list_metadata 欄位，OfflineUserDataJob
  • 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 不會在回應中回報警告。使用診斷功能擷取處理警告。
validate_only validate_only
operations audience_members 目標對象成員清單。詳情請參閱「目標對象成員欄位」一節。
無對應報告 terms_of_service 必要。設定為指出使用者已接受或拒絕接受目標顧客比對的服務條款。

顧客和目標對象欄位

Google Ads API 僅支援在每個工作中，將目標對象成員上傳至一個目標對象。此外，您必須設定 developer-token 要求標頭，並針對不同驗證情境設定 login-customer-id 和 linked-customer-id 要求標頭。

資料管理工具 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 customer_match_user_list_metadataOfflineUserDataJob product_destination_id 必要。設定為目標對象的數字 ID。請勿使用 UserList 的資源名稱。
無對應報告 reference Destination 的使用者定義 ID。如果您在單一要求中傳送多個目標對象的目標對象成員，請設定這個欄位。

目標對象成員欄位

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

填入與您要傳送的目標對象成員資料類型相應的欄位。詳情請參閱使用者 ID 欄位。

使用者 ID 欄位

在 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 位址

除了使用者 ID 之外，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 新增個別 UserIdentifier，並使用 mobile_id。在 Data Manager API 中，新增單一 MobileData，並將 mobile_ids 設為目標對象成員的所有行動 ID 清單。
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 新增個別 UserIdentifier，並使用 third_party_user_id 。

在 Data Manager API 中，將 user_id_data 欄位設為 UserIdData，並將 user_id 欄位設為目標對象成員的使用者 ID。您無法為同一位目標對象成員傳送多個使用者 ID。

user_identifier_source 沒有效果相當的功能。
上一頁
升級步驟