אפשרויות הגדרה

אפשר להגדיר את ספריית הלקוח של Python באמצעות קובץ YAML, משתני סביבה, מחרוזת YAML או dict.

הגדרת אימות

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

הגדרה באמצעות קובץ YAML

אתם יכולים לציין קובץ YAML שישמש לאתחול הלקוח, שמכיל את המידע הדרוש כדי לשלוח בקשות ל-Google Ads API. הגישה לקובץ הזה מתבצעת כשלקוח מאותחל באמצעות השיטה load_from_storage. הדרך הכי קלה ליצור את הקובץ הזה היא להעתיק את הדוגמה של google-ads.yaml מהמאגר ב-GitHub ולשנות אותה כך שתכלול את פרטי הכניסה שלכם, כולל טוקן הרענון, מזהה הלקוח וסוד הלקוח.

אם לא תציינו נתיב, הספרייה תחפש את הקובץ בספרייה $HOME:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()

כדי לציין את המיקום של הקובץ google-ads.yaml, אפשר להעביר את הנתיב כמחרוזת ל-method כשקוראים לה:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage("path/to/google-ads.yaml")

אפשר גם לציין את הנתיב על ידי הגדרת משתנה סביבה ספציפי:

import os
from google.ads.googleads.client import GoogleAdsClient

os.environ["GOOGLE_ADS_CONFIGURATION_FILE_PATH"] = "path/to/google-ads.yaml"
client = GoogleAdsClient.load_from_storage()

אם שני הערכים סופקו – נתיב הועבר ל-method ומשתנה הסביבה קיים – הספרייה נותנת עדיפות לנתיב שהועבר ל-method.

הגדרה באמצעות משתני סביבה

אתם יכולים לאחסן את כל הגדרות הלקוח כמשתני סביבה, שנקראים כשמשתמשים ב-method‏ load_from_env של הלקוח. משתני הסביבה צריכים להיות עם אותו שם כמו אלה שמוגדרים בקובץ google-ads.yaml, אבל הם חייבים להיות באותיות רישיות בלבד ועם הקידומת של מרחב השמות GOOGLE_ADS_. לדוגמה, צריך לאחסן את client_id בתור GOOGLE_ADS_CLIENT_ID.

משתני סביבה מוגדרים בדרך כלל בקובץ תצורה של bash, כמו קובץ .bashrc או .bash_profile שנמצא בספרייה $HOME. אפשר גם להגדיר אותם באמצעות שורת הפקודה.

הנה כמה שלבים בסיסיים להגדרת משתנה סביבה באמצעות קובץ .bashrc בטרמינל:

# Append the line "export GOOGLE_ADS_CLIENT_ID=1234567890" to
# the bottom of your .bashrc file.
echo "export GOOGLE_ADS_CLIENT_ID=1234567890" >> ~/.bashrc
# Update your bash environment to use the most recently updated
# version of your .bashrc file.
source ~/.bashrc

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

export GOOGLE_ADS_CLIENT_ID=1234567890
echo $GOOGLE_ADS_CLIENT_ID

ה-method‏ load_from_env טוענת נתוני הגדרה מהמאפיין environ במודול os המובנה של Python. לדוגמה: os.environ["GOOGLE_ADS_CLIENT_ID"]

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

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_env()

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

דוגמה להגדרה באמצעות קובץ .bashrc:

export GOOGLE_ADS_LOGGING='{
  "version": 1,
  "disable_existing_loggers": false,
  "formatters": {
    "default_fmt": {
      "format": "[%(asctime)s - %(levelname)s] %(message).5000s",
      "datefmt": "%Y-%m-%d %H:%M:%S"
    }
  },
  "handlers": {
    "default_handler": {
      "class": "logging.StreamHandler",
      "formatter": "default_fmt"
    }
  },
  "loggers": {
    "": {
      "handlers": ["default_handler"],
      "level": "INFO"
    }
  }
}'

נקודה חשובה: אם משתנה הסביבה GOOGLE_ADS_CONFIGURATION_FILE_PATH מוגדר כשקוראים ל-method‏ load_from_env, ערכי התצורה מאוחזרים מהקובץ google-ads.yaml שנמצא בנתיב שצוין, ולא ממשתני הסביבה שתוארו קודם.

