احراز هویت و مجوز

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

مدل دسترسی به گوگل ادز را درک کنید

برای کار مؤثر با API گوگل ادز، باید نحوه‌ی عملکرد مدل دسترسی گوگل ادز را درک کنید. توصیه می‌کنیم راهنمای مدل دسترسی گوگل ادز را مطالعه کنید.

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

سه گردش کار رایج هنگام کار با API گوگل ادز وجود دارد.

جریان حساب خدمات

اگر گردش کار شما نیازی به تعامل انسانی ندارد، این گردش کار توصیه می‌شود. این گردش کار نیاز به یک مرحله پیکربندی دارد که در آن کاربر یک حساب سرویس به حساب Google Ads خود اضافه می‌کند. سپس برنامه می‌تواند از اعتبارنامه‌های حساب سرویس برای مدیریت حساب Google Ads کاربر استفاده کند. برای پیکربندی این، فایل کلید JSON را در کنسول Google Cloud ایجاد و دانلود کنید، سپس google_ads_config.rb را در دایرکتوری خانگی خود کپی کنید و آن را تغییر دهید تا محل فایل کلید حساب سرویس و آدرس ایمیل کاربر برای جعل هویت مشخص شود:

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

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

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

همچنین می‌توانید اطلاعات را به صورت برنامه‌نویسی شده در زمان اجرا، با استفاده از googleauth gem برای ایجاد اعتبارنامه‌ها از یک فایل JSON حساب کاربری سرویس، ارسال کنید:

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

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

جریان احراز هویت تک کاربره

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

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

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

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

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

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

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

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

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

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"

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

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

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

جریان احراز هویت چند کاربره

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

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

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

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

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

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

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

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

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"

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

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

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

اگر کاربر من چندین حساب کاربری را مدیریت کند، چه می‌شود؟

رایج است که یک کاربر بیش از یک حساب گوگل ادز را مدیریت کند، چه از طریق دسترسی مستقیم به حساب‌ها و چه از طریق یک حساب مدیریت گوگل ادز. کتابخانه کلاینت روبی نمونه‌های کد زیر را ارائه می‌دهد که نحوه مدیریت چنین مواردی را نشان می‌دهد.

  1. مثال کد GetAccountHierarchy نحوه بازیابی لیست همه حساب‌های کاربری تحت یک حساب مدیریت تبلیغات گوگل (Google Ads manager) را نشان می‌دهد.
  2. مثال کد ListAccessibleCustomers نحوه بازیابی لیست تمام حساب‌هایی را که یک کاربر به آنها دسترسی مستقیم دارد، نشان می‌دهد. سپس می‌توان از این حساب‌ها به عنوان مقادیر معتبر برای تنظیم LoginCustomerId استفاده کرد.

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

کتابخانه کلاینت روبی همچنین از احراز هویت با اعتبارنامه‌های پیش‌فرض برنامه (ADC) پشتیبانی می‌کند. این کتابخانه به شما امکان می‌دهد اعتبارنامه‌های پیش‌فرض را برای برنامه خود تنظیم کنید، بدون اینکه نیازی به پیکربندی اطلاعات OAuth 2.0 در پیکربندی برنامه خود داشته باشید.

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

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

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

gcloud auth application-default login

این دستور یک مرورگر وب را برای تکمیل فرآیند احراز هویت حساب گوگل شما باز می‌کند. پس از تأیید، اعتبارنامه‌ها در یک مکان استاندارد ذخیره می‌شوند. سپس باید برنامه خود را برای استفاده از ADC به‌روزرسانی کنید.

توصیه می‌کنیم از یک فایل پیکربندی استفاده کنید. فایل google_ads_config.rb را در دایرکتوری خانگی خود کپی کنید، سپس توکن توسعه‌دهنده خود را اضافه کنید و use_application_default_credentials را روی true تنظیم کنید: 

  # 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

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

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

همچنین می‌توانید اطلاعات را به صورت برنامه‌نویسی شده در زمان اجرا ارسال کنید. هنگام مقداردهی اولیه کلاینت در کد Ruby خود، اعتبارنامه‌های OAuth2 صریح ارائه ندهید . کتابخانه به طور خودکار اعتبارنامه‌های تنظیم شده توسط ابزار خط فرمان Google Cloud را شناسایی و استفاده می‌کند. شما همچنان باید توکن توسعه‌دهنده خود را مشخص کنید. 

# 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

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