Pemetaan kolom

Gunakan pemetaan dalam tabel untuk memetakan metode dan kolom Google Ads API ke IngestEventsRequest yang setara di Data Manager API.

Autentikasi

Data Manager API memerlukan kredensial dengan cakupan yang berbeda dengan Google Ads API. Ikuti langkah-langkah di bagian Menyiapkan akses API untuk membuat kredensial baru yang menyertakan cakupan Data Manager API.

Metode API

Data Manager API memungkinkan Anda mengupload setiap batch peristiwa penjualan toko dalam satu IngestEventsRequest.

Sebaliknya, Google Ads API memerlukan proses tiga langkah menggunakan OfflineUserDataJobService:

  1. Membuat tugas menggunakan CreateOfflineUserDataJob
  2. Tambahkan operasi ke tugas menggunakan AddOfflineUserDataJobOperations
  3. Menjalankan tugas menggunakan RunOfflineUserDataJob

Kolom permintaan

Setiap IngestEventsRequest tunduk pada batas permintaan. Jika jumlah operasi dalam permintaan AddOfflineUserDataJobOperations Anda melebihi batas ini, Anda harus membaginya menjadi beberapa permintaan penyerapan Data Manager API.

Berikut cara pemetaan kolom permintaan Google Ads API ke Data Manager API.

CreateOfflineUserDataJobRequest

Tabel berikut menunjukkan cara kolom CreateOfflineUserDataJobRequest dipetakan ke IngestEventsRequest.

CreateOfflineUserDataJobRequest (Google Ads API) IngestEventsRequest (Data Manager API) Catatan
customer_id destinations.operating_account Lihat Kolom pelanggan dan tindakan konversi.
  • Header permintaan developer-token
  • Header permintaan login-customer_id
  • Header permintaan linked-customer-id
 destinations Lihat Kolom pelanggan dan tindakan konversi.
  • job.status
  • job.failure_reason
 Diagnostik Gunakan request_id yang ditampilkan di IngestEventsResponse untuk mengambil diagnostik tentang upload konversi Anda.
job.id request_id Gunakan request_id yang ditampilkan di IngestEventsResponse untuk mengambil diagnostik tentang upload konversi Anda.
job.external_id Tidak ada ekuivalen
job.type Tidak ada ekuivalen
job.store_sales_metadata.third_party_metadata.partner_id destinations.login_account Partner data yang mengupload konversi penjualan toko akan diidentifikasi oleh login_account tujuan. Lihat Mengonfigurasi tujuan untuk mengetahui detail selengkapnya.
job.store_sales_metadata.third_party_metadata.advertiser_upload_date_time Tidak ada ekuivalen
job.store_sales_metadata.third_party_metadata.valid_transaction_fraction Tidak ada ekuivalen
job.store_sales_metadata.third_party_metadata.partner_match_fraction Tidak ada ekuivalen
job.store_sales_metadata.third_party_metadata.partner_upload_fraction Tidak ada ekuivalen
job.store_sales_metadata.third_party_metadata.bridge_map_version_id Tidak ada ekuivalen
job.store_sales_metadata.loyalty_fraction Tidak ada ekuivalen
job.store_sales_metadata.transaction_upload_fraction Tidak ada ekuivalen
job.store_sales_metadata.custom_key
  • events[].custom_variables[].variable
  • events[].cart_data.items[].custom_variables[].variable
 Petakan ke kolom variable dari CustomVariable di tingkat peristiwa atau ItemCustomVariable di tingkat item.
enable_match_rate_range_preview Tidak ada ekuivalen
validate_only validate_only
Tidak ada ekuivalen consent Google Ads API hanya mendukung penentuan consent di tingkat peristiwa di UserData. Untuk Data Manager API, Anda dapat menentukan izin untuk semua peristiwa dalam permintaan dengan menetapkan kolom consent di IngestEventsRequest. Anda dapat mengganti nilai ini untuk setiap peristiwa dengan menetapkan kolom consent dari Event.
Tidak ada ekuivalen encoding Diperlukan untuk upload UserData. Tetapkan ke Encoding yang digunakan untuk nilai UserIdentifier.
Tidak ada ekuivalen encryption_info Tetapkan jika permintaan berisi ID pengguna UserData yang dienkripsi. Lihat Enkripsi untuk mengetahui detailnya.

AddOfflineUserDataJobOperationsRequest

Tabel berikut menunjukkan cara kolom AddOfflineUserDataJobOperationsRequest dipetakan ke IngestEventsRequest.

