Struktur Panggilan API

Panduan ini menjelaskan struktur umum semua panggilan API.

Jika menggunakan library klien untuk berinteraksi dengan API, Anda tidak perlu mengkhawatirkan detail permintaan yang mendasarinya. Namun, mengetahui sedikit tentang keduanya dapat berguna saat pengujian dan proses debug.

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

  1. [Preferred] Buat isi permintaan sebagai buffering protokol, kirim ke server menggunakan HTTP/2, lakukan deserialisasi respons ke buffering protokol, dan interpretasikan hasilnya. Sebagian besar dokumentasi kami menjelaskan penggunaan gRPC.

  2. [Opsional] Buat isi permintaan sebagai objek JSON, kirimkan ke server menggunakan HTTP 1.1, lakukan deserialisasi respons sebagai objek JSON, dan interpretasikan hasilnya. Lihat panduan antarmuka REST untuk informasi lebih lanjut tentang penggunaan REST.

Nama resource

Sebagian besar objek dalam API diidentifikasi melalui string nama resource-nya. String ini juga berfungsi sebagai URL saat menggunakan antarmuka REST. Lihat Resource Names antarmuka REST untuk strukturnya.

ID gabungan

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

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

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

Header permintaan

Ini adalah header HTTP (atau metadata grpc) yang menyertai isi dalam permintaan:

Otorisasi

Anda harus menyertakan token akses OAuth2 dalam bentuk Authorization: Bearer YOUR_ACCESS_TOKEN yang mengidentifikasi akun pengelola yang bertindak atas nama klien atau pengiklan yang secara langsung mengelola akunnya sendiri. Petunjuk untuk mengambil token akses dapat ditemukan di panduan OAuth2. Token akses valid selama satu jam setelah Anda memperolehnya; setelah masa berlakunya berakhir, refresh token akses untuk mengambil token yang baru. Perlu diperhatikan bahwa library klien kami akan otomatis memperbarui token yang telah habis masa berlakunya.

token developer

Token developer adalah string 22 karakter yang mengidentifikasi developer Google Ads API secara unik. Contoh string token developer adalah ABcdeFGH93KL-NOPQ_STUv. Token developer harus disertakan dalam bentuk developer-token : ABcdeFGH93KL-NOPQ_STUv.

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 melalui akun pengelola, header ini wajib ada dan harus ditetapkan ke ID pelanggan akun pengelola.

https://googleads.googleapis.com/v16/customers/1234567890/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 akan ditetapkan secara default ke pelanggan yang beroperasi.

id-pelanggan-tertaut

Header ini hanya digunakan oleh penyedia analisis aplikasi pihak ketiga saat mengupload konversi ke akun Google Ads tertaut.

Pertimbangkan skenario saat pengguna di akun A memberikan akses baca dan edit ke entitasnya untuk akun B melalui ThirdPartyAppAnalyticsLink. Setelah ditautkan, pengguna di akun B dapat melakukan panggilan API terhadap akun A, tunduk pada izin yang diberikan oleh link tersebut. Dalam hal ini, izin panggilan API ke akun A ditentukan oleh penautan pihak ketiga ke akun B, bukan hubungan akun pengelola yang digunakan dalam panggilan API lainnya.

Penyedia analisis aplikasi pihak ketiga melakukan panggilan API sebagai berikut:

  • linked-customer-id: Akun analisis aplikasi pihak ketiga yang mengupload data (akun B).
  • customer-id: Akun Google Ads tempat data diupload (akun A).
  • Header login-customer-id dan Authorization: Kombinasi nilai untuk mengidentifikasi pengguna yang memiliki akses ke akun B.

Header respons

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

request-id

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