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 token developer, kredensial OAuth 2.0, dan, dalam beberapa kasus, ID pelanggan login.

Token Developer

Token developer ditautkan ke akun pengelola dan dapat ditemukan di antarmuka web Google Ads.

Meskipun ditautkan ke akun pengelola, token developer tidak memberikan akses ke akun tersebut. Sebagai gantinya, token developer memberikan akses ke API secara umum, dan akses tingkat akun dikonfigurasi melalui OAuth 2.0.

Di library klien, token developer ditentukan oleh kunci api.googleads.developerToken dalam file ads.properties Anda.

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 berbeda-beda 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

Atau, tentukan ID pelanggan akun pengelola yang memberikan akses ke akun penayangan. Parameter 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 mereka. 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=PRIVATE_KEY_JSON_FILE_PATH
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
# Only add this key if you are using impersonation to access an account
# other than the service account itself.
# 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 memberikan akses pengguna ke akun pengelola Google Ads API, dan menautkan semua akun Google Ads di akun pengelola tersebut.
  2. Pengguna menjalankan alat command line seperti gcloud 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
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE

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

Alur autentikasi multi-pengguna

Alur kerja ini direkomendasikan jika aplikasi Anda memungkinkan pengguna login dan mengizinkan aplikasi Anda mengelola akun Google Ads mereka atas nama mereka. GenerateUserCredentials adalah contoh kode 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 yang memerlukan autentikasi pengguna.

Tambahkan baris 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
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE

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

Bagaimana jika pengguna saya 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 dapat diakses langsung oleh 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 pengembangan terhadap Google API yang berbeda, karena Anda dapat menggunakan kembali kredensial yang sama, asalkan kredensial tersebut dapat mengakses cakupan OAuth 2.0 yang benar.

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 Anda. Saat menggunakan kredensial default aplikasi, ID klien, rahasia klien, dan token refresh tidak boleh ditetapkan.