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.
[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.
[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
dari123
+~
+AdGroupAdId
dari45678
= 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 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 (akunB
).customer-id
: Akun Google Ads tempat data diupload (akunA
).- Header
login-customer-id
danAuthorization
: Kombinasi nilai untuk mengidentifikasi pengguna yang memiliki akses ke akunB
.
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.