Struktur panggilan API

Panduan ini menjelaskan struktur umum semua panggilan API.

Jika menggunakan library klien untuk berinteraksi dengan API, Anda tidak perlu mengetahui detail permintaan yang mendasarinya. Namun, beberapa pengetahuan tentang struktur panggilan API dapat berguna saat pengujian dan proses debug.

Google Ads API adalah gRPC API, dengan binding REST. Artinya, ada dua cara untuk melakukan panggilan ke API.

Pilihan:

1. Buat isi permintaan sebagai buffering protokol.
2. Kirim ke server menggunakan HTTP/2.
3. Lakukan deserialisasi respons ke buffering protokol.
4. Menafsirkan hasilnya.

Sebagian besar dokumentasi kami menjelaskan penggunaan gRPC.

Opsional:

1. Buat isi permintaan sebagai objek JSON.
2. Kirimkan ke server menggunakan HTTP 1.1.
3. Melakukan deserialisasi respons sebagai objek JSON.
4. Menafsirkan hasilnya.

Lihat panduan antarmuka REST untuk mengetahui informasi selengkapnya tentang cara menggunakan REST.

Catatan: Panduan ini menjelaskan struktur dan header transport yang umum untuk protokol gRPC dan REST.

ID resource

Objek di Google Ads API ditangani menggunakan nama resource terstruktur dan ID gabungan.

Nama resource

Sebagian besar objek di API diidentifikasi berdasarkan string nama resource-nya. String ini juga berfungsi sebagai URL saat menggunakan antarmuka REST. Lihat Nama resource antarmuka REST untuk mengetahui strukturnya.

Poin Penting: Lihat dokumentasi resource untuk semua resource yang didukung dan representasi jalurnya (resource_name). Format yang sama digunakan untuk layanan lain.

ID Komposit

Jika ID objek tidak unik secara global, ID gabungan untuk objek tersebut akan dibuat dengan menambahkan ID induknya dan tilde (~) di awal.

Misalnya, AdGroupAd memiliki pola nama resource customers/{customer_id}/adGroupAds/{ad_group_id}~{ad_id}. Karena ID gabungannya menggabungkan ID grup iklan induk (ad_group.id) dan ID iklan yang mendasarinya (ad_group_ad.ad.id), kita menambahkan ID grup iklan ke ID iklan:

• AdGroupId dari 123 + ~ + AdId dari 45678 = ID iklan grup iklan gabungan dari 123~45678.

Catatan: Membagikan AdId di beberapa grup iklan dilarang. Pembuatan AdGroupAd baru yang merujuk ke AdId yang ada di grup iklan lain akan gagal dengan error AdGroupAdError.AD_SHARING_NOT_ALLOWED.

Header permintaan

Berikut adalah header HTTP (atau metadata gRPC) yang menyertai isi dalam permintaan:

Otorisasi

Anda harus menyertakan token akses OAuth 2.0 dalam bentuk Authorization: Bearer YOUR_ACCESS_TOKEN yang mengidentifikasi akun pengelola yang bertindak atas nama klien, atau pengiklan yang langsung mengelola akunnya sendiri. Petunjuk untuk mengambil token akses dapat ditemukan di panduan OAuth2. Token akses berlaku selama satu jam setelah Anda mendapatkannya; saat masa berlakunya habis, refresh token akses untuk mengambil token baru. Perhatikan bahwa library klien kami otomatis memperbarui token yang sudah tidak berlaku.

Jika Anda mengalami error otorisasi, pastikan Anda menggunakan kredensial yang benar dan memiliki izin yang memadai. Error USER_PERMISSION_DENIED menunjukkan bahwa pengguna yang diautentikasi mungkin tidak memiliki akses ke akun pelanggan yang ditentukan dalam permintaan. Jika project Google Cloud Anda hanya disetujui untuk akses Test dan Anda mengirim permintaan yang menargetkan akun produksi, API akan menampilkan AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION di v25 dan yang lebih baru (atau AuthorizationError.ACTION_NOT_PERMITTED di v24 dan yang lebih lama). Lihat tingkat akses Google Ads untuk mengetahui detail tentang cara mengelola izin.

login-customer-id

