פונקציות לקבלת שירות וסוג

אחזור של קובצי עזר לכל מחלקות ה-proto השונות שנדרשות כדי להשתמש ב-API ב-Python יכול להיות מילולי, ודורש הבנה פנימית של ה-API או מעבר תכוף בין הקשרים כדי להפנות ל-protos או למסמכי התיעוד.

השיטות get_service ו-get_type של הלקוח

שתי ה-methods האלה מאפשרות לאחזר כל אובייקט של שירות או סוג ב-API. השיטה get_service משמשת לאחזור לקוחות של שירותים. get_type משמש לכל אובייקט אחר. מחלקות של לקוחות שירות מוגדרות בקוד בנתיב הגרסה google/ads/googleads/v*/services/, וכל הסוגים מוגדרים בקטגוריות האובייקטים השונות google/ads/googleads/v*/common|enums|errors|resources|services/types/. כל הקוד שמתחת לספריית הגרסה נוצר, ולכן מומלץ להשתמש בשיטות האלה במקום לייבא את האובייקטים ישירות, למקרה שהמבנה של בסיס הקוד ישתנה.

בדוגמה הבאה אפשר לראות איך משתמשים ב-method‏ get_service כדי לאחזר מכונה של הלקוח GoogleAdsService (או GoogleAdsServiceAsyncClient אסינכרוני ב-google-ads v28.4.0 ואילך, על ידי העברת is_async=True):

from google.ads.googleads.client import GoogleAdsClient

# "load_from_storage" loads your API credentials from disk so they
# can be used for service initialization. Providing the optional `version`
# parameter means that the v26 version of GoogleAdsService will
# be returned.
client = GoogleAdsClient.load_from_storage(version="v26")
googleads_service = client.get_service("GoogleAdsService")

# Supported in google-ads v28.4.0 and later: retrieve an async service client.
googleads_async_service = client.get_service("GoogleAdsService", is_async=True)

בדוגמה הבאה אפשר לראות איך משתמשים ב-method‏ get_type כדי לאחזר מופע של Campaign:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage(version="v26")
campaign = client.get_type("Campaign")

טיפוסים בני מנייה (enum)

אפשר להשתמש ב-method‏ get_type כדי לאחזר ערכי enum, אבל לכל מופע של GoogleAdsClient יש גם מאפיין enums שטוען באופן דינמי ערכי enum באמצעות אותו מנגנון כמו של ה-method‏ get_type. הממשק הזה פשוט יותר וקל יותר לקריאה מאשר שימוש ב-get_type:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage(version="v26")

campaign = client.get_type("Campaign")
campaign.status = client.enums.CampaignStatusEnum.PAUSED

שדות של אובייקטים מסוג Proto שהם טיפוסי enum מיוצגים ב-Python על ידי הסוג המובנה enum. זה אומר שאתם יכולים לקרוא את הערך של החבר ישירות. עבודה עם המכונה campaign מהדוגמה הקודמת ב-Python REPL:

>>> print(campaign.status)
CampaignStatus.PAUSED
>>> type(campaign.status)
<enum 'CampaignStatus'>
>>> print(campaign.status.value)
3

לפעמים כדאי לדעת את שם השדה שתואם לערך ה-enum. אפשר לגשת למידע הזה באמצעות המאפיין name:

>>> print(campaign.status.name)
'PAUSED'
>>> type(campaign.status.name)
<class 'str'>

האינטראקציה עם ערכי enum משתנה בהתאם להגדרה של use_proto_plus ל-true או ל-false. לפרטים על שני הממשקים, קראו את המסמכים בנושא הודעות protobuf.

ניהול גרסאות

כמה גרסאות של ה-API מתוחזקות בו-זמנית. ‫v26 היא הגרסה העדכנית, אבל עדיין אפשר לגשת לגרסאות קודמות עד שהן יבוטלו. הספרייה כוללת מחלקות נפרדות של הודעות proto שתואמות לכל גרסת API פעילה. כדי לגשת למחלקת הודעות של גרסה ספציפית, צריך לספק את הפרמטר של מילת המפתח version כשמאתחלים לקוח, כדי שהוא תמיד יחזיר מופע מהגרסה הנתונה:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage(version="v26")
# The Campaign instance will be from the v26 version of the API.
campaign = client.get_type("Campaign")

אם לא מציינים version כשמפעילים את הלקוח, אפשר לציין את הגרסה לכל קריאה כשקוראים לשיטות get_service ו-get_type (שימו לב שאם version מוגדר כשמפעילים את GoogleAdsClient, הוא מבטל כל ארגומנט של version שמועבר ל-get_service או ל-get_type):

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()
# This loads the v26 version of the GoogleAdsService.
googleads_service = client.get_service(
    "GoogleAdsService", version="v26"
)

# This loads a specific supported API version (such as v23) of a Campaign.
campaign = client.get_type("Campaign", version="v23")

אם לא צוין פרמטר של מילת מפתח version, הספרייה משתמשת כברירת מחדל בגרסת ה-API הגבוהה ביותר שנתמכת בחבילת google-ads המותקנת ("v26" בגרסה האחרונה). שימו לב: כדי לגשת לגרסאות משניות של ה-API (כמו v26.1), צריך להשתמש במחרוזת של הגרסה הראשית (version="v26"). רשימה מעודכנת של הגרסאות הזמינות האחרונות וגרסאות אחרות מופיעה בקטע הניווט הימני של מאמרי העזרה של ה-API.