Struktur panggilan API

Panduan ini menjelaskan struktur umum semua panggilan API.

Jika Anda menggunakan library klien untuk berinteraksi dengan API, Anda tidak perlu mengetahui detail permintaan yang mendasarinya. Namun, pengetahuan tentang struktur panggilan API dapat berguna saat melakukan 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 buffer protokol.
  2. Kirim ke server menggunakan HTTP/2.
  3. Lakukan deserialisasi respons ke buffer protokol.
  4. Interpretasi hasilnya.

Sebagian besar dokumentasi kami menjelaskan penggunaan gRPC.

Opsional:

  1. Buat isi permintaan sebagai objek JSON.
  2. Kirim ke server menggunakan HTTP 1.1.
  3. Lakukan deserialisasi respons sebagai objek JSON.
  4. Interpretasi hasilnya.

Lihat panduan antarmuka REST untuk mengetahui informasi selengkapnya tentang penggunaan REST.

Nama resource

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

ID Komposit

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

Misalnya, karena ID iklan grup iklan tidak unik secara global, kami menambahkan ID objek induknya (grup iklan) untuk membuat ID komposit yang unik:

  • AdGroupId dari 123 + ~ + AdGroupAdId dari 45678 = ID iklan grup iklan komposit 123~45678.

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 mengelola akunnya sendiri secara langsung. Petunjuk untuk mengambil token akses dapat ditemukan di panduan OAuth2. Token akses berlaku selama satu jam setelah Anda mendapatkannya. Jika masa berlakunya habis, perbarui token akses untuk mengambil token baru. Perhatikan bahwa library klien kami otomatis memperbarui token yang masa berlakunya habis.

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. Lihat Tingkat akses Google Ads untuk mengetahui detail tentang pengelolaan izin.

login-customer-id

Ini adalah ID pelanggan dari pelanggan yang diotorisasi untuk digunakan dalam permintaan, tanpa tanda hubung (-). Jika akses Anda ke akun pelanggan melalui akun pengelola, header ini wajib dan harus ditetapkan ke ID pelanggan akun pengelola. Jika Anda gagal 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.

https://googleads.googleapis.com/v25/customers/CUSTOMER_ID/campaignBudgets:mutate

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

linked-customer-id

Header ini diperlukan dan digunakan oleh partner (seperti penyedia analisis aplikasi pihak ketiga atau partner data) saat bertindak di akun Google Ads tertaut. Header ini harus menentukan ID pelanggan akun Google Ads yang memiliki penautan 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, sehingga memberikan akses Partner ke Pengiklan.

Pengguna yang memiliki akses ke akun Partner melakukan panggilan API untuk bertindak pada entity di akun Pengiklan (misalnya, untuk mengupload konversi atau mengelola daftar pengguna). Akun tertaut dapat berupa akun Pengiklan itu sendiri, atau akun pengelola 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 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 penautan produk dengan akun Partner, Akun tertaut adalah akun pengelola, dan linked-customer-id harus ditetapkan ke ID pelanggan pengelola.

Contoh 1: Penautan langsung

Jika akun Pengiklan 1111111111 memiliki penautan langsung dengan Partner akun 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 Partner akun 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 akhir grpc) ditampilkan dengan isi respons. Sebaiknya catat nilai ini untuk tujuan proses debug.

request-id

request-id adalah string yang secara unik mengidentifikasi permintaan ini.

Sebelumnya
Metadata resource