Kimlik Doğrulama ve Yetkilendirme

Google Ads API, diğer Google API'leri gibi 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şlemesi veya depolaması gerekmeden 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 okumanızı öneririz.

OAuth iş akışları

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

Hizmet hesabı akışı

İş akışınızda herhangi bir kullanıcı etkileşimi gerekmiyorsa bu iş akışını kullanmanız önerilir. Bu iş akışı, kullanıcının Google Ads hesabına 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 dosyası konumunuzu ve kimliğine bürünülecek kullanıcının 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'
  # c.impersonate = 'INSERT_EMAIL_ADDRESS_TO_IMPERSONATE_HERE'

Bu bilgileri bir dosyada depolamak yerine ortam değişkenlerini kullanmayı tercih ederseniz sırasıyla GOOGLE_ADS_JSON_KEY_FILE_PATH ve GOOGLE_ADS_IMPERSONATED_EMAIL değerlerini ayarlayabilirsiniz.

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

Ayrıca, çalışma zamanında bilgileri programatik olarak da iletebilirsiniz. Bunun için, hizmet hesabı JSON dosyasından kimlik bilgileri oluşturmak üzere googleauth gem'ini kullanın:

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

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ışını kullanabilirsiniz. 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ının erişmesini sağlayın. Genel bir yaklaşım, kullanıcıya bir Google Ads API yönetici hesabı vermek ve bu yönetici hesabı altındaki tüm Google Ads hesaplarını bağlamaktır.
  2. Kullanıcı, uygulamanızın kendi adına tüm Google Ads hesaplarını yönetmesini yetkilendirmek için gcloud gibi bir komut satırı aracı veya GenerateUserCredentials kod örneğini çalıştırır.

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

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

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

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

Alternatif olarak, dosyayı başka bir yerde saklamayı tercih ederseniz bu dosyanın yolunu ileterek istemciyi oluşturabilirsiniz:

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

Bu bilgileri bir dosyada depolamak yerine ortam değişkenlerini kullanmayı tercih ederseniz her birini ayarlayabilirsiniz:

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"

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

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

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

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

Uygulamanızın, kullanıcıların oturum açmasına ve Google Ads hesaplarını kendi adlarına yönetmek için uygulamanıza yetki vermesine izin veriyorsa bu iş akışını kullanmanız önerilir. 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 ancak login_customer_id da belirtilir.

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

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

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

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

Alternatif olarak, dosyayı başka bir yerde saklamayı tercih ederseniz bu dosyanın yolunu ileterek istemciyi oluşturabilirsiniz:

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

Bu bilgileri bir dosyada depolamak yerine ortam değişkenlerini kullanmayı tercih ederseniz her birini ayarlayabilirsiniz:

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"

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

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

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

Kullanıcım birden fazla hesap yönetiyorsa ne olur?

Kullanıcıların, hesaplara doğrudan erişerek veya bir Google Ads yönetici hesabı üzerinden 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ı altı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 LoginCustomerId ayarı için geçerli değerler olarak kullanılabilir.

Uygulama varsayılan kimlik bilgileri

Ruby istemci kitaplığı, 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'lerine karşı geliştirme için yararlıdır. Doğru OAuth 2.0 kapsamlarına erişebildikleri sürece aynı kimlik bilgilerini yeniden kullanabilirsiniz.

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

Uygulama varsayılan kimlik bilgilerini kullanmak için Google Cloud komut satırı aracını kullanmanızı ve ADC için kimlik doğrulama yapmanızı öneririz:

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 saklar. Ardından, ADC'yi kullanmak için uygulamanızı güncellemeniz gerekir.

Yapılandırma dosyası kullanmanızı öneririz. google_ads_config.rb dosyasını ana dizininize kopyalayın, ardından geliştirici jetonunuzu ekleyin ve use_application_default_credentials değerini true olarak ayarlayın:

  # 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

Bu bilgileri bir dosyada depolamak yerine ortam değişkenlerini kullanmayı tercih ederseniz GOOGLE_ADS_DEVELOPER_TOKEN ve GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS değerlerini ayarlayabilirsiniz:

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

Bilgileri çalışma zamanında programatik olarak da iletebilirsiniz. Ruby kodunuzda istemciyi başlatırken açık OAuth2 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. Yine de geliştirici jetonunuzu belirtmeniz gerekir.

# 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

Ruby istemci kitaplığını yapılandırmak için kullanılabilen seçenekler hakkında daha fazla bilgi edinmek üzere yapılandırma sayfasına bakın.