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, Anda harus memahami cara kerja model akses Google Ads. Sebaiknya baca panduan model akses Google Ads.

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.

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

  1. Buat kredensial OAuth2:

    Ikuti petunjuk untuk membuat akun layanan dan file *.JSON.

  2. Siapkan library klien:

    Tetapkan jalur JSON kunci pribadi dalam konfigurasi Anda. Jika Anda menggunakan file googleads.properties, tambahkan kode berikut:

    jsonKeyFilePath=PRIVATE_KEY_FILE_PATH

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

    export GOOGLE_ADS_JSON_KEY_FILE_PATH=PRIVATE_KEY_FILE_PATH

    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 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 ID klien dan -client_secret untuk rahasia klien.

    perl generate_user_credentials.pl -client_id {client_id} -client_secret {client_secret}

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

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

    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 Lanjutkan 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 bersama dengan ID klien dan rahasia klien ke file googleads.properties 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
developerToken=DEVELOPER_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_DEVELOPER_TOKEN=DEVELOPER_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

Alur kerja ini direkomendasikan jika aplikasi Anda memungkinkan pengguna login dan mengizinkan aplikasi Anda 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
developerToken=DEVELOPER_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_DEVELOPER_TOKEN=DEVELOPER_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 memberikan contoh yang menunjukkan cara menangani kasus tersebut.

  1. Contoh get_account_hierarchy.pl menunjukkan cara mengambil daftar semua akun dalam akun pengelola Google Ads.
  2. Contoh list_accessible_customers.pl menunjukkan cara mengambil daftar semua akun yang memiliki akses langsung 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.