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.

Memahami model akses Google Ads

Untuk bekerja secara efektif dengan Google Ads API, pahami cara kerja model akses Google Ads. Lihat panduan model akses Google Ads.

Alur kerja OAuth

Ada tiga alur kerja umum yang digunakan saat menggunakan 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, yaitu pengguna menambahkan akun layanan ke akun Google Ads-nya. Kemudian, aplikasi dapat menggunakan kredensial akun layanan untuk mengelola akun Google Ads pengguna.

Berikut cara menyiapkan OAuth2 untuk akses API menggunakan kredensial Anda sendiri dengan akun layanan di library klien Perl:

  1. Membuat kredensial OAuth2:

    Ikuti petunjuk untuk membuat akun layanan dan file kunci JSON.

  2. Menyiapkan library klien:

    Tetapkan jalur JSON kunci pribadi (dan impersonatedEmail opsional jika menggunakan delegasi di seluruh domain Google Workspace) dalam konfigurasi Anda. Jika Anda menggunakan file googleads.properties, tambahkan kode berikut:

    jsonKeyFilePath=PRIVATE_KEY_FILE_PATH
# Optional unless using Google Workspace domain-wide delegation:
impersonatedEmail=IMPERSONATED_EMAIL
loginCustomerId=LOGIN_CUSTOMER_ID

    Jika Anda menggunakan variabel lingkungan, tambahkan hal berikut ke konfigurasi atau lingkungan Bash Anda:

    export GOOGLE_ADS_JSON_KEY_FILE_PATH=KEY_FILE_PATH
export GOOGLE_ADS_IMPERSONATED_EMAIL=\
IMPERSONATED_EMAIL
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

    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. Beri satu pengguna akses ke semua akun yang akan dikelola menggunakan Google Ads API. Pendekatan yang umum adalah memberi pengguna akses ke akun pengelola Google Ads API, dan menautkan semua akun Google Ads di akun pengelola tersebut.
  2. Pengguna menjalankan contoh kode generate_user_credentials.pl untuk mengizinkan aplikasi Anda mengelola semua akun Google Ads mereka atas nama mereka.

Langkah-langkah berikut menjalankan contoh kode interaktif, yang kemudian mengharuskan Anda memberikan input.

  1. Di terminal, jalankan contoh generate_user_credentials.pl di direktori examples. Anda dapat mengubah nilai INSERT_XXX_HERE dalam contoh sebelum menjalankan atau menggunakan argumen command line -client_id untuk client ID dan -client_secret untuk rahasia klien.

    perl generate_user_credentials.pl \
  -client_id OAUTH_CLIENT_ID \
  -client_secret OAUTH_CLIENT_SECRET

  2. Contoh kode ini akan meminta Anda untuk membuka URL tempat Anda harus mengizinkan aplikasi mengakses akun Google Ads atas nama Anda.

    Paste this url in your browser:
https://accounts.google.com/o/oauth2/v2/auth?response_type=code&access_type=offline...

    Buka URL di sesi browser pribadi atau jendela samaran. Login dengan Akun Google yang Anda gunakan untuk mengakses Google Ads. Biasanya, ini adalah akun email yang memiliki akses ke akun pengelola Google Ads yang berisi semua akun yang perlu Anda kelola dalam hierarki akunnya. Klik Continue di layar izin OAuth 2.0.

    Layar izin OAuth 2.0

    Anda akan dialihkan ke halaman dengan pesan yang menunjukkan bahwa otorisasi berhasil.

    Authorization code was successfully retrieved.

  3. Kembali ke konsol tempat Anda menjalankan contoh kode. Anda akan melihat bahwa contoh kode telah selesai dan menampilkan token refresh serta beberapa petunjuk, diikuti dengan petunjuk yang harus Anda ikuti untuk mengonfigurasi library klien:

    Replace the following keys and values in your googleads.properties
configuration file:

clientId=***********************apps.googleusercontent.com
clientSecret=****
refreshToken=****

  4. Tekan Ctrl + C untuk menghentikan proses. Kemudian, salin token refresh yang dihasilkan beserta client ID dan rahasia klien ke file googleads.properties Anda atau simpan di tempat lain untuk digunakan jika membuat instance library saat runtime.

Library dapat diinisialisasi menggunakan kredensial OAuth 2.0 pengguna dengan menetapkan hal berikut di googleads.properties:

clientId=OAUTH_CLIENT_ID
clientSecret=OAUTH_CLIENT_SECRET
refreshToken=REFRESH_TOKEN
loginCustomerId=LOGIN_CUSTOMER_ID

Atau, gunakan variabel lingkungan:

export GOOGLE_ADS_CLIENT_ID=OAUTH_CLIENT_ID
export GOOGLE_ADS_CLIENT_SECRET=OAUTH_CLIENT_SECRET
export GOOGLE_ADS_REFRESH_TOKEN=REFRESH_TOKEN
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

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

Alur autentikasi multi-pengguna

Ini adalah alur kerja yang direkomendasikan jika aplikasi Anda mengizinkan pengguna untuk login dan memberi otorisasi kepada aplikasi Anda untuk mengelola akun Google Ads mereka atas nama mereka. Aplikasi Anda membuat dan mengelola kredensial pengguna OAuth 2.0.

Untuk Perl, Anda biasanya akan menerapkan alur aplikasi web tempat aplikasi Anda menangani pengalihan OAuth 2.0 dan pengelolaan token. Pengguna melakukan autentikasi melalui aplikasi Anda, dan aplikasi Anda menyimpan serta menggunakan token refresh pengguna untuk melakukan panggilan API atas nama mereka.

Konfigurasi untuk menggunakan kredensial yang diperoleh sama dengan konfigurasi untuk alur autentikasi pengguna tunggal:

clientId=OAUTH_CLIENT_ID
clientSecret=OAUTH_CLIENT_SECRET
refreshToken=REFRESH_TOKEN
loginCustomerId=LOGIN_CUSTOMER_ID

Atau, gunakan variabel lingkungan:

export GOOGLE_ADS_CLIENT_ID=OAUTH_CLIENT_ID
export GOOGLE_ADS_CLIENT_SECRET=OAUTH_CLIENT_SECRET
export GOOGLE_ADS_REFRESH_TOKEN=REFRESH_TOKEN
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

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 Perl menyediakan contoh yang menggambarkan cara menangani kasus tersebut:

  1. Contoh get_account_hierarchy.pl menunjukkan cara mengambil daftar semua akun di akun pengelola Google Ads.
  2. Contoh list_accessible_customers.pl menunjukkan cara mengambil daftar semua akun yang dapat diakses langsung oleh pengguna. Akun ini kemudian dapat digunakan sebagai nilai yang valid untuk setelan loginCustomerId dalam file googleads.properties atau variabel lingkungan GOOGLE_ADS_LOGIN_CUSTOMER_ID.