Pemetaan kolom

Gunakan pemetaan dalam tabel untuk memetakan metode dan kolom Google Ads API ke padanannya IngestEventsRequest di 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. Jalankan 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 tindakan konversi dan pelanggan.
  • Header permintaan developer-token
  • Header permintaan login-customer_id
  • Header permintaan linked-customer-id
 destinations Lihat Kolom tindakan konversi dan pelanggan.
  • 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 berdasarkan 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
 Dipetakan 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 dalam UserData. Untuk Data Manager API, Anda dapat menentukan izin untuk semua peristiwa dalam permintaan dengan menyetel kolom consent di IngestEventsRequest. Anda dapat mengganti nilai ini untuk setiap peristiwa dengan menyetel kolom consent dari Event.
Tidak ada ekuivalen encoding Wajib untuk upload UserData. Tetapkan ke Encoding yang digunakan untuk nilai UserIdentifier.
Tidak ada ekuivalen encryption_info Menetapkan apakah 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 tindakan konversi dan pelanggan.
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 hilir ditangani di tingkat peristiwa, yang dapat menghasilkan keberhasilan sebagian. Gunakan Diagnostik untuk mengambil status upload Anda serta error dan peringatan untuk setiap peristiwa. Jika IngestEventsRequest gagal (misalnya, karena BadRequest), tidak ada peristiwa yang diproses dan Anda harus menyelesaikan error serta mencoba kembali permintaan. Lihat Memahami error API untuk mengetahui informasi selengkapnya.
enable_warnings Tidak ada ekuivalen Gunakan Diagnostik untuk mengambil peringatan tentang permintaan Data Manager API Anda. Anda tidak perlu mengaktifkannya.
operations events Operasi OfflineUserDataJobOperation.create setara dengan mengirim IngestEventsRequest. Data Manager API tidak mendukung penghapusan acara.
validate_only validate_only
Tidak ada ekuivalen consent Google Ads API hanya mendukung penentuan consent di tingkat peristiwa dalam UserData. Untuk Data Manager API, Anda dapat menentukan izin untuk semua peristiwa dalam permintaan dengan menyetel kolom consent di IngestEventsRequest. Anda dapat mengganti nilai ini untuk setiap peristiwa dengan menyetel kolom consent dari Event.
Tidak ada ekuivalen encoding Wajib untuk upload UserData. Tetapkan ke Encoding yang digunakan untuk nilai UserIdentifier.
Tidak ada ekuivalen encryption_info Menetapkan apakah 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 login-customer-id dan linked-customer-id header permintaan untuk berbagai skenario autentikasi.

Data Manager API tidak memerlukan token developer, dan Anda menentukan informasi login dan pelanggan tertaut 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 Disetel 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 mendukung penyertaan hanya 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 Disetel ke IN_STORE untuk konversi penjualan toko.
transaction_attribute.conversion_action destinations.product_destination_id Lihat Kolom tindakan konversi dan pelanggan. 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)
  • cart_data.items[].conversion_value
 Tetapkan ke nilai mata uang, bukan nilai dalam mikro. Misalnya, untuk nilai konversi sebesar Rp5.230, 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
 Dipetakan 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 Ditetapkan ke harga satuan tidak termasuk pajak, pengiriman, 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 menyetel izin untuk semua peristiwa dalam permintaan dengan menyetel kolom consent di IngestEventsRequest.

Kolom ID pengguna

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

Sumber menentukan kolom mana 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 Disetel ke alamat email yang diformat dan di-hash. Anda juga dapat mengenkripsi alamat email yang di-hash.
hashed_phone_number phone_number Disetel ke nomor telepon yang diformat dan di-hash. Anda juga dapat mengenkripsi nomor telepon yang di-hash.
address_info address Disetel ke objek AddressInfo. Ikuti panduan pemformatan dan hashing. Anda juga dapat mengenkripsi atribut alamat yang di-hash.
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 di versi Data Manager API saat ini.
address_info.state Tidak ada ekuivalen Tidak didukung di versi Data Manager API saat ini.
address_info.hashed_street_address Tidak ada ekuivalen Tidak didukung di versi Data Manager API saat ini.
Sebelumnya
Langkah-langkah untuk mengupgrade