Ánh xạ trường

Sử dụng các mối liên kết trường để nâng cấp từng bước trong quy trình So khớp khách hàng từ API Google Ads lên Data Manager API:

Liên kết trường quản lý đối tượng

Sử dụng các mối liên kết trong bảng để liên kết một UserList trong API Google Ads với UserList tương đương trong Data Manager API.

UserList (API Google Ads) UserList (Data Manager API) Ghi chú
resource_name name Hãy xem phần Tên tài nguyên để biết thông tin chi tiết.
id id
read_only read_only
name display_name Bắt buộc
description description Bắt buộc
membership_status membership_status
integration_code integration_code
membership_life_span membership_duration

Khoảng thời gian mà một thành viên đối tượng vẫn nằm trong danh sách sau khi được thêm. Giá trị này phải tương ứng với số ngày. Nếu không được đặt, giá trị này sẽ mặc định là giá trị tối đa.

Định dạng giá trị bằng định dạng Dấu thời gian.
size_for_display size_info.display_network_members_count
size_range_for_display Không có thành phần tương đương. Sử dụng size_info.display_network_members_count cho thông tin về kích thước.
size_for_search size_info.search_network_members_count
size_range_for_search Không có thành phần tương đương. Sử dụng size_info.search_network_members_count cho thông tin về kích thước.
type Không có thành phần tương đương.
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 Không được dùng cho tính năng So khớp khách hàng.
crm_based_user_list ingested_user_list_info Bắt buộc. Xem thông tin về đối tượng So khớp khách hàng.
Không có thành phần tương đương. ingested_user_list_info.pair_id_info Không được dùng cho tính năng So khớp khách hàng.
Không có thành phần tương đương. ingested_user_list_info.partner_audience_info Không được dùng cho tính năng So khớp khách hàng.
logical_user_list Không có thành phần tương đương. Không được dùng cho tính năng So khớp khách hàng.
logical_user_list Không có thành phần tương đương. Không được dùng cho tính năng So khớp khách hàng.
lookalike_user_list Không có thành phần tương đương. Không được dùng cho tính năng So khớp khách hàng.
rule_based_user_list Không có thành phần tương đương. Không được dùng cho tính năng So khớp khách hàng.
similar_user_list Không có thành phần tương đương. Không được dùng cho tính năng So khớp khách hàng.

Thông tin về đối tượng đối sánh khách hàng

Trong Google Ads API, bạn phải điền trường crm_based_user_list khi tạo đối tượng So khớp khách hàng.

Trong Data Manager API, hãy đặt các thuộc tính tương đương bằng cách đặt trường ingested_user_list_info thành IngestedUserListInfo, sau đó đặt các trường bắt buộc cho tính năng So khớp khách hàng và loại dữ liệu người dùng.

Thông tin liên hệ

upload_key_types
Đặt thành một danh sách chứa CONTACT_INFO.
contact_id_info

Đặt thành ContactIdInfo.

Đặt data_source_type thành DATA_SOURCE_TYPE_FIRST_PARTY.

Mã nhận dạng trên thiết bị di động

upload_key_types
Đặt thành một danh sách chứa MOBILE_ID.
mobile_id_info

Đặt thành MobileIdInfo.

  • Đặt data_source_type thành DATA_SOURCE_TYPE_FIRST_PARTY.
  • Đặt key_space thành IOS hoặc ANDROID.
  • Đặt app_id thành chuỗi nhận dạng riêng biệt ứng dụng di động mà dữ liệu được thu thập. Sử dụng cùng định dạng mà bạn dùng cho mã ứng dụng trong API Google Ads.

Mã nhận dạng người dùng

upload_key_types
Đặt thành một danh sách chứa USER_ID.
user_id_info

Đặt thành UserIdInfo.

Đặt data_source_type thành DATA_SOURCE_TYPE_FIRST_PARTY.

Tên tài nguyên

Data Manager API sử dụng một định dạng tên tài nguyên khác với Google Ads API.

API Google Ads

Trong API Google Ads, tên tài nguyên UserList sử dụng định dạng:

customers/{customer_id}/userLists/{user_list_id}

Data Manager API

Trong Data Manager API, tên tài nguyên UserList sử dụng định dạng:

accountTypes/{accountType}/accounts/{account}/userLists/{userList}

Tải mối liên kết trường lên

Sử dụng các mối liên kết trong bảng để liên kết một AddOfflineUserDataJobOperationsRequest trong Google Ads API với IngestAudienceMembersRequest tương đương trong Data Manager API.

Trường yêu cầu

