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. Aplikasi kemudian dapat menggunakan kredensial akun layanan untuk mengelola akun Google Ads pengguna. Untuk mengonfigurasinya, buat dan download file kunci JSON di Konsol Google Cloud, lalu salin google_ads_config.rb ke direktori utama Anda dan ubah untuk menentukan lokasi file kunci akun layanan Anda (dan alamat email opsional pengguna yang akan ditiru identitasnya saat menggunakan delegasi di seluruh domain Google Workspace):

# You can also authenticate using a service account. If "keyfile" is
# specified below, then service account authentication will be assumed and
# the above authentication fields ignored. Read more about service account
# authentication here:
# https://developers.google.com/google-ads/api/docs/oauth/service-accounts
c.keyfile = 'path/to/keyfile.json'
# Optional unless using Google Workspace domain-wide delegation:
c.impersonate = 'INSERT_EMAIL_ADDRESS_TO_IMPERSONATE_HERE'

Jika Anda memilih untuk tidak menyimpan informasi ini dalam file dan lebih memilih untuk menggunakan variabel lingkungan, Anda dapat menetapkan GOOGLE_ADS_JSON_KEY_FILE_PATH (dan GOOGLE_ADS_IMPERSONATED_EMAIL opsional):

export GOOGLE_ADS_JSON_KEY_FILE_PATH="/path/to/your/service-account-key.json"
# Optional unless using Google Workspace domain-wide delegation:
export GOOGLE_ADS_IMPERSONATED_EMAIL="your_email@email.com"

Anda juga dapat meneruskan jalur file kunci akun layanan (dan email yang ditiru secara opsional) secara terprogram saat runtime:

require 'google/ads/google_ads'

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.keyfile = '/path/to/your/service-account-key.json'
  # Optional unless using Google Workspace domain-wide delegation:
  config.impersonate = 'INSERT_EMAIL_ADDRESS_TO_IMPERSONATE_HERE'
end

Atau, Anda dapat menggunakan gem googleauth untuk membuat kredensial akun layanan dan meneruskan credentials.updater_proc ke config.authentication:

require 'googleauth'
require 'google/ads/google_ads'

# Path to your service account key file.
key_file = '/path/to/your/service-account-key.json'

# Define the scopes needed for the Google Ads API.
scopes = ['https://www.googleapis.com/auth/adwords']

# Create service account credentials.
credentials = File.open(key_file) do |io|
  Google::Auth::ServiceAccountCredentials.make_creds(
    json_key_io: io,
    scope: scopes
  )
end

# Initialize the Google Ads API client with these credentials.
client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  # Inject the service account credential updater proc.
  config.authentication = credentials.updater_proc
end

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 alat command line seperti alat command line Google Cloud atau contoh kode GenerateUserCredentials untuk mengizinkan aplikasi Anda mengelola semua akun Google Ads mereka atas nama mereka.

Kredensial OAuth 2.0 dapat dikonfigurasi untuk Ruby dengan menyalin file google_ads_config.rb ke direktori utama Anda dan mengubahnya untuk menyertakan client ID, rahasia klien, dan token refresh:

# Authentication tells the API that you are allowed to make changes to the
# specific account you're trying to access.
# The default method of authentication is to use a refresh token, client id,
# and client secret to generate an access token.
c.client_id = 'INSERT_CLIENT_ID_HERE'
c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'

Klien akan otomatis membaca file konfigurasi dari direktori utama jika dibuat tanpa argumen:

client = Google::Ads::GoogleAds::GoogleAdsClient.new

Atau, jika Anda lebih suka menyimpan file di tempat lain, Anda dapat membuat instance klien dengan meneruskan jalur ke tempat Anda menyimpan file ini:

client = Google::Ads::GoogleAds::GoogleAdsClient.new(
  'path/to/google_ads_config.rb'
)

Jika Anda tidak ingin menyimpan informasi ini dalam file dan lebih memilih untuk menggunakan variabel lingkungan, Anda dapat menetapkan masing-masing variabel:

export GOOGLE_ADS_CLIENT_ID="INSERT_CLIENT_ID_HERE"
export GOOGLE_ADS_CLIENT_SECRET="INSERT_CLIENT_SECRET_HERE"
export GOOGLE_ADS_REFRESH_TOKEN="INSERT_REFRESH_TOKEN_HERE"

Anda juga dapat meneruskan informasi secara terprogram saat runtime:

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.client_id = 'INSERT_CLIENT_ID_HERE'
  config.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  config.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
end

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. Alur kerja ini dapat dikonfigurasi mirip dengan alur pengguna tunggal, dengan login_customer_id yang juga ditentukan.