AddOfflineUserDataJobOperationsRequest (Google Ads API) IngestEventsRequest (Data Manager API) Catatan
  • Header permintaan developer-token
  • Header permintaan login-customer_id
  • Header permintaan linked-customer-id
 destinations Lihat Kolom pelanggan dan tindakan konversi.
resource_name Tidak ada ekuivalen Data Manager API tidak memerlukan pembaruan resource tugas.
enable_partial_failure Tidak ada ekuivalen Jika IngestEventsRequest berhasil, kegagalan apa pun yang terjadi selama pemrosesan downstream akan ditangani di tingkat peristiwa, yang dapat menghasilkan keberhasilan parsial. Gunakan Diagnostik untuk mengambil status upload serta error dan peringatan untuk setiap peristiwa. Jika IngestEventsRequest gagal (misalnya, karena BadRequest), tidak ada peristiwa yang diproses dan Anda harus menyelesaikan error tersebut dan mencoba kembali permintaan. Lihat Memahami error API untuk mengetahui informasi selengkapnya.
enable_warnings Tidak ada ekuivalen Gunakan Diagnostik untuk mengambil peringatan tentang permintaan API Data Manager Anda. Anda tidak perlu mengaktifkannya.
operations events Operasi OfflineUserDataJobOperation.create setara dengan mengirim IngestEventsRequest. Data Manager API tidak mendukung penghapusan peristiwa.
validate_only validate_only
Tidak ada ekuivalen consent Google Ads API hanya mendukung penentuan consent di tingkat peristiwa di UserData. Untuk Data Manager API, Anda dapat menentukan izin untuk semua peristiwa dalam permintaan dengan menetapkan kolom consent di IngestEventsRequest. Anda dapat mengganti nilai ini untuk setiap peristiwa dengan menetapkan kolom consent dari Event.
Tidak ada ekuivalen encoding Diperlukan untuk upload UserData. Tetapkan ke Encoding yang digunakan untuk nilai UserIdentifier.
Tidak ada ekuivalen encryption_info Tetapkan jika permintaan berisi ID pengguna UserData yang dienkripsi. Lihat Enkripsi untuk mengetahui detailnya.

Kolom tindakan konversi dan pelanggan

Google Ads API memerlukan header permintaan developer-token, dan Anda menetapkan header permintaan login-customer-id dan linked-customer-id untuk berbagai skenario autentikasi.

Data Manager API tidak memerlukan token developer, dan Anda menentukan informasi pelanggan yang ditautkan dan login menggunakan kolom Destination, bukan header permintaan. Lihat Mengonfigurasi tujuan untuk mengetahui informasi selengkapnya tentang tujuan.

Google Ads API Destination (Data Manager API) Catatan
customer_id permintaan operating_account Tetapkan account_id ke ID pelanggan akun konversi Google Ads. Tetapkan account_type dari operating_account ke GOOGLE_ADS.
Header permintaan developer-token Tidak ada ekuivalen Token developer tidak diperlukan untuk Data Manager API.
Header permintaan login-customer-id login_account Tetapkan account_id ke ID pelanggan akun login. Tetapkan account_type ke GOOGLE_ADS jika akun login adalah akun Google Ads, atau DATA_PARTNER jika akun login adalah akun partner data.
Header permintaan linked-customer-id linked_account Jika Anda mengakses operating_account menggunakan link partner, tetapkan account_id ke ID pelanggan akun tertaut dan tetapkan account_type ke DATA_PARTNER. Jika tidak, jangan tetapkan kolom linked_account.
conversion_action product_destination_id Tetapkan ke ID numerik tindakan konversi. Jangan gunakan nama resource.

Kolom peristiwa

Tabel berikut menunjukkan cara kolom konversi penjualan toko dipetakan di antara kedua API.

Tidak seperti Google Ads API, yang hanya mendukung penyertaan satu item per transaksi menggunakan ItemAttribute, Data Manager API mendukung penyertaan beberapa item per peristiwa di CartData.

OfflineUserDataJobOperation.create (Google Ads API) Event (Data Manager API) Catatan
Tidak ada ekuivalen event_source Wajib Tetapkan ke IN_STORE untuk konversi penjualan toko.
transaction_attribute.conversion_action destinations.product_destination_id Lihat Kolom pelanggan dan tindakan konversi. Gunakan ID numerik tindakan konversi, bukan nama resource.
transaction_attribute.transaction_date_time event_timestamp
Lihat Format stempel waktu untuk mengetahui detailnya.
transaction_attribute.transaction_amount_micros
  • conversion_value (Wajib diisi)
  • cart_data.items[].conversion_value
 Tetapkan ke nilai mata uang, bukan nilai dalam mikro. Misalnya, untuk nilai konversi $5,23, gunakan nilai 5.23.
