Kimlik doğrulama ve yetkilendirme

Diğer Google API'leri gibi Google Ads API de kimlik doğrulama ve yetkilendirme için OAuth 2.0 protokolünü kullanır. OAuth 2.0, Google Ads API istemci uygulamanızın, kullanıcının giriş bilgilerini işlemesine veya saklamasına gerek kalmadan kullanıcının Google Ads hesabına erişmesini sağlar.

Google Ads erişim modelini anlama

Google Ads API ile etkili bir şekilde çalışmak için Google Ads erişim modelinin nasıl çalıştığını anlamanız gerekir. Google Ads erişim modeli kılavuzunu inceleyin.

OAuth iş akışları

Google Ads API ile çalışırken kullanılan üç yaygın iş akışı vardır.

Hizmet hesabı akışı

İş akışınız insan etkileşimi gerektirmiyorsa önerilen iş akışı budur. Bu iş akışı, kullanıcının Google Ads hesabına bir hizmet hesabı eklediği bir yapılandırma adımı gerektirir. Uygulama daha sonra kullanıcının Google Ads hesabını yönetmek için hizmet hesabının kimlik bilgilerini kullanabilir. Bunu yapılandırmak için Google Cloud Console'da JSON anahtar dosyasını oluşturup indirin, ardından google_ads_config.rb dosyasını ana dizininize kopyalayın ve hizmet hesabı anahtar dosyanızın konumunu (ve Google Workspace alan genelinde yetki kullanılırken kimliğine bürünülecek kullanıcının isteğe bağlı e-posta adresini) belirtecek şekilde değiştirin:

# 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'

Bu bilgileri bir dosyada saklamak yerine ortam değişkenlerini kullanmayı tercih ediyorsanız GOOGLE_ADS_JSON_KEY_FILE_PATH (ve isteğe bağlı olarak GOOGLE_ADS_IMPERSONATED_EMAIL) değişkenini ayarlayabilirsiniz:

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"

Hizmet hesabı anahtar dosyası yolunu (ve isteğe bağlı olarak kimliğine bürünülen e-posta adresini) çalışma zamanında programatik olarak da iletebilirsiniz:

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

Alternatif olarak, hizmet hesabı kimlik bilgilerini oluşturmak için googleauth gem'ini kullanabilir ve credentials.updater_proc değerini config.authentication'ye iletebilirsiniz:

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

Daha fazla bilgi edinmek için hizmet hesabı iş akışı kılavuzuna bakın.

Tek kullanıcılı kimlik doğrulama akışı

Hizmet hesaplarını kullanamıyorsanız bu iş akışından yararlanabilirsiniz. Bu iş akışı için iki yapılandırma adımı gerekir:

  1. Google Ads API kullanılarak yönetilecek tüm hesaplara tek bir kullanıcıya erişim izni verin. Yaygın bir yaklaşım, kullanıcıya bir Google Ads API yönetici hesabına erişim vermek ve tüm Google Ads hesaplarını bu yönetici hesabına bağlamaktır.
  2. Kullanıcı, uygulamanıza tüm Google Ads hesaplarını kendi adına yönetme yetkisi vermek için Google Cloud komut satırı aracı veya GenerateUserCredentials kod örneği gibi bir komut satırı aracı çalıştırır.

OAuth 2.0 kimlik bilgileri, google_ads_config.rb dosyasını ana dizininize kopyalayıp istemci kimliğinizi, istemci gizli anahtarınızı ve yenileme jetonunuzu içerecek şekilde değiştirerek Ruby için yapılandırılabilir:

# 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'

İstemci, bağımsız değişken olmadan örneklendirilirse yapılandırma dosyasını ana dizinden otomatik olarak okur:

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

Alternatif olarak, dosyayı başka bir yerde depolamayı tercih ederseniz bu dosyanın bulunduğu yolu ileterek istemciyi örneklendirebilirsiniz:

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

Bu bilgileri bir dosyada saklamak yerine ortam değişkenlerini kullanmayı tercih ediyorsanız her birini ayarlayabilirsiniz:

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"

Bilgileri çalışma zamanında programatik olarak da iletebilirsiniz:

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

Daha fazla bilgi edinmek için tek kullanıcı kimlik doğrulama iş akışı kılavuzuna bakın.

Çok kullanıcılı kimlik doğrulama akışı

Uygulamanız, kullanıcıların oturum açmasına ve uygulamanızı kendi adlarına Google Ads hesaplarını yönetmesi için yetkilendirmesine izin veriyorsa önerilen iş akışı budur. Uygulamanız, OAuth 2.0 kullanıcı kimlik bilgilerini oluşturur ve yönetir. Bu iş akışı, tek kullanıcılı akışa benzer şekilde yapılandırılabilir ve login_customer_id da belirtilir.