Sebaiknya gunakan file konfigurasi. Salin file google_ads_config.rb ke direktori utama Anda dan ubah untuk menyertakan client ID, rahasia klien, token refresh, dan ID pelanggan:

# Authentication tells the API that you are allowed to make changes to the
# specific account you're trying to access.
# The default method of authentication is to use a refresh token, client id,
# and client secret to generate an access token.
c.client_id = 'INSERT_CLIENT_ID_HERE'
c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'

# Required for manager accounts only: Specify the login customer ID used to
# authenticate API calls. This will be the customer ID of the authenticated
# manager account. If you need to use different values for this field, then
# make sure to fetch a new copy of the service after each time you change the
# value.
c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'

Klien akan otomatis membaca file konfigurasi dari direktori utama jika dibuat tanpa argumen:

client = Google::Ads::GoogleAds::GoogleAdsClient.new

Atau, jika Anda lebih suka menyimpan file di tempat lain, Anda dapat membuat instance klien dengan meneruskan jalur ke tempat Anda menyimpan file ini:

client = Google::Ads::GoogleAds::GoogleAdsClient.new(
  'path/to/google_ads_config.rb'
)

Jika Anda tidak ingin menyimpan informasi ini dalam file dan lebih memilih untuk menggunakan variabel lingkungan, Anda dapat menetapkan masing-masing variabel:

export GOOGLE_ADS_CLIENT_ID="INSERT_CLIENT_ID_HERE"
export GOOGLE_ADS_CLIENT_SECRET="INSERT_CLIENT_SECRET_HERE"
export GOOGLE_ADS_REFRESH_TOKEN="INSERT_REFRESH_TOKEN_HERE"
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="INSERT_LOGIN_CUSTOMER_ID_HERE"

Anda juga dapat meneruskan informasi secara terprogram saat runtime:

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.client_id = 'INSERT_CLIENT_ID_HERE'
  config.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  config.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
  config.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
end

Lihat panduan alur kerja autentikasi multi-pengguna untuk mempelajari lebih lanjut. Library klien Ruby menyertakan contoh kode sebagai referensi. Contoh kode command line GenerateUserCredentials mengilustrasikan cara mendapatkan autentikasi pengguna saat runtime untuk mengelola akun Google Ads mereka atas nama mereka. Anda dapat menggunakan contoh kode ini sebagai referensi untuk membuat aplikasi desktop yang memerlukan autentikasi pengguna.

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

  1. Contoh kode GetAccountHierarchy menunjukkan cara mengambil daftar semua akun di 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 login_customer_id.

Kredensial Default Aplikasi

Library klien Ruby (v36.1.0 dan yang lebih baru) juga mendukung autentikasi dengan kredensial default aplikasi (ADC). Dengan library ini, Anda dapat menetapkan kredensial default untuk aplikasi tanpa perlu mengonfigurasi informasi OAuth 2.0 dalam konfigurasi 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, gunakan alat command line Google Cloud dan lakukan autentikasi untuk ADC:

gcloud auth application-default login

Perintah ini akan membuka browser web untuk menyelesaikan alur autentikasi untuk Akun Google Anda. Setelah diotorisasi, alat ini akan menyimpan kredensial di lokasi standar. Kemudian, Anda perlu mengupdate aplikasi untuk menggunakan ADC.

Salin file google_ads_config.rb ke direktori utama Anda, dan tetapkan use_application_default_credentials ke true:

# You can also authenticate using Application Default Credentials (ADC).
# To understand how ADC discovers credentials in a given environment, see:
# https://developers.google.com/identity/protocols/application-default-credentials
c.use_application_default_credentials = true

Jika Anda memilih untuk tidak menyimpan informasi ini dalam file dan lebih memilih untuk menggunakan variabel lingkungan, Anda dapat menetapkan GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS:

export GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS="true"

Anda juga dapat meneruskan informasi secara terprogram saat runtime. Saat Anda melakukan inisialisasi klien dalam kode Ruby, tetapkan config.use_application_default_credentials = true dan jangan berikan kredensial OAuth 2.0 eksplisit. Library ini otomatis mendeteksi dan menggunakan kredensial yang disiapkan oleh alat command line Google Cloud:

# Initialize the client using Application Default Credentials.
client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.use_application_default_credentials = true

  # Optional: Specify a login customer ID if you are accessing accounts
  # through a manager account.
  # config.login_customer_id = 'YOUR_LOGIN_CUSTOMER_ID'

  # Do NOT include client_id, client_secret, or refresh_token here.
end

Lihat halaman konfigurasi untuk mengetahui detail selengkapnya tentang opsi yang tersedia untuk mengonfigurasi library klien Ruby.