Struktur Panggilan API

Panduan ini menjelaskan struktur umum semua panggilan API.

Jika menggunakan library klien untuk berinteraksi dengan API, Anda tidak perlu khawatir dengan detail permintaan yang mendasarinya. Namun, mengetahui sedikit tentangnya dapat berguna saat menguji dan men-debug.

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

1. [Direkomendasikan] Buat isi permintaan sebagai buffer protokol, kirim ke server menggunakan HTTP/2, deserialisasi respons ke buffer protokol, dan interpretasikan 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. Lihat panduan antarmuka REST untuk mengetahui informasi selengkapnya tentang penggunaan REST.

Catatan: Panduan ini menjelaskan struktur dan header transpor yang umum untuk protokol gRPC dan REST.

Nama resource

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.

Poin Penting: Lihat dokumentasi resource, untuk semua resource yang didukung dan representasi jalurnya (resource_name). Format yang sama digunakan untuk layanan lainnya.

ID Komposit

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

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

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

Header permintaan

Berikut 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 langsung mengelola akunnya sendiri. Petunjuk untuk mengambil token akses dapat ditemukan di panduan OAuth2. Token akses berlaku selama satu jam setelah Anda mendapatkannya; saat masa berlakunya berakhir, refresh token akses untuk mengambil token baru. Perhatikan bahwa library klien kami akan otomatis memuat ulang token yang telah habis masa berlakunya.

developer-token

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 format developer-token : ABcdeFGH93KL-NOPQ_STUv.

login-customer-id

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

Istilah Penting: Pelanggan yang beroperasi adalah ID pelanggan dalam payload permintaan. Misalnya, pelanggan yang beroperasi dalam permintaan CampaignBudgetService berikut adalah 1234567890:

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

Menetapkan login-customer-id sama dengan memilih akun di UI Google Ads setelah login atau mengklik foto profil Anda di kanan atas. Jika Anda tidak menyertakan header ini, header ini akan ditetapkan secara default ke pelanggan operasional.

Catatan: Anda dapat mengambil daftar akun yang dapat diakses secara langsung dengan kredensial OAuth Anda dengan mengeluarkan permintaan CustomerService.ListAccessibleCustomers. login-customer-id tidak diperlukan untuk jenis permintaan ini, dan tidak memengaruhi daftar pelanggan yang ditampilkan.

linked-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 entitas ke akun B melalui ThirdPartyAppAnalyticsLink. Setelah ditautkan, pengguna di akun B dapat melakukan panggilan API terhadap akun A, tunduk pada izin yang diberikan oleh penautan. 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 grpc trailing-metadata) ditampilkan dengan isi respons. Sebaiknya Anda mencatat nilai ini ke dalam log untuk tujuan proses debug.

request-id

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