הצטרפו אלינו בשידור חי ב-Discord בשרת של קהילת הפרסום והמדידה של Google וב-YouTube ב-15 באוקטובר בשעה 10:00 (שעון החוף המזרחי של ארה"ב). נדבר על התכונות החדשות שנוספו בגרסה 26 של Google Ads API.

‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

אימות והרשאה

בדומה לממשקי Google API אחרים, Google Ads 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

מידע נוסף מופיע במדריך לתהליך העבודה עם חשבונות שירות.

תהליך אימות של משתמש יחיד

אפשר להשתמש בתהליך העבודה הזה אם אין לכם אפשרות להשתמש בחשבונות שירות. תהליך העבודה הזה מחייב שני שלבי הגדרה:

מעניקים למשתמש יחיד גישה לכל החשבונות שמנוהלים באמצעות Google Ads API. גישה נפוצה היא לתת למשתמש גישה לחשבון ניהול ב-Google Ads API ולקשר את כל חשבונות Google Ads לחשבון הניהול הזה.
המשתמש מריץ כלי של שורת פקודה, כמו כלי שורת הפקודה של Google Cloud או דוגמת הקוד של GenerateUserCredentials, כדי להעניק לאפליקציה שלכם הרשאה לנהל בשמו את כל החשבונות שלו ב-Google Ads.

אפשר להגדיר את פרטי הכניסה של OAuth 2.0 עבור Ruby על ידי העתקת הקובץ 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'

הלקוח קורא באופן אוטומטי את קובץ ההגדרות מהספרייה הראשית אם הוא מופעל ללא ארגומנטים:

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.

Application Default Credentials

ספריית הלקוח של Ruby (גרסה 36.1.0 ואילך) תומכת גם באימות באמצעות Application Default Credentials ‏ (ADC). היא מאפשרת להגדיר את פרטי ברירת המחדל של האפליקציה בלי להגדיר את פרטי OAuth 2.0 בהגדרת האפליקציה.

השיטה הזו שימושית במיוחד לפיתוח מקומי או לפיתוח מול ממשקי Google API שונים, כי אפשר לעשות שימוש חוזר באותם פרטי כניסה, בתנאי שיש להם גישה להיקפי ההרשאות הנדרשים של 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.