אימות והרשאה

בדומה לממשקי 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 של המשתמש. ספריית Python מוגדרת באופן הבא:

• אם משתמשים בקובץ google-ads.yaml או במחרוזת YAML, מוסיפים את השורה הבאה להגדרה כדי להגדיר את הנתיב לקובץ ה-JSON של המפתח הפרטי בסביבה המקומית:

  json_key_file_path: JSON_KEY_FILE_PATH
  

  לאחר מכן מבצעים קריאה לשיטות load_from_storage או load_from_string:

  from google.ads.googleads.client import GoogleAdsClient
  client = GoogleAdsClient.load_from_storage()
  

• אם אתם משתמשים ב-dict כדי להגדיר את הספרייה, צריך לכלול את צמד מפתח/ערך הבא ולהפעיל את השיטה load_from_dict, ולהעביר את הגדרת dict:

  from google.ads.googleads.client import GoogleAdsClient
  
  configuration = {
    # ...
    "json_key_file_path": JSON_KEY_FILE_PATH
    # ...
  }
  
  client = GoogleAdsClient.load_from_dict(configuration)
  

• אם אתם משתמשים במשתני סביבה, מוסיפים את הערכים הבאים להגדרה או לסביבה של bash:

  export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH
  

  לאחר מכן מבצעים קריאה ל-load_from_env:

  from google.ads.googleads.client import GoogleAdsClient
  client = GoogleAdsClient.load_from_env()
    ```
  

אם אפשרות ההגדרה json_key_file_path מופיעה באחת משיטות ההגדרה האלה, והאפשרות json_key_file_path היא False או לא מוגדרת, הספרייה תאשר אוטומטית את השימוש בתהליך של חשבון השירות.use_application_default_credentials

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

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

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

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

2. המשתמש מריץ כלי כמו gcloud CLI או דוגמת הקוד generate_user_credentials כדי להעניק לאפליקציה הרשאה לנהל את כל חשבונות Google Ads שלו בשמו.

אפשר לאתחל את הספרייה באמצעות פרטי הכניסה של המשתמש ב-OAuth 2.0 באופן הבא:

אם משתמשים בכלי gcloud CLI (מומלץ)

1. פועלים לפי ההוראות במאמר יצירת פרטי כניסה כדי להגדיר Application Default Credentials (ADC) בסביבה המקומית.

2. מוסיפים את ההגדרה הבאה ל-google-ads.yaml או למחרוזת ה-YAML:

   use_application_default_credentials: true
   

   לאחר מכן מבצעים קריאה לשיטה load_from_storage או load_from_string:

   from google.ads.googleads.client import GoogleAdsClient
   client = GoogleAdsClient.load_from_storage()
   

   אם אתם משתמשים ב-dict כדי להגדיר את הספרייה, צריך לכלול את צמד מפתח/ערך הבא ולקרוא לשיטה load_from_dict:

   from google.ads.googleads.client import GoogleAdsClient
   
   configuration = {
     # ...
     "use_account_default_credentials": True
     # ...
   }
   
   client = GoogleAdsClient.load_from_dict(configuration)
   

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

   export GOOGLE_ADS_USE_ACCOUNT_DEFAULT_CREDENTIALS=true
   

   לאחר מכן מבצעים קריאה ל-load_from_env:

   from google.ads.googleads.client import GoogleAdsClient
   client = GoogleAdsClient.load_from_env()
   

אם אתם מטפלים ישירות בטוקנים של OAuth

1. פועלים לפי השלבים להגדרת פרויקט במסוף ומורידים את קובץ ה-JSON שכולל את מזהה הלקוח ואת הסוד של הלקוח בפרויקט.

2. משכפלים את ספריית הלקוח של Python למכונה ועוברים לספרייה שלה:

   $ git clone https://github.com/googleads/google-ads-python.git
   $ cd google-ads-python
   

3. מריצים את הדוגמה ומזינים נתיב מוחלט לקובץ ה-JSON שהורדתם בשלב 1:

   $ python examples/authentication/generate_user_credentials.py -c PATH_TO_CREDENTIALS_JSON
   

   בסיום, טוקן לרענון מודפס במסוף. מעתיקים אותו ושומרים אותו לשלב הבא.

4. כדי להגדיר את הספרייה, מוסיפים את ההגדרות הבאות להגדרה הרצויה:

   מוסיפים את ההגדרה הבאה ל-google-ads.yaml או למחרוזת ה-YAML:

   client_id: INSERT_OAUTH2_CLIENT_ID_HERE
   client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
   refresh_token: INSERT_REFRESH_TOKEN_HERE
   

   לאחר מכן מבצעים קריאה לשיטה load_from_storage או load_from_string:

   from google.ads.googleads.client import GoogleAdsClient
   client = GoogleAdsClient.load_from_storage()
   

   אם אתם משתמשים ב-dict כדי להגדיר את הספרייה, צריך לכלול את צמדי המפתח/ערך הבאים ולקרוא לשיטה load_from_dict:

   from google.ads.googleads.client import GoogleAdsClient
   
   configuration = {
     # ...
     "client_id": INSERT_OAUTH2_CLIENT_ID_HERE
     "client_secret": INSERT_OAUTH2_CLIENT_SECRET_HERE
     "refresh_token": INSERT_REFRESH_TOKEN_HERE
     # ...
   }
   
   client = GoogleAdsClient.load_from_dict(configuration)
   

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

   export GOOGLE_ADS_CLIENT_ID=INSERT_OAUTH2_CLIENT_ID_HERE
   export GOOGLE_ADS_CLIENT_SECRET=INSERT_OAUTH2_CLIENT_SECRET_HERE
   export GOOGLE_ADS_REFRESH_TOKEN=INSERT_REFRESH_TOKEN_HERE
   

   לאחר מכן מבצעים קריאה ל-load_from_env:

   from google.ads.googleads.client import GoogleAdsClient
   client = GoogleAdsClient.load_from_env()
   

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

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

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

dict הוא מנגנון ההגדרה הכי פשוט לשימוש כשמקבלים אישורים בזמן הריצה:

from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "client_id": client_id
  "client_secret": client_secret
  "refresh_token": refresh_token
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

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

אימות ידני

אפשר ליצור פרטי אימות בכל שיטה ולספק אותם ל-GoogleAdsClient באופן ידני על ידי יצירת מופע של מחלקת הלקוח ישירות. בהנחה שאובייקט פרטי הכניסה שאתם יוצרים הוא מופע של google.auth.credentials.Credentials, אתם יכולים להעביר אותו באופן הבא:

from google.ads.googleads.client import GoogleAdsClient
from google.auth import default

# This line retrieves ADCs from the environment. You can use any authentication
# approach as long as the `credentials` variable is an instance of
# `google.auth.credentials.Credentials`
credentials = default(scopes=["https://www.googleapis.com/auth/adwords"])

client = GoogleAdsClient(
  credentials=credentials,
  # ... insert remaining parameters
)

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

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

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