הגדרה באמצעות מחרוזת YAML

אם קראתם קובץ YAML לזיכרון, אתם יכולים לספק אותו ישירות ללקוח בזמן האתחול. כדי לעשות את זה, משתמשים ב-method‏ load_from_string:

from google.ads.googleads.client import GoogleAdsClient

with open("/path/to/yaml", "r", encoding="utf-8") as handle:
    yaml_content = handle.read()

client = GoogleAdsClient.load_from_string(yaml_content)

הגדרה באמצעות dict

אפשר להעביר dict ישירות ל-method‏ load_from_dict. לדוגמה:

from google.ads.googleads.client import GoogleAdsClient

credentials = {
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "use_proto_plus": True,
}

client = GoogleAdsClient.load_from_dict(credentials)

שדות תצורה

ההגדרות של ספריית הלקוח תומכות בשדות הבאים.

אימות

צריך להשתמש רק באחת מקבוצות השדות האלה, בהתאם לגישת האימות שבה אתם משתמשים:

  • משתמש יחיד עם Application Default Credentials (מסמכי תיעוד)
    • ‫use_application_default_credentials: אם הספרייה צריכה להשתמש בפרטי כניסה של ברירת מחדל לאפליקציה (ADC) לצורך אימות (נתמך ב-google-ads v28.3.0 ואילך).
  • משתמש יחיד עם אסימוני OAuth (מסמכי תיעוד)
    • ‫client_id: מזהה הלקוח ב-OAuth.
    • ‫client_secret: סוד הלקוח ב-OAuth.
    • ‫refresh_token: טוקן הרענון של OAuth.
  • חשבון שירות (מאמרי עזרה)
    • ‫json_key_file_path: נתיב לקובץ מקומי של מפתח פרטי. הוא משמש לאימות באמצעות חשבון שירות.
    • ‫impersonated_email: כתובת אימייל אופציונלית של החשבון שרוצים להתחזות אליו כשמשתמשים בהענקת גישה ברמת הדומיין ב-Google Workspace.

התנהגות הספרייה

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

הגדרה ברמת הבקשה

משתני סביבה

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

  • GOOGLE_ADS_ADS_ASSISTANT
  • GOOGLE_ADS_CLIENT_ID
  • GOOGLE_ADS_CLIENT_SECRET
  • GOOGLE_ADS_CONFIGURATION_FILE_PATH
  • GOOGLE_ADS_ENDPOINT
  • GOOGLE_ADS_HTTP_PROXY
  • GOOGLE_ADS_IMPERSONATED_EMAIL
  • GOOGLE_ADS_JSON_KEY_FILE_PATH
  • GOOGLE_ADS_LINKED_CUSTOMER_ID
  • GOOGLE_ADS_LOGIN_CUSTOMER_ID
  • GOOGLE_ADS_LOGGING
  • GOOGLE_ADS_REFRESH_TOKEN
  • GOOGLE_ADS_USE_PROTO_PLUS
  • ‫GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS (נתמך בגרסה v28.3.0 ואילך)

הגדרת היומן

שדות של יומנים, שהם שדות מתחת לשדה התצורה logging, נגזרים ישירות מהמודול המובנה logging.config כי הספרייה מעבירה את כל השדות במרחב השמות logging ישירות ל-method‏ logging.config.dictConfig. פרטים מלאים מופיעים במדריך הרישום ביומן.

  • ‫version: ערך של מספר שלם שמייצג גרסת סכימה.
  • ‫disable_existing_loggers: אם צריך להשבית את כלי הרישום שהוגדרו במקום אחר באפליקציה.
  • ‫formatters: מילונים שמגדירים סוגים שונים של מעצבים.
  • ‫handlers: מילונים שמגדירים handlers שונים, שקובעים לאן נכתבים היומנים ובאילו formatters צריך להשתמש.
  • ‫loggers: מילונים שמגדירים סוגים שונים של רושמי יומנים, שכוללים handler ורמת יומן.