אימות והרשאה

כמו ממשקי Google API אחרים, Google Ads API משתמש בפרוטוקול OAuth 2.0 לאימות ולהרשאה. פרוטוקול OAuth 2.0 מאפשר לאפליקציית הלקוח של Google Ads API לגשת לחשבון Google Ads של המשתמש בלי לטפל בפרטי ההתחברות של המשתמש או לאחסן אותם.

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

למידע נוסף על מודל הגישה של Google Ads API, קראו את המדריך למודל הגישה של Google Ads.

פרטי כניסה

כדי לקבל גישה ל-Google Ads API, צריך פרטי כניסה ל-OAuth 2.0 ובמקרים מסוימים גם מספר לקוח לצורך התחברות.

פרטי כניסה של OAuth 2.0

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

הספרייה תומכת בשלושה תהליכים:

  • תהליך של חשבון שירות
  • תהליך אימות של משתמש יחיד
  • תהליך אימות של משתמשים מרובים

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

מספר הלקוח של חשבון ההתחברות

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

בספריית הלקוח, מספר הלקוח בפרופיל נכנס מצוין במפתח api.googleads.loginCustomerId בקובץ ads.properties.

הגדרות אישיות

אפשר להגדיר את ספריית הלקוח באמצעות קובץ ads.properties, משתני סביבה או באופן פרוגרמטי. המדריך הזה מתמקד בשימוש בקובץ ads.properties. במדריך להגדרה מפורטות כל האפשרויות.

אם משתמשים בקובץ ads.properties, צריך לשים אותו בספריית הבית: ~/ads.properties.

תהליכי עבודה של OAuth

יש שלושה תהליכי עבודה נפוצים כשעובדים עם Google Ads API.

תהליך של חשבון שירות

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

אחרי שקיבלתם את קובץ ה-JSON של המפתח הפרטי, הוסיפו את הקוד הבא לקובץ ads.properties:

api.googleads.serviceAccountSecretsPath=INSERT_PATH_TO_JSON_HERE
# Only add this key if you are using Google Workspace domain-wide delegation
# to impersonate a user who has access to the Google Ads account.
# api.googleads.serviceAccountUser=USER_EMAIL_TO_IMPERSONATE

למידע נוסף, קראו את המדריך לתהליך העבודה של חשבון שירות.

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

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

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

אחרי שמקבלים את פרטי הכניסה האלה, מוסיפים את הפרטים הבאים לקובץ ads.properties:

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE

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

תהליך אימות של משתמשים מרובים

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

באפליקציות עם משתמשים מרובים, צריך לשמור את מזהה הלקוח וסוד הלקוח של OAuth 2.0 של האפליקציה ב-ads.properties (או במאגר הגדרות אחר), ולשמור את טוקן הרענון של כל משתמש קצה באופן מאובטח במסד הנתונים של האפליקציה ולהעביר אותו באופן פרוגרמטי בזמן הריצה כשיוצרים את UserCredentials ואת GoogleAdsClient:

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE

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

ניהול חשבונות מרובים

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

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

Application Default Credentials

ספריית הלקוח של Java תומכת גם באימות באמצעות Application Default Credentials.

האפשרות הזו שימושית במיוחד לפיתוח מקומי או לפיתוח מול ממשקי Google API שונים, כי אפשר להשתמש שוב באותם פרטי כניסה, בתנאי שהם יכולים לגשת להיקפי ההרשאות הנדרשים של OAuth 2.0.

ב-Google Ads API, ודאו של-Application Default Credentials יש גישה להיקף ההרשאות של OAuth 2.0 ב-https://www.googleapis.com/auth/adwords.

כדי להשתמש ב-Application Default Credentials, צריך להגדיר את האפשרות api.googleads.useApplicationDefaultCredentials לערך true בקובץ ads.properties (או להפעיל את .enableApplicationDefaultCredentials() ב-GoogleAdsClient.newBuilder()). כשמשתמשים ב-Application Default Credentials, לא צריך להגדיר את מזהה הלקוח, סוד הלקוח וטוקן הרענון.