אימות והרשאה

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