AddOfflineUserDataJobOperationsRequest (Google Ads API) IngestAudienceMembersRequest (Data Manager API) Ghi chú
  • customer_id trường
  • customer_match_user_list_metadata trường của OfflineUserDataJob
  • Tiêu đề của yêu cầu developer-token
  • Tiêu đề của yêu cầu login-customer_id
  • Tiêu đề của yêu cầu linked-customer-id
 destinations Xem Trường khách hàng và đối tượng.
consent từ customer_match_user_list_metadata của OfflineUserDataJob consent Chế độ cài đặt mặc định không bắt buộc về sự đồng ý cho các thành viên trong đối tượng trong yêu cầu. Bạn có thể ghi đè giá trị này cho từng thành viên đối tượng bằng cách đặt trường consent của AudienceMember.
Không có phiên bản mới encoding Bắt buộc: Đặt thành Encoding được dùng cho các giá trị UserIdentifier.
Không có phiên bản mới encryption_info Đặt nếu yêu cầu chứa các giá trị được mã hoá. Hãy xem phần Mã hoá để biết thông tin chi tiết.
job_id Không có phiên bản mới Sử dụng request_id được trả về trong phản hồi để truy xuất thông tin chẩn đoán.
enable_partial_failure Không có phiên bản mới API Trình quản lý dữ liệu không hỗ trợ lỗi một phần. Nếu bất kỳ trường nào của IngestAudienceMembersRequest không xác thực được, thì Data Manager API sẽ từ chối toàn bộ yêu cầu. Truy xuất lỗi xử lý bằng thông tin chẩn đoán.
enable_warnings Không có phiên bản mới Data Manager API không báo cáo cảnh báo trong phản hồi. Truy xuất cảnh báo xử lý bằng cách sử dụng chẩn đoán.
validate_only validate_only
operations audience_members Danh sách thành viên trong đối tượng. Hãy xem mục Trường thành viên đối tượng để biết thông tin chi tiết.
Không có phiên bản mới terms_of_service Bắt buộc. Đặt để cho biết rằng người dùng đã chấp nhận hoặc từ chối điều khoản dịch vụ cho tính năng So khớp khách hàng.

Trường khách hàng và đối tượng

Google Ads API chỉ hỗ trợ tải thành viên đối tượng lên một đối tượng cho mỗi công việc.Ngoài ra, bạn phải có tiêu đề yêu cầu developer-token và bạn đặt login-customer-id và linked-customer-id tiêu đề yêu cầu cho các trường hợp xác thực khác nhau.

Data Manager API hỗ trợ gửi thành viên đối tượng cho nhiều đối tượng trong một yêu cầu. Data Manager API không yêu cầu mã của nhà phát triển và bạn chỉ định thông tin đăng nhập cũng như thông tin khách hàng được liên kết bằng cách sử dụng các trường của Destination thay vì tiêu đề yêu cầu. Hãy xem phần Định cấu hình vị trí xuất hiện để biết thêm thông tin về vị trí xuất hiện.

Data Manager API không hỗ trợ việc xoá tất cả thành viên của một đối tượng. Trong Google Ads API, bạn có thể xoá tất cả thành viên của một đối tượng bằng cách đặt trường remove_all của OfflineUserDataJobOperation thành true.

Sau đây là cách liên kết các trường API Google Ads cho một đối tượng duy nhất với các trường tương đương trong Destination:

API Google Ads Destination (Data Manager API) Ghi chú
customer_id của yêu cầu operating_account Đặt account_id thành mã nhận dạng khách hàng của đối tượng. Đặt account_type của operating_account thành GOOGLE_ADS.
Tiêu đề của yêu cầu developer-token Không có phiên bản mới Bạn không cần mã của nhà phát triển cho Data Manager API.
Tiêu đề của yêu cầu login-customer-id login_account Đặt account_id thành mã khách hàng của tài khoản đăng nhập. Đặt account_type thành GOOGLE_ADS nếu tài khoản đăng nhập là tài khoản Google Ads hoặc DATA_PARTNER nếu tài khoản đăng nhập là tài khoản đối tác dữ liệu.
Tiêu đề của yêu cầu linked-customer-id linked_account Đặt account_id thành mã khách hàng của tài khoản được liên kết. Đặt account_type thành DATA_PARTNER.
user_list từ customer_match_user_list_metadata của OfflineUserDataJob product_destination_id Bắt buộc. Đặt thành mã nhận dạng dạng số của đối tượng. Đừng sử dụng tên tài nguyên của UserList.
Không có phiên bản mới reference Giá trị nhận dạng do người dùng xác định cho Destination. Đặt trường này nếu bạn gửi thành viên đối tượng cho nhiều đối tượng trong một yêu cầu.

Các trường thành viên đối tượng

UserData (Google Ads API) AudienceMember (Data Manager API) Ghi chú
consent consent

Đặt để chỉ định sự đồng ý cho thành viên trong đối tượng.

