Panduan ini menjelaskan struktur umum untuk semua panggilan API.
Jika Anda menggunakan library klien untuk berinteraksi dengan API, Anda tidak Anda tidak perlu mengkhawatirkan detail permintaan yang mendasarinya. Namun, mengetahui sedikit tentang mereka dapat berguna saat pengujian dan {i>debugging<i}.
Google Ads API adalah gRPC API, dengan REST. Artinya, ada dua cara untuk melakukan panggilan ke API.
[Preferred] Buat isi permintaan sebagai buffering protokol, kirimkan ke server menggunakan HTTP/2, lakukan deserialisasi respons ke protokol {i>buffer<i}, dan menafsirkan hasilnya. Sebagian besar dokumentasi kami menjelaskan penggunaan gRPC.
[Opsional] Buat isi permintaan sebagai JSON, kirimkan ke server menggunakan HTTP 1.1, melakukan deserialisasi respons sebagai objek JSON, dan menafsirkan hasilnya. Rujuk ke lihat panduan antarmuka REST untuk informasi lebih lanjut tentang Istirahat.
Nama resource
Sebagian besar objek di API diidentifikasi melalui string nama resource-nya. Ini {i>string<i} juga berfungsi sebagai URL saat menggunakan antarmuka REST. Lihat REST Resource Names antarmuka untuk karena ada berbagai struktur penetapan harga.
ID Gabungan
Jika ID suatu objek tidak unik secara global, maka ID gabungan untuk objek tersebut dibuat dengan menambahkan ID induknya dan tanda gelombang (~).
Misalnya, karena ID iklan grup iklan tidak unik secara global, kami tambahkan ID objek induk (grup iklan) untuk membuat ID gabungan yang unik:
AdGroupIddari123+~+AdGroupAdIddari45678= iklan gabungan ID iklan grup123~45678.
Header permintaan
Berikut adalah header HTTP (atau grpc) metadata) yang menyertai isi permintaan:
Otorisasi
Anda perlu menyertakan token akses OAuth2 dalam bentuk
Authorization: Bearer YOUR_ACCESS_TOKEN yang mengidentifikasi
akun pengelola yang bertindak langsung atas nama klien atau pengiklan
mengelola akun mereka sendiri. Petunjuk untuk mengambil token akses
dapat ditemukan di panduan OAuth2. Channel
token akses berlaku selama satu jam setelah Anda mengakuisisinya; kapan
berakhir, perbarui token akses untuk mengambil yang baru. Perlu diketahui bahwa
perpustakaan klien kita secara otomatis
memperbarui token yang kedaluwarsa.
developer-token
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
dalam bentuk developer-token : ABcdeFGH93KL-NOPQ_STUv.
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
menggunakan akun pengelola.
https://googleads.googleapis.com/v17/customers/1234567890/campaignBudgets:mutate
Menyetel login-customer-id sama dengan memilih akun di
UI Google Ads setelah login atau mengklik foto profil Anda di bagian atas
ke kanan. Jika Anda tidak menyertakan header ini, maka default-nya adalah operasi
pelanggan.
linked-customer-id
Header ini hanya digunakan oleh penyedia analisis aplikasi pihak ketiga saat mengupload konversi ke akun Google Ads tertaut menggunakan akun layanan.
Pertimbangkan skenario ketika pengguna di akun A memberikan akses baca dan edit
ke entitasnya ke akun B melalui
ThirdPartyAppAnalyticsLink
Setelah ditautkan, pengguna di akun B dapat melakukan panggilan API terhadap akun A,
tunduk kepada izin yang diberikan oleh tautan tersebut. Dalam hal ini, panggilan API
izin untuk akun A ditentukan oleh tautan 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
{i>Header<i} berikut (atau metadata akhir grpc) ditampilkan dengan isi respons. Sebaiknya Anda mencatat untuk tujuan proses debug.
id-permintaan
request-id adalah string yang mengidentifikasi permintaan ini secara unik.