Struktur Panggilan API

Panduan ini menjelaskan struktur umum semua panggilan API.

Jika menggunakan library klien untuk berinteraksi dengan API, Anda tidak perlu mengetahui detail permintaan yang mendasarinya. Namun, beberapa pengetahuan tentang struktur panggilan API dapat berguna saat melakukan pengujian dan proses 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. Menginterpretasi hasil.

Sebagian besar dokumentasi kami menjelaskan cara menggunakan gRPC.

Opsional:

1. Buat isi permintaan sebagai objek JSON.

2. Kirim ke server menggunakan HTTP 1.1.

3. Mendeserialisasi respons sebagai objek JSON.

4. Menginterpretasi hasil.

Lihat panduan REST interface untuk mengetahui informasi selengkapnya tentang cara menggunakan REST.

Catatan: Panduan ini menjelaskan header struktur dan transport 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 REST API untuk mengetahui strukturnya.

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

ID Komposit

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

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

• AdGroupId dari 123 + ~ + AdGroupAdId dari 45678 = iklan komposit ID iklan grup iklan dari 123~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 mengelola akunnya sendiri secara langsung. 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 otomatis memperbarui token yang telah habis masa berlakunya.

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 cara mengelola 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 resmi yang akan digunakan dalam permintaan, tanpa tanda hubung (-). Jika akses Anda ke akun pelanggan melalui akun pengelola, header ini wajib dan harus disetel ke ID pelanggan akun pengelola. Jika Anda gagal menyertakan login-customer-id saat melakukan autentikasi melalui akun pengelola, hal ini akan menyebabkan error AuthorizationError.USER_PERMISSION_DENIED. Tinjau Error Umum untuk mengetahui informasi selengkapnya tentang jenis error ini.

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/v24/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, defaultnya adalah pelanggan yang beroperasi.

Catatan: Anda dapat mengambil daftar akun yang dapat diakses secara langsung dengan kredensial OAuth Anda dengan mengirimkan permintaan CustomerService.ListAccessibleCustomers. login-customer-id tidak diperlukan untuk jenis permintaan ini, dan tidak memengaruhi 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 atas akun Google Ads yang ditautkan. 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 penautan produk yang sudah dibuat dengan Partner, sehingga Partner dapat mengakses Pengiklan.

Pengguna yang memiliki akses ke Partner melakukan panggilan API untuk bertindak atas entitas 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, biasanya terkait dengan Partner.
• login-customer-id: ID Pelanggan Partner. Pengguna terautentikasi harus memiliki akses ke akun ini.
• linked-customer-id: ID Pelanggan Akun tertaut. Header ini menandakan bahwa otorisasi untuk permintaan ini mengandalkan penautan produk akun tertaut dengan Partner.

Ada dua skenario penautan:

• Jika Pengiklan memiliki link produk langsung dengan Partner, maka Akun tertaut adalah Pengiklan, dan linked-customer-id harus disetel ke ID pelanggan Pengiklan.
• Jika Pengiklan dikelola oleh akun pengelola yang memiliki penautan produk dengan Partner, maka Akun tertaut adalah akun pengelola, dan linked-customer-id harus disetel 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 tautan 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 trailing-metadata) akan ditampilkan dengan isi respons. Sebaiknya Anda mencatat nilai ini untuk tujuan penelusuran kesalahan.

request-id

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