Yapılandırma dosyası kullanmanız önerilir. google_ads_config.rb dosyasını ana dizininize kopyalayın ve istemci kimliğinizi, istemci gizli anahtarınızı, yenileme jetonunuzu ve müşteri kimliğinizi içerecek şekilde değiştirin:

# 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'

İstemci, bağımsız değişken olmadan örneklendirilirse yapılandırma dosyasını ana dizinden otomatik olarak okur:

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

Alternatif olarak, dosyayı başka bir yerde depolamayı tercih ederseniz bu dosyanın bulunduğu yolu ileterek istemciyi örneklendirebilirsiniz:

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

Bu bilgileri bir dosyada saklamak yerine ortam değişkenlerini kullanmayı tercih ediyorsanız her birini ayarlayabilirsiniz:

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"

Bilgileri çalışma zamanında programatik olarak da iletebilirsiniz:

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

Daha fazla bilgi edinmek için çok kullanıcılı kimlik doğrulama iş akışı kılavuzuna bakın. Ruby istemci kitaplığında referans olarak kullanabileceğiniz bir kod örneği bulunur. GenerateUserCredentials komut satırı kodu örneği, kullanıcıların Google Ads hesaplarını onlar adına yönetmek için çalışma zamanında kullanıcı kimlik doğrulamasının nasıl alınacağını gösterir. Kullanıcı kimlik doğrulaması gerektiren masaüstü uygulamaları oluşturmak için bu kod örneğini referans olarak kullanabilirsiniz.

Birden çok hesabı yönetme

Kullanıcıların, hesaplara doğrudan erişim veya Google Ads yönetici hesabı aracılığıyla birden fazla Google Ads hesabını yönetmesi yaygın bir durumdur. Ruby istemci kitaplığı, bu tür durumların nasıl ele alınacağını gösteren aşağıdaki kod örneklerini sağlar:

  1. GetAccountHierarchy kod örneği, bir Google Ads yönetici hesabındaki tüm hesapların listesinin nasıl alınacağını gösterir.
  2. ListAccessibleCustomers kod örneği, bir kullanıcının doğrudan erişebildiği tüm hesapların listesinin nasıl alınacağını gösterir. Bu hesaplar daha sonra login_customer_id ayarı için geçerli değerler olarak kullanılabilir.

Uygulama varsayılan kimlik bilgileri

Ruby istemci kitaplığı (v36.1.0 ve sonraki sürümler), uygulama varsayılan kimlik bilgileri (ADC) ile kimlik doğrulamayı da destekler. Uygulama yapılandırmanızda OAuth 2.0 bilgilerini yapılandırmanıza gerek kalmadan uygulamanız için varsayılan kimlik bilgilerini ayarlamanıza olanak tanır.

Bu, özellikle yerel geliştirme veya farklı Google API'leri için geliştirme yaparken kullanışlıdır. Gerekli OAuth 2.0 kapsamlarına erişebildikleri sürece aynı kimlik bilgilerini yeniden kullanabilirsiniz.

Google Ads API için, uygulama varsayılan kimlik bilgilerinizin https://www.googleapis.com/auth/adwords OAuth 2.0 kapsamına erişebildiğinden emin olun.

Uygulama Varsayılan Kimlik Bilgileri'ni kullanmak için Google Cloud komut satırı aracını kullanın ve ADC için kimlik doğrulaması yapın:

gcloud auth application-default login

Bu komut, Google Hesabınızın kimlik doğrulama akışını tamamlamak için bir web tarayıcısı açar. Yetkilendirildikten sonra kimlik bilgilerini standart bir konumda depolar. Ardından, ADC'yi kullanmak için uygulamanızı güncellemeniz gerekir.

google_ads_config.rb dosyasını ana dizininize kopyalayın ve use_application_default_credentials değerini true olarak ayarlayın:

# 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

Bu bilgileri bir dosyada saklamak yerine ortam değişkenlerini kullanmayı tercih ediyorsanız GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS değerini ayarlayabilirsiniz:

export GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS="true"

Bilgileri çalışma zamanında programatik olarak da iletebilirsiniz. Ruby kodunuzda istemciyi ilk kullanıma hazırlarken config.use_application_default_credentials = true değerini ayarlayın ve açık OAuth 2.0 kimlik bilgileri sağlamayın. Kitaplık, Google Cloud komut satırı aracı tarafından ayarlanan kimlik bilgilerini otomatik olarak algılar ve kullanır:

# 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

Ruby istemci kitaplığını yapılandırmak için kullanabileceğiniz seçenekler hakkında daha fazla bilgi edinmek istiyorsanız yapılandırma sayfasını inceleyin.