transaction_attribute.currency_code currency Wajib.
transaction_attribute.order_id transaction_id Wajib.
transaction_attribute.store_attribute.store_code event_location.store_id Wajib Tetapkan kode toko di kolom store_id dalam objek EventLocation.
transaction_attribute.custom_value
  • custom_variables[].value
  • cart_data.items[].custom_variables[].value
 Petakan ke kolom value dari CustomVariable di tingkat peristiwa atau ItemCustomVariable di tingkat item.
transaction_attribute.item_attribute.item_id cart_data.items[].merchant_product_id
transaction_attribute.item_attribute.merchant_id
  • cart_data.merchant_id
  • cart_data.items[].merchant_id
 Jika Anda menetapkan cart_data.merchant_id, atribut ini akan berfungsi sebagai default untuk semua item, tetapi Anda dapat menggantinya untuk setiap item.
transaction_attribute.item_attribute.country_code
  • cart_data.merchant_feed_label
  • cart_data.items[].merchant_feed_label
 Jika Anda menetapkan cart_data.merchant_feed_label, atribut ini akan berfungsi sebagai default untuk semua item, tetapi Anda dapat menggantinya untuk setiap item.
transaction_attribute.item_attribute.language_code
  • cart_data.merchant_feed_language_code
  • cart_data.items[].merchant_feed_language_code
 Jika Anda menetapkan cart_data.merchant_feed_language_code, atribut ini akan berfungsi sebagai default untuk semua item, tetapi Anda dapat menggantinya untuk setiap item.
transaction_attribute.item_attribute.quantity cart_data.items[].quantity
Tidak ada ekuivalen cart_data.items[].unit_price Tetapkan ke harga satuan sebelum pajak, ongkos kirim, dan diskon cakupan peristiwa (tingkat transaksi) untuk item ini.
user_identifiers
  • user_data.user_identifiers
  • third_party_user_data.user_identifiers
 Wajib diisi.

third_party_user_data menggunakan struktur yang sama dengan user_data, tetapi menunjukkan bahwa ID pengguna berasal dari sumber pihak ketiga, bukan data pengiklan pihak pertama.

Pengisian third_party_user_data hanya diizinkan jika akun login adalah partner data (login_account.account_type adalah DATA_PARTNER).

Lihat Kolom ID pengguna untuk mengetahui detailnya.

consent consent Kedua API menggunakan objek Consent yang serupa (ad_user_data, ad_personalization). Untuk Data Manager API, Anda juga dapat menetapkan izin untuk semua peristiwa dalam permintaan dengan menetapkan kolom consent di IngestEventsRequest.

Kolom ID pengguna

UserIdentifier (Google Ads API) UserIdentifier (Data Manager API) Catatan
user_identifier_source

Sumber menentukan kolom yang akan diisi di Event Data Manager API:

  • user_data
  • third_party_user_data

third_party_user_data menggunakan struktur yang sama dengan user_data, tetapi menunjukkan bahwa ID pengguna berasal dari sumber pihak ketiga, bukan data pengiklan pihak pertama.

Pengisian third_party_user_data hanya diizinkan jika akun login adalah partner data (login_account.account_type adalah DATA_PARTNER).

Lihat Kolom ID pengguna untuk mengetahui detailnya.

hashed_email email_address Tetapkan ke alamat email yang diformat dan di-hash. Anda juga dapat mengenkripsi alamat email yang di-hash.
hashed_phone_number phone_number Tetapkan ke nomor telepon yang diformat dan di-hash. Anda juga dapat mengenkripsi nomor telepon yang di-hash.
address_info address Tetapkan ke objek AddressInfo. Ikuti panduan pemformatan dan hashing. Anda juga dapat mengenkripsi atribut yang di-hash dari sebuah alamat.
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 Tidak ada ekuivalen Tidak didukung untuk tujuan iklan Google Ads.
address_info.state Tidak ada ekuivalen Tidak didukung untuk tujuan iklan Google Ads.
address_info.hashed_street_address Tidak ada ekuivalen Tidak didukung untuk tujuan iklan Google Ads.
Sebelumnya
Langkah-langkah untuk mengupgrade