אימות והרשאה

כמו ממשקי 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 של המשתמש.

כך מגדירים את OAuth2 לגישה ל-API באמצעות פרטי הכניסה שלכם עם חשבון שירות בספריית הלקוח של Perl:

1. יצירת פרטי כניסה של OAuth2:

   פועלים לפי ההוראות ליצירת חשבון שירות וקובץ מפתח JSON.

2. מגדירים את ספריית הלקוח:

   מגדירים את הנתיב של מפתח פרטי מסוג JSON (ואת impersonatedEmail האופציונלי אם משתמשים בהענקת הרשאות ברמת הדומיין ב-Google Workspace) בהגדרה. אם אתם משתמשים בקובץ googleads.properties, הוסיפו את הקוד הבא:

   jsonKeyFilePath=PRIVATE_KEY_FILE_PATH
   # Optional unless using Google Workspace domain-wide delegation:
   impersonatedEmail=IMPERSONATED_EMAIL
   loginCustomerId=LOGIN_CUSTOMER_ID
   

   אם אתם משתמשים במשתני סביבה, הוסיפו את הקוד הבא להגדרות או לסביבה של Bash:

   export GOOGLE_ADS_JSON_KEY_FILE_PATH=KEY_FILE_PATH
   export GOOGLE_ADS_IMPERSONATED_EMAIL=\
   IMPERSONATED_EMAIL
   export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID
   

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

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

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

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

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

בשלבים הבאים מריצים דוגמה של קוד אינטראקטיבי, שבה צריך לספק קלט.

1. במסוף, מריצים את הדוגמה generate_user_credentials.pl בספרייה examples. אפשר לשנות את הערכים של INSERT_XXX_HERE בדוגמה לפני שמריצים אותה, או להשתמש בארגומנטים של שורת הפקודה -client_id למזהה הלקוח ו--client_secret לסוד הלקוח.

   perl generate_user_credentials.pl \
     -client_id OAUTH_CLIENT_ID \
     -client_secret OAUTH_CLIENT_SECRET
   

2. דוגמת הקוד הזו מבקשת מכם להיכנס לכתובת URL שבה אתם צריכים לאשר לאפליקציה לגשת לחשבון Google Ads בשמכם.

   Paste this url in your browser:
   https://accounts.google.com/o/oauth2/v2/auth?response_type=code&access_type=offline...
   

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

   

   תועברו לדף עם הודעה שההרשאה בוצעה בהצלחה.

   Authorization code was successfully retrieved.
   

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

   Replace the following keys and values in your googleads.properties
   configuration file:
   
   clientId=***********************apps.googleusercontent.com
   clientSecret=****
   refreshToken=****
   

4. כדי לסיים את התהליך, לוחצים על Ctrl + C. אחר כך מעתיקים את אסימון הרענון שנוצר, יחד עם מזהה הלקוח וסוד הלקוח, לקובץ googleads.properties או שומרים אותו במקום אחר כדי להשתמש בו אם יוצרים מופע של הספרייה בזמן הריצה.

אפשר להפעיל את הספרייה באמצעות פרטי הכניסה של המשתמש ב-OAuth 2.0 על ידי הגדרת הערכים הבאים ב-googleads.properties:

clientId=OAUTH_CLIENT_ID
clientSecret=OAUTH_CLIENT_SECRET
refreshToken=REFRESH_TOKEN
loginCustomerId=LOGIN_CUSTOMER_ID

לחלופין, אפשר להשתמש במשתני סביבה:

export GOOGLE_ADS_CLIENT_ID=OAUTH_CLIENT_ID
export GOOGLE_ADS_CLIENT_SECRET=OAUTH_CLIENT_SECRET
export GOOGLE_ADS_REFRESH_TOKEN=REFRESH_TOKEN
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

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

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

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

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

ההגדרה לשימוש בפרטי הכניסה שהתקבלו זהה להגדרה של תהליך האימות למשתמש יחיד:

clientId=OAUTH_CLIENT_ID
clientSecret=OAUTH_CLIENT_SECRET
refreshToken=REFRESH_TOKEN
loginCustomerId=LOGIN_CUSTOMER_ID

אפשרות אחרת היא להשתמש במשתני סביבה:

export GOOGLE_ADS_CLIENT_ID=OAUTH_CLIENT_ID
export GOOGLE_ADS_CLIENT_SECRET=OAUTH_CLIENT_SECRET
export GOOGLE_ADS_REFRESH_TOKEN=REFRESH_TOKEN
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

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

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

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

1. בדוגמה get_account_hierarchy.pl מוסבר איך לאחזר את רשימת כל החשבונות שמשויכים לחשבון ניהול ב-Google Ads.
2. בדוגמה list_accessible_customers.pl מוסבר איך לאחזר את רשימת כל החשבונות שלמשתמש יש גישה ישירה אליהם. אפשר להשתמש בחשבונות האלה כערכים חוקיים להגדרה loginCustomerId בקובץ googleads.properties או למשתנה הסביבה GOOGLE_ADS_LOGIN_CUSTOMER_ID.