אימות והרשאה

בדומה לממשקי 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 עם המפתח הפרטי בהגדרות. אם אתם משתמשים בקובץ googleads.properties, מוסיפים את השורות הבאות:

   jsonKeyFilePath=PRIVATE_KEY_FILE_PATH
   

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

   export GOOGLE_ADS_JSON_KEY_FILE_PATH=PRIVATE_KEY_FILE_PATH
   

   נקודה חשובה: כשמטעינים הגדרות, הספרייה מחפשת קודם פרטי כניסה מתוך תהליכי 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 {client_id} -client_secret {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&client_id=...
   

   עוברים לכתובת ה-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
developerToken=DEVELOPER_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_DEVELOPER_TOKEN=DEVELOPER_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
developerToken=DEVELOPER_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_DEVELOPER_TOKEN=DEVELOPER_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.