Sử dụng các mối liên kết trong bảng để liên kết các phương thức và trường của Google Ads API với phương thức và trường tương đương IngestEventsRequest trong Data Manager API.
Phương thức API
Data Manager API cho phép bạn tải từng lô lượt bán hàng tại cửa hàng thực tế lên trong một IngestEventsRequest.
Ngược lại, API Google Ads yêu cầu quy trình gồm 3 bước bằng cách sử dụng OfflineUserDataJobService:
- Tạo công việc bằng cách sử dụng
CreateOfflineUserDataJob - Thêm các thao tác vào lệnh bằng cách sử dụng
AddOfflineUserDataJobOperations - Chạy công việc bằng cách sử dụng
RunOfflineUserDataJob
Trường yêu cầu
Mỗi IngestEventsRequest đều phải tuân theo hạn mức yêu cầu. Nếu số lượng thao tác trong yêu cầu AddOfflineUserDataJobOperations của bạn vượt quá các giới hạn này, bạn phải chia yêu cầu này thành nhiều yêu cầu tiếp nhận Data Manager API.
Sau đây là cách các trường của yêu cầu API Google Ads liên kết với Data Manager API.
CreateOfflineUserDataJobRequest
Bảng sau đây cho thấy cách các trường của CreateOfflineUserDataJobRequest liên kết đến một IngestEventsRequest.
CreateOfflineUserDataJobRequest (Google Ads API) |
IngestEventsRequest (Data Manager API) |
Ghi chú |
|---|---|---|
customer_id |
destinations.operating_account |
Xem Trường khách hàng và hành động chuyển đổi. |
|
destinations |
Xem Trường khách hàng và hành động chuyển đổi. |
|
Chẩn đoán | Sử dụng request_id được trả về trong IngestEventsResponse để truy xuất thông tin chẩn đoán về lượt chuyển đổi mà bạn tải lên. |
job.id |
request_id |
Sử dụng request_id được trả về trong IngestEventsResponse để truy xuất thông tin chẩn đoán về lượt chuyển đổi mà bạn tải lên. |
job.external_id |
Không có phiên bản mới | |
job.type |
Không có phiên bản mới | |
job.store_sales_metadata.third_party_metadata.partner_id |
destinations.login_account |
Đối tác dữ liệu tải lượt chuyển đổi bán hàng tại cửa hàng thực tế lên sẽ được xác định bằng biểu tượng login_account của một đích đến. Hãy xem phần Định cấu hình đích đến để biết thêm thông tin. |
job.store_sales_metadata.third_party_metadata.advertiser_upload_date_time |
Không có phiên bản mới | |
job.store_sales_metadata.third_party_metadata.valid_transaction_fraction |
Không có phiên bản mới | |
job.store_sales_metadata.third_party_metadata.partner_match_fraction |
Không có phiên bản mới | |
job.store_sales_metadata.third_party_metadata.partner_upload_fraction |
Không có phiên bản mới | |
job.store_sales_metadata.third_party_metadata.bridge_map_version_id |
Không có phiên bản mới | |
job.store_sales_metadata.loyalty_fraction |
Không có phiên bản mới | |
job.store_sales_metadata.transaction_upload_fraction |
Không có phiên bản mới | |
job.store_sales_metadata.custom_key |
|
Liên kết với trường variable của CustomVariable ở cấp sự kiện hoặc ItemCustomVariable ở cấp mặt hàng. |
enable_match_rate_range_preview |
Không có phiên bản mới | |
validate_only |
validate_only |
|
| Không có phiên bản mới | consent |
API Google Ads chỉ hỗ trợ việc chỉ định consent ở cấp sự kiện trong UserData. Đối với Data Manager API, bạn có thể chỉ định sự đồng ý cho tất cả sự kiện trong một yêu cầu bằng cách đặt trường consent trên IngestEventsRequest. Bạn có thể ghi đè giá trị này cho một sự kiện riêng lẻ bằng cách đặt trường consent của Event. |
| Không có phiên bản mới | encoding |
Bắt buộc đối với tệp tải lên UserData. Đặ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 giá trị nhận dạng người dùng UserData được mã hoá. Hãy xem phần Mã hoá để biết thông tin chi tiết. |
AddOfflineUserDataJobOperationsRequest
Bảng sau đây cho thấy cách các trường của AddOfflineUserDataJobOperationsRequest liên kết đến một IngestEventsRequest.
AddOfflineUserDataJobOperationsRequest (Google Ads API) |
IngestEventsRequest (Data Manager API) |
Ghi chú |
|---|---|---|
|
destinations |
Xem Trường khách hàng và hành động chuyển đổi. |
resource_name |
Không có phiên bản mới | Data Manager API không yêu cầu bạn cập nhật tài nguyên công việc. |
enable_partial_failure |
Không có phiên bản mới | Nếu IngestEventsRequest thành công, mọi lỗi xảy ra trong quá trình xử lý tiếp theo sẽ được xử lý ở cấp sự kiện, điều này có thể dẫn đến thành công một phần. Sử dụng Chẩn đoán để truy xuất trạng thái của tệp tải lên cũng như lỗi và cảnh báo cho từng sự kiện. Nếu IngestEventsRequest thất bại (ví dụ: do BadRequest), thì không có sự kiện nào được xử lý và bạn sẽ cần giải quyết lỗi rồi thử lại yêu cầu. Hãy xem bài viết Tìm hiểu về lỗi API để biết thêm thông tin. |
enable_warnings |
Không có phiên bản mới | Sử dụng Chẩn đoán để truy xuất cảnh báo về yêu cầu API Data Manager. Bạn không cần bật chế độ này. |
operations |
events |
Thao tác OfflineUserDataJobOperation.create tương đương với việc gửi một IngestEventsRequest. Data Manager API không hỗ trợ việc xoá sự kiện. |
validate_only |
validate_only |
|
| Không có phiên bản mới | consent |
API Google Ads chỉ hỗ trợ việc chỉ định consent ở cấp sự kiện trong UserData. Đối với Data Manager API, bạn có thể chỉ định sự đồng ý cho tất cả sự kiện trong một yêu cầu bằng cách đặt trường consent trên IngestEventsRequest. Bạn có thể ghi đè giá trị này cho một sự kiện riêng lẻ bằng cách đặt trường consent của Event. |
| Không có phiên bản mới | encoding |
Bắt buộc đối với tệp tải lên UserData. Đặ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 giá trị nhận dạng người dùng UserData được mã hoá. Hãy xem phần Mã hoá để biết thông tin chi tiết. |
Các trường khách hàng và hành động chuyển đổi
Google Ads API yêu cầu tiêu đề của yêu cầu developer-token và bạn đặt login-customer-id và linked-customer-id
tiêu đề của yêu cầu cho các trường hợp xác thực khác nhau.
Data Manager API không yêu cầu mã thông báo của nhà phát triển và bạn chỉ định thông tin đăng nhập và 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 bài viết Đị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.
| 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 tài khoản chuyển đổi Google Ads. Đặ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 |
Nếu bạn đang truy cập vào operating_account bằng đường liên kết đố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. |
conversion_action |
product_destination_id |
Đặt thành mã nhận dạng dạng số của hành động chuyển đổi. Đừng sử dụng tên tài nguyên. |
Trường sự kiện
Bảng sau đây cho biết cách các trường của lượt chuyển đổi dẫn đến lượt bán hàng tại cửa hàng thực tế liên kết giữa hai API.
Không giống như Google Ads API (chỉ hỗ trợ việc thêm một mặt hàng duy nhất cho mỗi giao dịch bằng cách sử dụng ItemAttribute), Data Manager API hỗ trợ việc thêm nhiều mặt hàng cho mỗi sự kiện trong CartData.
OfflineUserDataJobOperation.create (Google Ads API) |
Event (Data Manager API) |
Ghi chú |
|---|---|---|
| Không có phiên bản mới | event_source |
Bắt buộc Đặt thành IN_STORE cho lượt chuyển đổi từ lượt bán hàng tại cửa hàng thực tế. |
transaction_attribute.conversion_action |
destinations.product_destination_id |
Xem Trường khách hàng và hành động chuyển đổi. Sử dụng mã nhận dạng dạng số của hành động chuyển đổi thay vì tên tài nguyên. |
transaction_attribute.transaction_date_time |
event_timestamp |
Hãy xem phần Định dạng dấu thời gian để biết thông tin chi tiết. |
transaction_attribute.transaction_amount_micros |
|
Đặt thành giá trị tiền tệ, không phải giá trị tính bằng phần triệu. Ví dụ: đối với giá trị lượt chuyển đổi là 5, 23 đô la Mỹ, hãy sử dụng giá trị 5.23. |
transaction_attribute.currency_code |
currency |
Bắt buộc. |
transaction_attribute.order_id |
transaction_id |
Bắt buộc. |
transaction_attribute.store_attribute.store_code |
event_location.store_id |
Bắt buộc Đặt mã cửa hàng trong trường store_id trong đối tượng EventLocation. |
transaction_attribute.custom_value |
|
Liên kết với trường value của CustomVariable ở cấp sự kiện hoặc ItemCustomVariable ở cấp mặt hàng. |
transaction_attribute.item_attribute.item_id |
cart_data.items[].merchant_product_id |
|
transaction_attribute.item_attribute.merchant_id |
|
Nếu bạn đặt cart_data.merchant_id, thuộc tính này sẽ hoạt động như một giá trị mặc định cho tất cả các mặt hàng, nhưng bạn có thể ghi đè giá trị này cho từng mặt hàng. |
transaction_attribute.item_attribute.country_code |
|
Nếu bạn đặt cart_data.merchant_feed_label, thuộc tính này sẽ hoạt động như một giá trị mặc định cho tất cả các mặt hàng, nhưng bạn có thể ghi đè giá trị này cho từng mặt hàng. |
transaction_attribute.item_attribute.language_code |
|
Nếu bạn đặt cart_data.merchant_feed_language_code, thuộc tính này sẽ hoạt động như một giá trị mặc định cho tất cả các mặt hàng, nhưng bạn có thể ghi đè giá trị này cho từng mặt hàng. |
transaction_attribute.item_attribute.quantity |
cart_data.items[].quantity |
|
| Không có phiên bản mới | cart_data.items[].unit_price |
Đặt thành giá đơn vị chưa bao gồm thuế, phí vận chuyển và chiết khấu theo phạm vi sự kiện (cấp giao dịch) cho mặt hàng này. |
user_identifiers |
|
Bắt buộc.
|
consent |
consent |
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ả các sự kiện trong một yêu cầu bằng cách đặt trường consent trên IngestEventsRequest. |
Trường giá trị nhận dạng người dùng
UserIdentifier (Google Ads API) |
UserIdentifier (Data Manager API) |
Ghi chú |
|---|---|---|
user_identifier_source |
Nguồn xác định trường cần điền trên Data Manager API
|
|
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. |
address_info |
address |
Đặt thành một đối tượng AddressInfo. Tuân thủ nguyên tắc định dạng và băm. Bạn cũng có thể mã hoá các thuộc tính đã băm của một địa chỉ. |
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 |
Không có phiên bản mới | Không được hỗ trợ trong phiên bản hiện tại của Data Manager API. |
address_info.state |
Không có phiên bản mới | Không được hỗ trợ trong phiên bản hiện tại của Data Manager API. |
address_info.hashed_street_address |
Không có phiên bản mới | Không được hỗ trợ trong phiên bản hiện tại của Data Manager API. |