Cả hai API đều sử dụng một đối tượng Consent tương tự (ad_user_data, ad_personalization).

Đối với Data Manager API, bạn cũng có thể đặt sự đồng ý cho tất cả thành viên đối tượng trong một yêu cầu bằng cách đặt trường consent ở cấp yêu cầu.
transaction_attribute Không có thành phần tương đương. Không áp dụng cho tính năng So khớp khách hàng.
user_attribute Không có thành phần tương đương. Không áp dụng cho tính năng So khớp khách hàng.
user_identifiers
  • mobile_id_data
  • user_id_data
  • user_identifiers

Điền thông tin vào trường tương ứng với loại dữ liệu mà bạn đang gửi cho các thành viên trong đối tượng. Hãy xem phần Trường giá trị nhận dạng người dùng để biết thông tin chi tiết.

Trường giá trị nhận dạng người dùng

Trong API Google Ads, cho dù bạn đang gửi thông tin liên hệ, mã nhận dạng thiết bị di động hay mã nhận dạng người dùng, bạn đều sử dụng UserIdentifier. Data Manager API sử dụng một phương pháp khác, với các trường khác nhau cho từng loại dữ liệu.

Trong Data Manager API, hãy điền sẵn trường tương ứng với loại dữ liệu mà bạn đang gửi:

Thông tin liên hệ

Nếu sử dụng thông tin liên hệ như địa chỉ email, số điện thoại hoặc thông tin địa chỉ, hãy đặt user_data thành UserData với một mục riêng trong user_identifiers cho từng mục thông tin liên hệ.

UserIdentifier (Google Ads API) UserIdentifier (Data Manager API) Ghi chú
address_info address Hãy xem Các trường địa chỉ để biết thông tin chi tiết.
hashed_email email_address Đặt thành địa chỉ email đã định dạng và băm. Bạn cũng có thể mã hoá địa chỉ email đã băm.
hashed_phone_number phone_number Đặt thành số điện thoại đã định dạng và băm. Bạn cũng có thể mã hoá số điện thoại đã băm.
user_identifier_source Không có thành phần tương đương.

Trường địa chỉ

Sau đây là các mối liên kết trường giữa OfflineUserAddressInfo trong API Google Ads và AddressInfo trong API Trình quản lý dữ liệu. Hãy sử dụng các mối liên kết này nếu bạn đang dùng thông tin liên hệ để điền sẵn đối tượng So khớp khách hàng.

OfflineUserAddressInfo (Google Ads API) AddressInfo (Data Manager API) Ghi chú
city Không có thành phần tương đương.
country_code region_code
hashed_first_name given_name

Đặt thành tên được cho định dạng và băm. Bạn cũng có thể mã hoá tên đã cho được băm.
hashed_last_name family_name

Đặt thành tên gia đình đã định dạng và băm. Bạn cũng có thể mã hoá tên gia đình đã băm.
hashed_street_address Không có thành phần tương đương.
postal_code postal_code
state Không có thành phần tương đương.

Mã nhận dạng trên thiết bị di động

Nếu sử dụng mã nhận dạng thiết bị di động, hãy đặt mobile_data thành MobileData có một mục trong mobile_ids cho mỗi mã nhận dạng.

UserIdentifier (Google Ads API) MobileData (Data Manager API) Ghi chú
mobile_id mobile_ids Đặt thành danh sách mã nhận dạng thiết bị di động cho thành viên đối tượng.

Trong API Google Ads, bạn thêm một riêng biệt UserIdentifier có mobile_id cho mọi mã nhận dạng thiết bị di động của thành viên đối tượng. Trong Data Manager API, hãy thêm một MobileData mobile_ids duy nhất với được đặt thành danh sách tất cả mã nhận dạng thiết bị di động của thành viên đối tượng.

user_identifier_source Không có thành phần tương đương.

Mã nhận dạng người dùng

Nếu bạn sử dụng mã nhận dạng người dùng, hãy đặt user_id_data thành UserIdData và đặt user_id thành mã nhận dạng người dùng của thành viên đối tượng.

UserIdentifier (Google Ads API) UserIdData (Data Manager API) Ghi chú
third_party_user_id user_id

Trong Google Ads API, bạn thêm một riêng biệt UserIdentifier bằng third_party_user_id cho mỗi mã nhận dạng người dùng của thành viên đối tượng.

Trong Data Manager API, hãy đặt trường user_id_data thành UserIdData và đặt trường user_id thành mã nhận dạng người dùng của thành viên đối tượng. Bạn không thể gửi nhiều mã nhận dạng người dùng cho cùng một thành viên đối tượng.

user_identifier_source Không có thành phần tương đương.
Trước
Các bước nâng cấp