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. Mendeserialisasi 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 penggunaan REST.

ID resource

Objek di Google Ads API diakses menggunakan nama resource terstruktur dan ID gabungan.

Nama resource

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

ID Komposit

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

Misalnya, AdGroupAd memiliki pola nama resource customers/{customer_id}/adGroupAds/{ad_group_id}~{ad_id}. Karena ID gabungannya menggabungkan ID grup iklan induk (ad_group.id) dan ID iklan pokok (ad_group_ad.ad.id), kami menambahkan ID grup iklan ke ID iklan:

• AdGroupId dari 123 + ~ + AdId dari 45678 = grup iklan gabungan ID iklan dari 123~45678.

Header permintaan

Berikut adalah header HTTP (atau metadata gRPC) yang menyertai isi dalam permintaan:

Otorisasi

Anda harus menyertakan token akses OAuth 2.0 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 habis, 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. Jika project Google Cloud Anda hanya disetujui untuk akses Test dan Anda mengirim permintaan yang menargetkan akun produksi, API akan menampilkan AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION di v25 dan yang lebih baru (atau AuthorizationError.ACTION_NOT_PERMITTED di v24 dan yang lebih lama). Lihat Tingkat akses Google Ads untuk mengetahui detail tentang cara mengelola izin.

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 Anda 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. Untuk penjelasan mendetail tentang cara akses akun diselesaikan, lihat panduan model akses OAuth.

https://googleads.googleapis.com/v25/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, defaultnya adalah pelanggan yang beroperasi.

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 link produk yang sudah dibuat dengan Partner, sehingga Partner dapat mengakses Pengiklan.

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

Header permintaan harus ditetapkan sebagai berikut:

• Authorization: Token akses OAuth 2.0 untuk pengguna yang memiliki akses ke Partner.
• login-customer-id: ID pelanggan akun 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 mengandalkan penautan produk akun tertaut dengan Partner.

Ada dua skenario penautan:

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

Contoh 1: Link langsung

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

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

Contoh 2: Link pengelola

Jika akun Pengiklan 1111111111 dikelola oleh akun pengelola 3333333333, akun pengelola 3333333333 memiliki penautan dengan akun Partner 2222222222, dan panggilan API menargetkan customers/1111111111/...:

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

Header respons

Header berikut (atau gRPC trailing-metadata) ditampilkan dengan isi respons. Sebaiknya Anda mencatat nilai ini untuk tujuan pen-debug-an.

request-id

request-id adalah string yang secara unik mengidentifikasi permintaan ini. Berikan nilai ini saat menghubungi dukungan untuk membantu memecahkan masalah permintaan API yang gagal atau tidak terduga.