Ini adalah ID pelanggan dari pelanggan yang diberi otorisasi untuk digunakan dalam permintaan, tanpa tanda hubung (-). Jika akses Anda ke akun pelanggan adalah melalui akun pengelola, header ini diperlukan dan harus ditetapkan ke ID pelanggan akun pengelola. Jika Anda tidak menyertakan login-customer-id saat melakukan autentikasi melalui akun pengelola, hal ini akan menyebabkan error AuthorizationError.USER_PERMISSION_DENIED. Tinjau error umum untuk mengetahui informasi selengkapnya tentang jenis error ini. Untuk penjelasan mendetail tentang cara akses akun diselesaikan, lihat panduan model akses OAuth.

Istilah Penting: Pelanggan yang beroperasi adalah ID pelanggan dalam payload permintaan. Misalnya, pelanggan yang beroperasi dalam permintaan CampaignBudgetService berikut adalah 1234567890:

https://googleads.googleapis.com/v26/customers/1234567890/campaignBudgets:mutate

Menetapkan login-customer-id sama dengan memilih akun di UI Google Ads setelah login atau mengklik foto profil Anda di kanan atas. Jika Anda tidak menyertakan header ini, header akan ditetapkan secara default ke operating customer.

Catatan: Anda dapat mengambil daftar akun yang dapat diakses secara langsung dengan kredensial OAuth Anda dengan mengeluarkan permintaan CustomerService.ListAccessibleCustomers. login-customer-id tidak diperlukan untuk jenis permintaan ini, dan tidak berpengaruh pada daftar pelanggan yang ditampilkan.

linked-customer-id

Header ini wajib diisi dan digunakan oleh partner (seperti penyedia analisis aplikasi pihak ketiga atau partner data) saat bertindak atas akun Google Ads tertaut. Header ini harus menentukan ID pelanggan akun Google Ads yang memiliki tautan produk.

Pertimbangkan skenario saat partner perlu melakukan panggilan API ke akun Google Ads berdasarkan penautan produk.

• Pengiklan: Akun Google Ads yang dikelola atau diperbarui oleh panggilan API. ID akun Pengiklan ditentukan dalam permintaan. Di REST, ini adalah parameter jalur customerId (misalnya, customers/1111111111/...), dan di gRPC, ini adalah kolom customer_id dalam permintaan.
• Partner: Akun partner (misalnya, penyedia analisis aplikasi pihak ketiga atau partner data).
• Akun tertaut: Akun Google Ads yang memiliki penautan produk yang ditetapkan dengan Partner, yang memberi Partner akses ke Pengiklan.

Pengguna yang memiliki akses ke akun Partner melakukan panggilan API untuk bertindak atas entitas di akun Pengiklan (misalnya, untuk mengupload konversi atau mengelola daftar pengguna). Akun tertaut dapat berupa akun Pengiklan itu sendiri, atau akun pengelola dari akun Pengiklan.

Header permintaan harus ditetapkan sebagai berikut:

• Authorization: Token akses OAuth 2.0 untuk pengguna yang memiliki akses ke Partner.
• login-customer-id: ID pelanggan akun Partner. Pengguna yang diautentikasi harus memiliki akses ke akun ini.
• linked-customer-id: ID pelanggan Akun tertaut. Header ini menandakan bahwa otorisasi untuk permintaan ini bergantung pada penautan produk Akun tertaut dengan Partner.

Ada dua skenario penautan:

• Jika akun Pengiklan memiliki penautan produk langsung dengan akun Partner, Akun tertaut adalah Pengiklan, dan linked-customer-id harus ditetapkan ke ID pelanggan akun Pengiklan.
• Jika akun Pengiklan dikelola oleh akun pengelola yang memiliki tautan produk dengan akun Partner, Akun tertaut adalah akun pengelola, dan linked-customer-id harus ditetapkan ke ID pelanggan pengelola.

Contoh 1: Link langsung

Jika akun Pengiklan 1111111111 memiliki penautan langsung dengan akun Partner 2222222222, dan panggilan API menargetkan customers/1111111111/...:

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

Contoh 2: Penautan pengelola

Jika akun Pengiklan 1111111111 dikelola oleh akun pengelola 3333333333, akun pengelola 3333333333 memiliki penautan dengan akun Partner 2222222222, dan panggilan API menargetkan customers/1111111111/...:

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

Header respons

Header berikut (atau metadata tambahan gRPC) ditampilkan dengan isi respons. Sebaiknya Anda mencatat nilai ini ke dalam log untuk tujuan proses debug.

request-id

request-id adalah string yang secara unik mengidentifikasi permintaan ini. Berikan nilai ini saat menghubungi dukungan untuk membantu memecahkan masalah permintaan API yang gagal atau tidak terduga.