در ۱۵ اکتبر ساعت ۱۰:۰۰ صبح به‌وقت منطقه زمانی شرقی، در Discord در سرور «انجمن تبلیغات و سنجش Google» و در YouTube به‌صورت زنده به ما بپیوندید! درباره ویژگی‌های جدید اضافه شده در نسخه ۲۶ «میانای برنامه‌سازی کاربردی Google Ads» بحث خواهیم کرد.

‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

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

مانند دیگر «میاناهای برنامه‌سازی کاربردی Google»، «میانای برنامه‌سازی کاربردی Google Ads» از پروتکل OAuth 2.0 برای اصالت‌سنجی و صدور مجوز استفاده می‌کند. ‫OAuth 2.0 به برنامه کارخواه «میانای برنامه‌سازی کاربردی Google Ads» شما امکان می‌دهد بدون نیاز به مدیریت یا ذخیره اطلاعات ورود به سیستم کاربر، به حساب 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

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

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

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

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

با کپی کردن فایل google_ads_config.rb در دایرکتوری خانه و تغییر دادن آن برای افزودن شناسه کارخواه، رمز کارخواه، و رمز بازآوری، می‌توانید اطلاعات اعتباری OAuth 2.0 را برای 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 نمونه‌های کد زیر را ارائه می‌دهد که نحوه مدیریت چنین مواردی را نشان می‌دهد:

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

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

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

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

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

برای استفاده از اعتبارنامه‌های پیش‌فرض برنامه، از ابزار خط فرمان 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، به صفحه پیکربندی مراجعه کنید.