כדי לדון במוצרים שלנו ולספק משוב עליהם, אתם יכולים להצטרף לערוץ הרשמי של Google Ads ב-Discord בשרת Google Advertising and Measurement Community.

דף זה תורגם על ידי Cloud Translation API.

אימות והרשאה

בדומה לממשקי 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 לספריית הבית ומשנים אותו כדי לציין את המיקום של קובץ המפתח של חשבון השירות ואת כתובת האימייל של המשתמש שאליו רוצים להתחזות:

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

אפשר גם להעביר את המידע באופן פרוגרמטי בזמן הריצה, באמצעות ה-gem‏ googleauth כדי ליצור פרטי כניסה מקובץ 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

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

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

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

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

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

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

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

מידע נוסף זמין במדריך לתהליך העבודה של אימות משתמשים מרובים. ספריית הלקוח של Ruby כוללת קוד לדוגמה לעיון. ‫GenerateUserCredentials הוא דוגמה לקוד בשורת הפקודה שממחישה איך לקבל אימות משתמש בזמן ריצה כדי לנהל את חשבונות Google Ads שלו בשמו. אפשר להשתמש בדוגמת הקוד הזו כהפניה ליצירת אפליקציות למחשב שדורשות אימות משתמש.

מה קורה אם המשתמש מנהל כמה חשבונות?

בדרך כלל משתמש מנהל יותר מחשבון Google Ads אחד, או באמצעות גישה ישירה לחשבונות או באמצעות חשבון ניהול ב-Google Ads. ספריית הלקוח של Ruby כוללת את דוגמאות הקוד הבאות שממחישות איך לטפל במקרים כאלה.

בדוגמת הקוד GetAccountHierarchy מוסבר איך לאחזר את רשימת כל החשבונות שמשויכים לחשבון ניהול ב-Google Ads.
בדוגמת הקוד ListAccessibleCustomers מוצג אופן האחזור של רשימת כל החשבונות שלמשתמש יש גישה ישירה אליהם. אפשר להשתמש בחשבונות האלה כערכים תקינים להגדרה LoginCustomerId.

Application Default Credentials

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

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

  # 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

פרטים נוספים על האפשרויות הזמינות להגדרת ספריית הלקוח של Ruby מופיעים בדף ההגדרה.

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