אימות והרשאה

בדומה לממשקי 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 ובמקרים מסוימים, מספר לקוח של חשבון כניסה.

קוד מפתח

קוד המפתח מקושר לחשבון ניהול ואפשר למצוא אותו בממשק האינטרנט של Google Ads.

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

בספריית הלקוח, טוקן המפתח למפתחים מצוין על ידי המפתח api.googleads.developerToken בקובץ ads.properties.

פרטי כניסה של 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=PRIVATE_KEY_JSON_FILE_PATH
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
# Only add this key if you are using impersonation to access an account
# other than the service account itself.
# api.googleads.serviceAccountUser=USER_EMAIL_TO_IMPERSONATE

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

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

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

  1. נותנים למשתמש יחיד גישה לכל החשבונות שמנוהלים באמצעות Google Ads API. גישה נפוצה היא לתת למשתמש גישה לחשבון ניהול ב-Google Ads API, ולקשר את כל חשבונות Google Ads לחשבון הניהול הזה.
  2. המשתמש מריץ כלי של שורת פקודה כמו gcloud או דוגמת הקוד של 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
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE

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

תהליך אימות של כמה משתמשים

זהו תהליך העבודה המומלץ אם האפליקציה מאפשרת למשתמשים להיכנס אליה ולתת לה הרשאה לנהל את חשבונות Google Ads שלהם בשמם. ‫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
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE

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

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

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

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

Application Default Credentials

ספריית הלקוח Java תומכת גם באימות באמצעות פרטי כניסה שמוגדרים כברירת מחדל באפליקציה.

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

ב-Google Ads API, צריך לוודא שלפרטי ברירת המחדל של האפליקציה יש גישה להיקף https://www.googleapis.com/auth/adwords OAuth 2.0.

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