Ánh xạ trường

Sử dụng thông tin 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ừ Google Ads API lên Data Manager API:

• Liên kết trường quản lý đối tượng chứa các liên kết trường để tạo, cập nhật và truy xuất đối tượng.

• Ánh xạ trường nhập dữ liệu chứa các mối liên kết trường để thêm hoặc xoá thành viên trong phân khúc đối tượng.

Xác thực

Data Manager API yêu cầu thông tin xác thực có phạm vi khác với Google Ads API. Làm theo các bước trong phần Thiết lập quyền truy cập API để tạo thông tin xác thực mới, bao gồm cả phạm vi của Data Manager API.

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

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

UserList (Google Ads API)	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	Thời gian một thành viên trong phân khúc đối tượng vẫn nằm trong danh sách sau khi được thêm. Giá trị phải tương ứng với số ngày nguyên. Nếu không được đặt, giá trị mặc định sẽ 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 để biết 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 để biết 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 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 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 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 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 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 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 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 dùng cho tính năng So khớp khách hàng.

Thông tin về đối tượng So khớp khách hàng

Trong Google Ads API, bạn phải đặt trường crm_based_user_list thành CrmBasedUserListInfo 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.

Tên tài nguyên

Data Manager API sử dụng đị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 mối liên kết trong bảng để liên kết một AddOfflineUserDataJobOperationsRequest trong Google Ads API với yêu cầu IngestionService tương đương trong Data Manager API.

Trường yêu cầu

Những mối liên kết này sử dụng IngestAudienceMembersRequest trong API Trình quản lý dữ liệu làm tệp đối chiếu, nhưng bạn cũng có thể sử dụng những mối liên kết này nếu đang chuyển đổi yêu cầu API Google Ads thành RemoveAudienceMembersRequest hoặc RemoveAllAudienceMembersRequest.

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 thành viên trong phân khúc đối tượng trong yêu cầu. Bạn có thể ghi đè giá trị này cho một thành viên trong phân khúc đố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 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ị đã 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	Data Manager API sử dụng mô hình lỗi nhanh hỏng. Nếu bất kỳ trường nào của IngestAudienceMembersRequest không được xác thực, thì API Trình quản lý dữ liệu sẽ từ chối toàn bộ yêu cầu. Truy xuất lỗi xử lý bằng cách sử dụ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 diagnostics.
validate_only	validate_only
operations	audience_members	Danh sách thành viên trong phân khúc đối tượng cần thêm hoặc xoá. Hãy xem mục Trường thao tác để 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 trong phân khúc đối tượng lên một đối tượng cho mỗi công việc.Ngoài ra, bạn cần có tiêu đề của yêu cầu developer-token và bạn đặt tiêu đề của yêu cầu login-customer-id và linked-customer-id 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 trong phân khúc đối tượng cho nhiều đối tượng trong một yêu cầu duy nhất. 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ác trường của Destination thay vì tiêu đề của yêu cầu. Hãy xem bài viết Định cấu hình đích đến để biết thêm thông tin về đích đến.

Trong API Google Ads, 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.

Trong Data Manager API, bạn có thể thực hiện việc này bằng cách gửi một RemoveAllAudienceMembersRequest. Xem hướng dẫn Xoá tất cả thành viên để biết thông tin chi tiết.

Sau đây là cách liên kết các trường của Google Ads API cho một đối tượng 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ã 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 phải có mã của nhà phát triển để sử dụng 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	Nếu bạn đang truy cập vào operating_account bằng đường liên kết của đối tác, hãy đặt account_id thành mã khách hàng của tài khoản được liên kết và đặt account_type thành DATA_PARTNER. Nếu không, đừng đặt trường linked_account.
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 đang gửi thành viên trong phân khúc đối tượng cho nhiều đối tượng trong một yêu cầu.

Trường hoạt động

API Trình quản lý dữ liệu có các phương thức riêng biệt để thêm và xoá thành viên trong phân khúc đối tượng. Ngược lại, AddOfflineUserDataJobOperationsRequest trong Google Ads API chứa danh sách operations, mỗi thao tác sẽ thêm một thành viên, xoá một thành viên hoặc xoá tất cả thành viên dựa trên loại thao tác. Dưới đây là mối liên kết giữa từng loại thao tác với phương thức tương ứng trong Data Manager API:

OfflineUserDataJobOperation (Google Ads API)	Phương thức IngestionService (Data Manager API)	Ghi chú
create	IngestAudienceMembers	Hãy xem mục Trường thành viên trong phân khúc đối tượng để biết thông tin chi tiết.
remove	RemoveAudienceMembers	Hãy xem mục Trường thành viên trong phân khúc đối tượng để biết thông tin chi tiết.
remove_all	RemoveAllAudienceMembers	Hãy xem phần Xoá tất cả thành viên trong phân khúc đối tượng để biết thông tin chi tiết.

Trường thành viên trong phân khúc đố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 phân khúc đố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 trạng thái đồng ý cho tất cả thành viên trong phân khúc đố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_data user_id_data composite_data user_data ip_data	Điền vào trường tương ứng với loại dữ liệu mà bạn đang gửi cho thành viên trong phân khúc đố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 Google Ads API, 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. API Trình quản lý dữ liệu 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 vào trường tương ứng với loại dữ liệu mà bạn đang gửi: