Struktur Panggilan API

Panduan ini menjelaskan struktur umum dari semua panggilan API.

Jika menggunakan library klien untuk berinteraksi dengan API, Anda tidak perlu khawatir tentang detail permintaan yang mendasarinya. Namun, mengetahui sedikit tentang hal tersebut dapat berguna saat menguji dan melakukan debug.

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

  1. [Prefer] Membuat isi permintaan sebagai buffering protokol, mengirimnya ke server menggunakan HTTP/2, melakukan deserialisasi respons ke buffering protokol, dan menafsirkan hasilnya. Sebagian besar dokumentasi kami menjelaskan penggunaan gRPC.

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

Nama fasilitas

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

ID gabungan

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

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

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

Header permintaan

Header tersebut adalah header HTTP (atau metadata grpc) yang menyertai tubuh 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 berlaku selama satu jam setelah Anda memperolehnya; saat token akses berakhir, refresh token akses untuk mengambil yang baru. Perhatikan bahwa library klien kami secara otomatis memperbarui token yang sudah habis masa berlakunya.

token developer

Token developer adalah string 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.

ID pelanggan-login

Ini adalah ID pelanggan dari pelanggan yang diotorisasi yang akan digunakan dalam permintaan, tanpa tanda hubung (-). Jika akses Anda ke akun pelanggan adalah melalui akun pengelola, header ini diperlukan dan harus ditetapkan ke ID pelanggan akun pengelola.

https://googleads.googleapis.com/v11/customers/1234567890/campaignBudgets:mutate

Menetapkan login-customer-id sama dengan memilih akun di UI Google Ads setelah login atau mengklik gambar profil di kanan atas. Jika Anda tidak menyertakan header ini, header defaultnya adalah pelanggan yang mengoperasikan.

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 entity-nya ke akun B melalui ThirdPartyAppAnalyticsLink. Setelah ditautkan, pengguna di akun B dapat melakukan panggilan API terhadap akun A, yang tunduk pada izin yang diberikan oleh link. Dalam hal ini, izin panggilan API ke akun A ditentukan oleh link pihak ketiga ke akun B, bukan hubungan akun pengelola yang digunakan dalam panggilan API lainnya.

Penyedia analisis aplikasi pihak ketiga membuat 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 GcRP-metadata) ditampilkan dengan isi respons. Sebaiknya catat nilai ini ke dalam log untuk tujuan proses debug.

id-permintaan

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