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

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

השיטות של הלקוח 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/. כל הקוד שמתחת לספריית הגרסה נוצר, ולכן מומלץ להשתמש בשיטות האלה במקום לייבא את האובייקטים ישירות, למקרה שמבנה בסיס הקוד ישתנה.

בדוגמה הבאה מוצג אופן השימוש בשיטה 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 v25 version of GoogleAdsService will
# be returned.
client = GoogleAdsClient.load_from_storage(version="v25")
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)

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

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage(version="v25")
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="v25")

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

שדות של אובייקט Proto שהם enum מיוצגים ב-Python על ידי הסוג המובנה enum. כלומר, אפשר לקרוא את הערך של המאפיין member ישירות. עבודה עם מופע 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'>

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

ניהול גרסאות

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

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage(version="v25")
# The Campaign instance will be from the v25 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 v25 version of the GoogleAdsService.
googleads_service = client.get_service(
    "GoogleAdsService", version="v25"
)

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

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