אימות והרשאה

כמו ממשקי 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 של המפתח הפרטי בסביבה המקומית (יחד עם impersonated_email אופציונלי אם משתמשים בהקצאת הרשאות ברמת הדומיין):

  json_key_file_path: JSON_KEY_FILE_PATH
  # Optional: only set if using Google Workspace domain-wide delegation:
  # impersonated_email: IMPERSONATED_EMAIL
  

  לאחר מכן, קוראים ל-load_from_storage או ל-load_from_string:

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

• אם אתם משתמשים ב-dict כדי להגדיר את הספרייה, צריך לכלול את צמד המפתח/ערך הבא ולקרוא ל-method‏ 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
  

  ואז קוראים ל-method‏ load_from_env:

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

אם אפשרות ההגדרה json_key_file_path קיימת באחת משיטות ההגדרה האלה, האפשרות use_application_default_credentials היא False או לא מוגדרת, והמפתחות של פרטי הכניסה של משתמש OAuth (client_id,‏ client_secret ו-refresh_token) לא מוגדרים או מסומנים כהערה, הספרייה מאשרת באופן אוטומטי באמצעות תהליך חשבון השירות.

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

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

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

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

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

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

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

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 כדי להגדיר את הספרייה, צריך לכלול את צמד המפתח/ערך הבא ולקרוא ל-method‏ load_from_dict:

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

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

   export GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS=true
   

   ואז קוראים ל-method‏ 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 כדי להגדיר את הספרייה, צריך לכלול את צמדי המפתח/ערך הבאים ולקרוא ל-method‏ 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
   

   ואז קוראים ל-method‏ 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,
    use_proto_plus=True,
)

ניהול חשבונות מרובים

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

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