Otorisasi dan Header HTTP

Anda memerlukan kredensial OAuth 2.0 dan token developer saat memanggil Google Ads API. Jika melakukan panggilan API dengan akun pengelola Google Ads, Anda juga harus menentukan header login-customer-id dengan setiap permintaan. Halaman ini menjelaskan cara menetapkan nilai ini dan mendokumentasikan beberapa header HTTP khusus API tambahan yang dikirim dan diterima saat menggunakan antarmuka REST.

Kredensial OAuth 2.0

Google Ads API menggunakan OAuth 2.0 untuk mengotorisasi permintaan API. Alur autentikasi pengguna OAuth 2.0 user authentication flow dan service account flow didukung. Untuk mengetahui detail selengkapnya, lihat OAuth 2.0 di Google Ads API.

Jika baru menggunakan Google API, Anda dapat menggunakan gcloud CLI atau OAuth 2.0 Playground untuk bereksperimen dengan kredensial OAuth 2.0 dan Google Ads API sebelum menulis kode untuk aplikasi Anda.

Sebaiknya gunakan salah satu library OAuth 2.0 yang tersedia di https://oauth.net/code/ untuk menerapkan alur kerja otorisasi OAuth 2.0. Namun, kami telah mencantumkan petunjuk curl jika Anda perlu mengimplementasikannya sendiri.

Akun layanan

Ikuti langkah-langkah untuk mengonfigurasi project Google Cloud untuk Google Ads API. Catat email akun layanan dan kunci akun layanan. Selanjutnya, ikuti petunjuk umum di panduan Akun Layanan untuk menyiapkan akun layanan guna mengakses akun Google Ads Anda.

Autentikasi pengguna

Ikuti langkah-langkah untuk mengonfigurasi project Google Cloud Console untuk Google Ads API. Catat client ID dan rahasia klien. Selanjutnya, ikuti petunjuk alur aplikasi desktop atau petunjuk alur aplikasi web untuk membuat token refresh dan token akses. scope yang akan digunakan untuk akses Google Ads API adalah https://www.googleapis.com/auth/adwords.

Membuat token akses baru

Akun layanan

Jika Anda memiliki email akun layanan dan kunci akun layanan, ikuti panduan Menggunakan OAuth 2.0 untuk Server ke Server Aplikasi untuk membuat kumpulan klaim JWT, yang kemudian dapat ditukarkan untuk mendapatkan token akses OAuth 2.0. Pastikan untuk memilih tab HTTP/REST saat mengikuti panduan. scope OAuth 2.0 yang akan digunakan untuk akses Google Ads API adalah https://www.googleapis.com/auth/adwords. Selain itu, Anda dapat melewati parameter sub saat membuat kumpulan klaim JWT, karena langkah-langkah penyiapan memberikan akses langsung akun layanan ke akun Google Ads, sehingga tidak perlu meniru pengguna Google Ads.

Kemudian, gunakan token akses di header HTTP Authorization dari setiap panggilan API ke Google Ads API:

GET /v24/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

Autentikasi pengguna

Setelah memiliki client ID, rahasia klien, dan token refresh OAuth 2.0, Anda dapat membuat token akses baru untuk digunakan dalam panggilan API dengan alat command line curl:

curl \
  --data "grant_type=refresh_token" \
  --data "client_id=CLIENT_ID" \
  --data "client_secret=CLIENT_SECRET" \
  --data "refresh_token=REFRESH_TOKEN" \
  https://www.googleapis.com/oauth2/v3/token

Kemudian, gunakan token akses yang ditampilkan oleh permintaan curl di header HTTP Authorization dari setiap panggilan API ke Google Ads API:

GET /v24/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

Header permintaan

Bagian berikut menjelaskan header HTTP yang diperlukan atau digunakan saat membuat permintaan ke Google Ads API.

Token Developer

Google Ads API juga memerlukan token developer untuk melakukan panggilan ke API. Jika sudah memiliki token developer, Anda dapat menemukannya dengan membuka https://ads.google.com/aw/apicenter. Login ke akun pengelola Google Ads jika diminta. Jika Anda tidak memilikinya, ikuti petunjuk untuk mendaftar token developer.

Anda harus menyertakan nilai token developer di header HTTP developer-token dari setiap panggilan API ke Google Ads API:

GET /v24/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

ID pelanggan login

Untuk panggilan Google Ads API yang dilakukan oleh pengelola ke akun klien (yaitu, saat login sebagai pengelola untuk melakukan panggilan API ke salah satu akun kliennya), Anda juga harus memberikan header HTTP login-customer-id. Nilai ini mewakili ID pelanggan Google Ads dari pengelola yang melakukan panggilan API.

Menyertakan header ini sama dengan memilih akun di UI Google Ads setelah login atau mengklik gambar profil Anda di pojok kanan atas halaman. Saat menentukan ID pelanggan, pastikan untuk menghapus tanda hubung (—). Misalnya: 1234567890, bukan 123-456-7890. Lihat panduan model akses Google Ads untuk mempelajari ID pelanggan login lebih lanjut.

GET /v24/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
login-customer-id: MANAGER_CUSTOMER_ID

ID pelanggan tertaut

Header ID pelanggan tertaut hanya digunakan oleh [penyedia analisis aplikasi pihak ketiga saat mengupload konversi ke akun Google Ads tertaut. Lihat panduan Struktur Panggilan API untuk mengetahui detail selengkapnya.

...
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
login-customer-id: MANAGER_CUSTOMER_ID
linked-customer-id: LINKED_CUSTOMER_ID

Header respons

Header berikut ditampilkan dalam respons HTTP dari API.

ID Permintaan

request-id adalah string yang secara unik mengidentifikasi permintaan API. Saat men-debug atau memecahkan masalah dengan panggilan API tertentu, request-id adalah ID penting yang harus tersedia saat menghubungi dukungan developer Google.

request-id: 2a5Cj89VV7CNhya1DZjjrC
Sebelumnya
Ringkasan
Berikutnya
Desain antarmuka REST