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. Kemudian, aplikasi dapat menggunakan kredensial akun layanan untuk mengelola akun Google Ads pengguna. Untuk mengonfigurasi ini, buat dan download file kunci JSON di Konsol Google Cloud, lalu salin google_ads_config.rb ke direktori beranda Anda dan ubah untuk menentukan lokasi file kunci akun layanan dan alamat email pengguna yang akan ditiru:

  # 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'
  # c.impersonate = 'INSERT_EMAIL_ADDRESS_TO_IMPERSONATE_HERE'

Jika memilih untuk tidak menyimpan informasi ini dalam file dan lebih memilih menggunakan variabel lingkungan, Anda dapat menyetel GOOGLE_ADS_JSON_KEY_FILE_PATH dan GOOGLE_ADS_IMPERSONATED_EMAIL masing-masing.

export GOOGLE_ADS_JSON_KEY_FILE_PATH="/path/to/your/service-account-key.json"
export GOOGLE_ADS_IMPERSONATED_EMAIL="your_email@email.com"

Anda juga dapat meneruskan informasi secara terprogram saat runtime, dengan menggunakan gem googleauth untuk membuat kredensial dari file JSON akun layanan:

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 = Google::Auth::ServiceAccountCredentials.make_creds(
  json_key_io: File.open(key_file),
  scope: scopes
)

# Initialize the Google Ads API client with these credentials
client = Google::Ads::GoogleAds::Client.new do |config|
  config.developer_token = "YOUR_DEVELOPER_TOKEN"
  # Inject the service account credentials
  config.oauth2_client = credentials
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. 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 GenerateUserCredentials contoh kode 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 beranda Anda dan mengubahnya untuk menyertakan token developer, client ID, rahasia klien, dan token refresh Anda:

  # The developer token is required to authenticate that you are allowed to
  # make API calls.
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'

  # 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 beranda jika di-instantiate 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 tidak ingin menyimpan informasi ini dalam file dan lebih memilih menggunakan variabel lingkungan, Anda dapat menyetel masing-masing variabel tersebut:

export GOOGLE_ADS_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
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.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
  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

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

Sebaiknya gunakan file konfigurasi. Salin file google_ads_config.rb ke direktori beranda Anda dan ubah untuk menyertakan token developer, ID klien, secret klien, token refresh, dan ID pelanggan Anda:

  # The developer token is required to authenticate that you are allowed to
  # make API calls.
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'

  # 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 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 beranda jika di-instantiate 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 tidak ingin menyimpan informasi ini dalam file dan lebih memilih menggunakan variabel lingkungan, Anda dapat menyetel masing-masing variabel tersebut:

export GOOGLE_ADS_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
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.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
  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. GenerateUserCredentials adalah contoh kode command line yang 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 membangun aplikasi desktop yang memerlukan autentikasi pengguna.

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 Ruby menyediakan contoh kode berikut yang mengilustrasikan 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 Ruby juga mendukung autentikasi dengan kredensial default aplikasi (ADC). Dengan begitu, Anda dapat menetapkan kredensial default untuk aplikasi Anda, tanpa perlu mengonfigurasi informasi OAuth 2.0 dalam konfigurasi aplikasi Anda.

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, sebaiknya 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, kredensial akan disimpan di lokasi standar. Kemudian, Anda perlu mengupdate aplikasi untuk menggunakan ADC.

Sebaiknya gunakan file konfigurasi. Salin file google_ads_config.rb ke direktori beranda Anda, lalu tambahkan token developer dan tetapkan use_application_default_credentials ke benar (true):

  # The developer token is required to authenticate that you are allowed to
  # make API calls.
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'

  # 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 menggunakan variabel lingkungan, Anda dapat menyetel GOOGLE_ADS_DEVELOPER_TOKEN dan GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS:

export GOOGLE_ADS_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
export GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS="true"

Anda juga dapat meneruskan informasi secara terprogram saat runtime. Saat Anda menginisialisasi klien dalam kode Ruby, jangan berikan kredensial OAuth2 eksplisit. Library akan otomatis mendeteksi dan menggunakan kredensial yang disiapkan oleh alat command line Google Cloud. Anda tetap harus menentukan token developer.

# Initialize the client. It will automatically use Application Default Credentials.
client = Google::Ads::GoogleAds::Client.new do |config|
  # Developer Token is mandatory for the Google Ads API.
  config.developer_token = "YOUR_DEVELOPER_TOKEN"

  # 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 oauth2_client_id, oauth2_client_secret, or oauth2_refresh_token here.
end

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