Struktur Panggilan API

Panduan ini menjelaskan struktur umum semua panggilan API.

Jika Anda menggunakan library klien untuk berinteraksi dengan API, Anda tidak perlu mengetahui detail permintaan yang mendasarinya. Namun, pengetahuan tentang struktur panggilan API 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.

Pilihan:

1. Buat isi permintaan sebagai buffer protokol.

2. Kirim ke server menggunakan HTTP/2.

3. Lakukan deserialisasi respons ke buffer protokol.

4. Interpretasikan hasilnya.

Sebagian besar dokumentasi kami menjelaskan penggunaan gRPC.

Opsional:

1. Buat isi permintaan sebagai objek JSON.

2. Kirim ke server menggunakan HTTP 1.1.

3. Lakukan deserialisasi respons sebagai objek JSON.

4. Interpretasikan hasilnya.

Lihat panduan antarmuka REST untuk mengetahui informasi selengkapnya tentang penggunaan REST.

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

Nama resource

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

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

resource_name

ID Komposit

Jika ID objek tidak unik secara global, ID komposit untuk objek tersebut akan dibuat dengan menambahkan ID induknya dan tilde (~).

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

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

Header permintaan

Berikut adalah header HTTP (atau grpc metadata) 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 akunnya sendiri secara langsung. Petunjuk untuk mengambil token akses dapat ditemukan di panduan OAuth2. Token akses berlaku selama satu jam setelah Anda mendapatkannya. Jika masa berlakunya berakhir, refresh token akses untuk mengambil token baru. Perhatikan bahwa library klien kami otomatis me-refresh token yang masa berlakunya telah berakhir.

Jika Anda mengalami error otorisasi, pastikan Anda menggunakan kredensial yang benar dan memiliki izin yang memadai. Error USER_PERMISSION_DENIED menunjukkan bahwa pengguna yang diautentikasi mungkin tidak memiliki akses ke akun pelanggan yang ditentukan dalam permintaan. Lihat Tingkat Akses Google Ads untuk mengetahui detail tentang pengelolaan izin.

developer-token

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.

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 dan harus ditetapkan ke ID pelanggan akun pengelola. Jika Anda gagal menyertakan login-customer-id saat melakukan autentikasi melalui akun pengelola, hal ini akan menghasilkan error AuthorizationError.USER_PERMISSION_DENIED. Tinjau Error Umum untuk mengetahui informasi selengkapnya tentang jenis error ini. Untuk mengetahui penjelasan mendetail tentang cara akses akun diselesaikan, lihat panduan model akses akses OAuth.

Istilah Kunci: **Pelanggan operasi** adalah ID pelanggan dalam payload permintaan. Misalnya, pelanggan operasi dalam permintaan CampaignBudgetService berikut adalah 1234567890:

https://googleads.googleapis.com/v24/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 ini akan ditetapkan secara default ke pelanggan operasi.

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

linked-customer-id

Header ini diperlukan dan digunakan oleh partner (seperti penyedia analisis aplikasi pihak ketiga atau partner data) saat bertindak di akun Google Ads tertaut. Header ini harus menentukan ID Pelanggan akun Google Ads yang memiliki link produk.

Pertimbangkan skenario saat partner perlu melakukan panggilan API ke akun Google Ads berdasarkan link produk.

• Pengiklan: Akun Google Ads yang dikelola atau diperbarui oleh panggilan API. ID akun Pengiklan ditentukan dalam permintaan. Di REST, ini adalah parameter jalur customerId (misalnya, customers/1111111111/...), dan di gRPC, ini adalah kolom customer_id dalam permintaan.
• Partner: Akun partner (misalnya, penyedia analisis aplikasi pihak ketiga atau partner data).
• Akun tertaut: Akun Google Ads yang memiliki link produk yang ditetapkan dengan Partner, sehingga memberikan akses Partner ke Pengiklan.

Pengguna yang memiliki akses ke Partner melakukan panggilan API untuk bertindak pada entity di Pengiklan (misalnya, untuk mengupload konversi atau mengelola daftar pengguna). Akun tertaut dapat berupa Pengiklan itu sendiri, atau akun pengelola Pengiklan.

Header permintaan harus ditetapkan sebagai berikut:

• Authorization: Token OAuth2 untuk pengguna yang memiliki akses ke Partner.
• developer-token: Token developer untuk aplikasi API, yang biasanya terkait dengan Partner.
• login-customer-id: ID Pelanggan Partner. Pengguna yang diautentikasi harus memiliki akses ke akun ini.
• linked-customer-id: ID Pelanggan Akun tertaut. Header ini menandakan bahwa otorisasi untuk permintaan ini bergantung pada link produk Akun tertaut dengan Partner.

Ada dua skenario penautan:

• Jika Pengiklan memiliki link produk langsung dengan Partner, Akun tertaut adalah Pengiklan, dan linked-customer-id harus ditetapkan ke ID pelanggan Pengiklan.
• Jika Pengiklan dikelola oleh akun pengelola yang memiliki link produk dengan Partner, Akun tertaut adalah akun pengelola, dan linked-customer-id harus ditetapkan ke ID pelanggan pengelola.

Contoh 1: Link langsung

Jika Pengiklan 1111111111 memiliki link langsung dengan Partner 2222222222, dan panggilan API menargetkan customers/1111111111/...:

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

Contoh 2: Link pengelola

Jika Pengiklan 1111111111 dikelola oleh Pengelola 3333333333, Pengelola 3333333333 memiliki link dengan Partner 2222222222, dan panggilan API menargetkan customers/1111111111/...:

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

Header respons

Header berikut (atau grpc metadata akhir) ditampilkan dengan isi respons. Sebaiknya catat nilai ini untuk tujuan proses debug.

request-id

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