Autentikasi dan otorisasi

Seperti Google API lainnya, Google Ads API menggunakan protokol OAuth 2.0 untuk autentikasi dan otorisasi. OAuth 2.0 memungkinkan aplikasi klien Google Ads API Anda mengakses akun Google Ads pengguna tanpa harus menangani atau menyimpan info login pengguna.

Panduan ini membahas cara mengonfigurasi library klien Java untuk autentikasi Google Ads API menggunakan tiga alur OAuth 2.0 yang paling umum, serta menjelaskan kredensial yang diperlukan.

Untuk mempelajari model akses Google Ads API lebih lanjut, baca Panduan model akses Google Ads.

Kredensial

Akses ke Google Ads API memerlukan kredensial OAuth 2.0 dan, dalam beberapa kasus, ID pelanggan login.

Kredensial OAuth 2.0

Untuk memberikan otorisasi sebagai pengguna Akun Google dengan akses ke akun Google Ads, Anda harus memberikan serangkaian kredensial OAuth 2.0. Jenis kredensial yang diperlukan bervariasi bergantung pada alur OAuth 2.0 yang digunakan.

Library ini mendukung tiga alur:

  • Alur akun layanan
  • Alur autentikasi pengguna tunggal
  • Alur autentikasi multi-pengguna

Lihat ringkasan OAuth untuk mengetahui detail alur OAuth Google Ads API, dan ikuti petunjuk untuk alur yang paling sesuai dengan kebutuhan Anda guna mendapatkan kredensial yang diperlukan.

ID pelanggan login

Secara opsional, tentukan ID pelanggan akun pengelola yang memberikan akses ke akun penayangan. ID ini harus ditentukan jika akses Anda ke akun pelanggan dilakukan melalui akun pengelola. Anda tidak perlu menentukan semua akun pengelola di jalur ke ID pelanggan, cukup ID pengelola teratas yang Anda gunakan untuk izin akses. Untuk mengetahui detail selengkapnya, lihat dokumentasi terkait.

Di library klien, ID pelanggan login ditentukan oleh kunci api.googleads.loginCustomerId dalam file ads.properties Anda.

Konfigurasi

Anda dapat mengonfigurasi library klien dengan file ads.properties, variabel lingkungan, atau secara terprogram. Panduan ini berfokus pada penggunaan file ads.properties. Lihat Panduan konfigurasi untuk mengetahui detail semua opsi.

Jika menggunakan file ads.properties, tempatkan di direktori utama Anda: ~/ads.properties.

Alur kerja OAuth

Ada tiga alur kerja umum yang digunakan saat bekerja dengan Google Ads API.

Alur akun layanan

Ini adalah alur kerja yang direkomendasikan jika alur kerja Anda tidak memerlukan interaksi manusia. Alur kerja ini memerlukan langkah konfigurasi, di mana pengguna menambahkan akun layanan ke akun Google Ads-nya. Aplikasi kemudian dapat menggunakan kredensial akun layanan untuk mengelola akun Google Ads pengguna.

Setelah Anda memiliki file JSON kunci pribadi, tambahkan kode berikut ke file ads.properties Anda:

api.googleads.serviceAccountSecretsPath=INSERT_PATH_TO_JSON_HERE
# Only add this key if you are using Google Workspace domain-wide delegation
# to impersonate a user who has access to the Google Ads account.
# api.googleads.serviceAccountUser=USER_EMAIL_TO_IMPERSONATE

Lihat panduan alur kerja akun layanan untuk mempelajari lebih lanjut.

Alur autentikasi pengguna tunggal

Alur kerja ini dapat digunakan jika Anda tidak dapat menggunakan akun layanan. Alur kerja ini memerlukan dua langkah konfigurasi:

  1. Memberi satu pengguna akses ke semua akun yang akan dikelola menggunakan Google Ads API. Pendekatan umum adalah memberi pengguna akses ke akun pengelola Google Ads API dan menautkan semua akun Google Ads target di akun pengelola tersebut.
  2. Pengguna menjalankan alat command line seperti gcloud CLI atau contoh kode GenerateUserCredentials untuk memberi otorisasi aplikasi Anda agar dapat mengelola semua akun Google Ads mereka atas nama mereka.

Setelah Anda memiliki kredensial ini, tambahkan kode berikut ke file ads.properties Anda:

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE

Lihat panduan alur kerja autentikasi pengguna tunggal untuk mempelajari lebih lanjut.

Alur autentikasi multi-pengguna

Alur kerja ini direkomendasikan jika aplikasi Anda mengizinkan pengguna untuk login dan mengizinkan aplikasi Anda mengelola akun Google Ads mereka atas nama mereka. Contoh kode GenerateUserCredentials adalah alat command line yang menggambarkan cara mendapatkan autentikasi pengguna saat runtime untuk mengelola akun Google Ads mereka atas nama mereka. Anda dapat menggunakan contoh kode ini sebagai referensi untuk membangun aplikasi desktop atau web yang memerlukan autentikasi pengguna.

Untuk aplikasi multi-pengguna, simpan ID klien OAuth 2.0 dan rahasia klien aplikasi Anda di ads.properties (atau penyimpanan konfigurasi lain), sambil menyimpan token refresh setiap pengguna akhir dengan aman di database aplikasi Anda dan meneruskannya secara terprogram saat runtime saat membuat UserCredentials dan GoogleAdsClient:

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE

Lihat panduan alur kerja autentikasi multi-pengguna untuk mempelajari lebih lanjut.

Mengelola beberapa akun

Pengguna biasanya mengelola lebih dari satu akun Google Ads, baik melalui akses langsung ke akun, atau melalui akun pengelola Google Ads. Library klien Java menyediakan contoh kode berikut yang menggambarkan cara menangani kasus tersebut:

  1. Contoh kode GetAccountHierarchy menunjukkan cara mengambil daftar semua akun dalam akun pengelola Google Ads.
  2. Contoh kode ListAccessibleCustomers menunjukkan cara mengambil daftar semua akun yang memiliki akses langsung pengguna. Akun ini kemudian dapat digunakan sebagai nilai yang valid untuk setelan loginCustomerId.

Kredensial Default Aplikasi

Library klien Java juga mendukung autentikasi dengan Kredensial Default Aplikasi.

Hal ini sangat berguna untuk pengembangan lokal atau untuk pengembangan terhadap Google API yang berbeda, karena Anda dapat menggunakan kembali kredensial yang sama, asalkan kredensial tersebut dapat mengakses cakupan OAuth 2.0 yang diperlukan.

Untuk Google Ads API, pastikan Kredensial Default Aplikasi Anda dapat mengakses cakupan OAuth 2.0 https://www.googleapis.com/auth/adwords.

Untuk menggunakan Kredensial Default Aplikasi, tetapkan opsi api.googleads.useApplicationDefaultCredentials ke true dalam file ads.properties (atau panggil .enableApplicationDefaultCredentials() di GoogleAdsClient.newBuilder()). Saat menggunakan Kredensial Default Aplikasi, ID klien, secret klien, dan token refresh tidak boleh ditetapkan.