اصالت‌سنجی و مجوز

Google Ads API، مانند دیگر Google APIها، از پروتکل OAuth 2.0 برای اصالت‌سنجی و صدور مجوز استفاده می‌کند. OAuth 2.0 به برنامه کارخواه Google Ads API شما امکان می‌دهد بدون نیاز به مدیریت یا ذخیره اطلاعات ورود به سیستم کاربر، به حساب Google Ads کاربر دسترسی پیدا کند.

آشنایی با مدل دسترسی Google Ads

برای کار کردن مؤثر با Google Ads API، با نحوه عملکرد مدل دسترسی Google Ads آشنا شوید. به راهنمای مدل دسترسی Google Ads مراجعه کنید.

گردش‌های کار OAuth

سه گردش کار رایج وجود دارد که هنگام کار با Google Ads API استفاده می‌شود.

جریان حساب سرویس

اگر گردش کار شما به هیچ تعامل انسانی نیاز ندارد، این گردش کار توصیه می‌شود. این گردش کار به یک مرحله پیکربندی نیاز دارد که در آن کاربر یک حساب سرویس به حساب Google Ads خود اضافه می‌کند. سپس برنامه می‌تواند از اعتبارنامه حساب سرویس برای مدیریت حساب Google Ads کاربر استفاده کند. برای پیکربندی این مورد، فایل کلید JSON را در «کنسول Google Cloud» ایجاد و بارگیری کنید، سپس google_ads_config.rb را در پوشه اصلی‌تان کپی کنید و آن را اصلاح کنید تا مکان فایل کلید حساب سرویس شما (و نشانی ایمیل اختیاری کاربر برای جعل هویت هنگام استفاده از واگذاری در سطح دامنه 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'

اگر ترجیح می‌دهید این اطلاعات را در فایل ذخیره نکنید و می‌خواهید از متغیرهای محیطی استفاده کنید، می‌توانید GOOGLE_ADS_JSON_KEY_FILE_PATH (و GOOGLE_ADS_IMPERSONATED_EMAIL اختیاری) را تنظیم کنید:

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"

همچنین می‌توانید مسیر فایل کلید حساب سرویس (و ایمیل جعل هویت اختیاری) را به‌صورت برنامه‌نویسی‌شده در زمان اجرا ارسال کنید:

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

یا می‌توانید از gem googleauth برای ساختن اعتبارنامه‌های حساب سرویس استفاده کنید و credentials.updater_proc را به 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

برای کسب اطلاعات بیشتر، به راهنمای گردش کار حساب سرویس مراجعه کنید.

جریان اصالت‌سنجی تک‌کاربره

اگر نمی‌توانید از حساب‌های سرویس استفاده کنید، ممکن است از این گردش کار استفاده شود. این گردش کار به دو مرحله پیکربندی نیاز دارد:

  1. به یک کاربر امکان دسترسی به همه حساب‌هایی را بدهید که قرار است بااستفاده از Google Ads API مدیریت شوند. یک رویکرد رایج این است که به کاربر دسترسی به حساب مدیر Google Ads API داده شود و همه حساب‌های Google Ads تحت آن حساب مدیر پیوند داده شوند.
  2. کاربر ابزار خط فرمانی مثل ابزار خط فرمان Google Cloud یا نمونه کد GenerateUserCredentials را اجرا می‌کند تا به برنامه شما اجازه دهد همه حساب‌های Google Ads او را ازطرف او مدیریت کند.

اعتبارنامه OAuth 2.0 را می‌توان با کپی کردن فایل google_ads_config.rb در دایرکتوری اصلی و اصلاح آن برای گنجاندن شناسه کارخواه، رمز کارخواه، و ژتون بازآوری برای Ruby پیکربندی کرد:

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

اگر کارخواه بدون آرگومان نمونه‌سازی شود، به‌طور خودکار فایل پیکربندی را از فهرست راهنمای خانه می‌خواند:

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

یا اگر ترجیح می‌دهید فایل را در جای دیگری ذخیره کنید، می‌توانید با ارسال مسیر محل نگهداری این فایل، کلاینت را نمونه‌سازی کنید:

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

اگر ترجیح می‌دهید این اطلاعات را در فایل ذخیره نکنید و می‌خواهید از متغیرهای محیطی استفاده کنید، می‌توانید هرکدام را تنظیم کنید:

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"

همچنین می‌توانید اطلاعات را به‌صورت برنامه‌نویسی‌شده در زمان اجرا ارسال کنید:

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

برای کسب اطلاعات بیشتر، به راهنمای گردش کار اصالت‌سنجی تک‌کاربره مراجعه کنید.

جریان اصالت‌سنجی چندکاربره

اگر برنامه‌تان به کاربران اجازه می‌دهد به سیستم وارد شوند و به برنامه‌تان اجازه می‌دهند حساب‌های Google Ads آن‌ها را ازطرف آن‌ها مدیریت کند، این گردش کار توصیه می‌شود. برنامه شما اعتبارنامه‌های کاربر OAuth 2.0 را می‌سازد و مدیریت می‌کند. این گردش کار را می‌توان مشابه جریان تک‌کاربره پیکربندی کرد و login_customer_id را نیز مشخص کرد.

استفاده از فایل پیکربندی توصیه می‌شود. فایل google_ads_config.rb را در دایرکتوری خانه خود کپی کنید و آن را تغییر دهید تا شناسه کارخواه، رمز کارخواه، ژتون بازآوری، و شناسه مشتری شما را دربرگیرد:

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

اگر کارخواه بدون آرگومان نمونه‌سازی شود، به‌طور خودکار فایل پیکربندی را از فهرست راهنمای خانه می‌خواند:

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

یا اگر ترجیح می‌دهید فایل را در جای دیگری ذخیره کنید، می‌توانید با ارسال مسیر محل نگهداری این فایل، کلاینت را نمونه‌سازی کنید:

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

اگر ترجیح می‌دهید این اطلاعات را در فایل ذخیره نکنید و می‌خواهید از متغیرهای محیطی استفاده کنید، می‌توانید هرکدام را تنظیم کنید:

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"

همچنین می‌توانید اطلاعات را به‌صورت برنامه‌نویسی‌شده در زمان اجرا ارسال کنید:

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

برای کسب اطلاعات بیشتر، به راهنمای گردش کار اصالت‌سنجی چندکاربره مراجعه کنید. کتابخانه کارخواه Ruby شامل یک نمونه کد برای مرجع است. نمونه GenerateUserCredentials کد خط فرمان نشان می‌دهد که چگونه می‌توان اصالت‌سنجی کاربر را در زمان اجرا به‌دست آورد تا بتوان حساب‌های Google Ads او را ازطرف او مدیریت کرد. می‌توانید از این نمونه کد به‌عنوان مرجعی برای ساختن برنامه‌های رایانه‌ای که به اصالت‌سنجی کاربر نیاز دارند استفاده کنید.

مدیریت چند حساب

معمولاً کاربران بیش‌از یک حساب Google Ads را مدیریت می‌کنند، چه ازطریق دسترسی مستقیم به حساب‌ها و چه ازطریق حساب مدیر Google Ads. کتابخانه کارخواه Ruby نمونه کدهای زیر را ارائه می‌دهد که نحوه رسیدگی به چنین مواردی را نشان می‌دهد:

  1. نمونه کد GetAccountHierarchy نشان می‌دهد که چگونه می‌توان فهرست همه حساب‌های تحت یک حساب مدیر Google Ads را بازیابی کرد.
  2. نمونه کد ListAccessibleCustomers نشان می‌دهد که چگونه می‌توان فهرست همه حساب‌هایی را که کاربر دسترسی مستقیم به آن‌ها دارد بازیابی کرد. سپس می‌توان از این حساب‌ها به‌عنوان مقادیر معتبر برای تنظیم login_customer_id استفاده کرد.

اعتبارنامه‌های پیش‌فرض برنامه

کتابخانه کارخواه Ruby (نسخه ۳۶.۱.۰ و جدیدتر) از اصالت‌سنجی با اعتبارنامه پیش‌فرض برنامه (ADC) نیز پشتیبانی می‌کند. این ابزار به شما امکان می‌دهد اعتبارنامه‌های پیش‌فرض را برای برنامه‌تان تنظیم کنید، بدون اینکه نیاز باشد اطلاعات OAuth 2.0 را در پیکربندی برنامه‌تان پیکربندی کنید.

این به‌ویژه برای توسعه محلی یا توسعه دربرابر Google APIهای مختلف مفید است، زیرا می‌توانید از همان اعتبارنامه‌ها مجدداً استفاده کنید، مشروط بر اینکه بتوانند به دامنه‌های OAuth 2.0 موردنیاز دسترسی داشته باشند.

برای Google Ads API، مطمئن شوید اعتبارنامه‌های پیش‌فرض برنامه‌تان می‌تواند به https://www.googleapis.com/auth/adwords OAuth 2.0 scope دسترسی داشته باشد.

برای استفاده از اطلاعات کاربری پیش‌فرض برنامه، از ابزار خط فرمان Google Cloud استفاده کنید و برای ADC اصالت‌سنجی کنید:

gcloud auth application-default login

این فرمان مرورگر وبی را باز می‌کند تا جریان اصالت‌سنجی برای «حساب Google» شما تکمیل شود. پس‌از صدور مجوز، اعتبارنامه‌ها را در مکانی استاندارد ذخیره می‌کند. سپس باید برنامه‌تان را به‌روز کنید تا بتوانید از ADC استفاده کنید.

فایل google_ads_config.rb را در دایرکتوری خانه کپی کنید و use_application_default_credentials را روی 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

اگر ترجیح می‌دهید این اطلاعات را در فایل ذخیره نکنید و می‌خواهید از متغیرهای محیطی استفاده کنید، می‌توانید GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS را تنظیم کنید:

export GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS="true"

همچنین می‌توانید اطلاعات را به‌صورت برنامه‌نویسی‌شده در زمان اجرا ارسال کنید. وقتی کلاینت را در کد Ruby خود مقداردهی اولیه می‌کنید، config.use_application_default_credentials = true را تنظیم کنید و اعتبارنامه صریح OAuth 2.0 را ارائه نکنید. کتابخانه به‌طور خودکار اطلاعات اعتباری را که توسط ابزار خط فرمان 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

برای جزئیات بیشتر درباره گزینه‌های موجود برای پیکربندی کتابخانه کارخواه Ruby، به صفحه پیکربندی مراجعه کنید.