欄位對應

使用欄位對應，將目標顧客比對工作流程的每個步驟從 Google Ads 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_metadata OfflineUserDataJob) 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 沒有效果相當的功能。
上一頁
升級步驟