Panduan ini menjelaskan struktur umum untuk semua panggilan API.
Jika menggunakan library klien untuk berinteraksi dengan API, Anda tidak perlu mengkhawatirkan detail permintaan yang mendasarinya. Namun, mengetahui sedikit tentang hal tersebut 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.
[Preferred] Buat isi permintaan sebagai buffering protokol, kirim ke server menggunakan HTTP/2, lakukan deserialisasi respons ke buffering protokol, dan tafsirkan hasilnya. Sebagian besar dokumentasi kami menjelaskan penggunaan gRPC.
[Opsional] Buat isi permintaan sebagai objek JSON, kirim ke server menggunakan HTTP 1.1, lakukan deserialisasi respons sebagai objek JSON, dan tafsirkan hasilnya. Lihat panduan antarmuka REST untuk informasi lebih lanjut tentang penggunaan REST.
Nama resource
Sebagian besar objek di 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 ID induknya dan tanda gelombang (~).
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:
AdGroupIddari123+~+AdGroupAdIddari45678= ID iklan grup iklan gabungan dari123~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 mengelola akun mereka sendiri secara langsung. 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 baru. Perlu diperhatikan bahwa library klien akan otomatis memperbarui token yang sudah tidak berlaku.
token developer
Token developer adalah string berisi 22 karakter yang secara unik mengidentifikasi developer Google Ads API. 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 diotorisasi yang akan digunakan dalam permintaan, tanpa tanda hubung (-). Jika akses Anda ke akun pelanggan dilakukan melalui akun pengelola, header ini wajib ada dan harus ditetapkan ke ID pelanggan akun pengelola.
https://googleads.googleapis.com/v17/customers/1234567890/campaignBudgets:mutate
Menetapkan login-customer-id sama dengan memilih akun di
UI Google Ads setelah login atau mengklik foto profil di kanan
atas. Jika Anda tidak menyertakan header ini, header tersebut akan ditetapkan secara default ke pelanggan operasi.
link-customer-id
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. 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 (akunB).customer-id: Akun Google Ads tempat data diupload (akunA).- Header
login-customer-iddanAuthorization: Kombinasi nilai untuk mengidentifikasi pengguna yang memiliki akses ke akunB.
Header respons
Header berikut (atau grafis 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.