Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

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 menggunakan Google Ads API secara efektif, pahami cara kerja model akses Google Ads. Lihat 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-nya. Aplikasi kemudian dapat menggunakan kredensial akun layanan untuk mengelola akun Google Ads pengguna. Untuk mengonfigurasi hal ini, 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 di-impersonate 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 tidak ingin menyimpan informasi ini dalam file dan lebih memilih 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 identitasnya 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:

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

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

# 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 otomatis membaca file konfigurasi dari direktori beranda jika di-instansiasi 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 menetapkan setiap variabel tersebut:

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

Alur kerja ini direkomendasikan jika aplikasi Anda mengizinkan pengguna untuk 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 serupa dengan alur pengguna tunggal, 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 client ID, rahasia klien, token refresh, dan ID pelanggan Anda:

# 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 otomatis membaca file konfigurasi dari direktori beranda jika di-instansiasi 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 menetapkan setiap variabel tersebut:

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 membangun 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 mengilustrasikan cara menangani kasus tersebut:

Contoh kode GetAccountHierarchy menunjukkan cara mengambil daftar semua akun di akun pengelola Google Ads.
Contoh kode ListAccessibleCustomers menunjukkan cara mengambil daftar semua akun yang akses langsungnya dimiliki 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 demikian, 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 Akun Google Anda. Setelah diberi otorisasi, kredensial akan disimpan di lokasi standar. Kemudian, Anda perlu mengupdate aplikasi untuk menggunakan ADC.

Salin file google_ads_config.rb ke direktori utama Anda, lalu 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 tidak ingin menyimpan informasi ini dalam file dan lebih memilih 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 menginisialisasi klien dalam kode Ruby, tetapkan config.use_application_default_credentials = true dan jangan berikan kredensial OAuth 2.0 eksplisit. Library akan 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.