מקבלי שירותים וסוגים

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

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

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

דוגמה לשימוש בשיטה get_service כדי לאחזר מופע של לקוח GoogleAdsService.

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 v21 version of GoogleAdsService will
# be returned.
client = GoogleAdsClient.load_from_storage(version="v21")
googleads_service = client.get_service("GoogleAdsService")

דוגמה לשימוש בשיטה get_type כדי לאחזר מופע של Campaign.

from google.ads.googleads.client import GoogleAdsClient

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

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

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

client = GoogleAdsClient.load_from_storage(version=v21)

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 מתוחזקות בו-זמנית. יכול להיות שגרסה v21 היא הגרסה האחרונה, אבל עדיין אפשר לגשת לגרסאות קודמות עד שהן יצאו משימוש. הספרייה תכלול מחלקות נפרדות של הודעות פרוטו שמתאימות לכל גרסה פעילה של ה-API. כדי לגשת למחלקת הודעות לגרסה ספציפית, צריך לספק את פרמטר מילת המפתח version כשמפעילים לקוח, כדי שהמערכת תמיד תחזיר מופע מהגרסה הנתונה:

client = GoogleAdsService.load_from_storage(version="/google-ads/api/reference/rpc/v21/")
# The Campaign instance will be from the v21 version of the API.
campaign = client.get_type("Campaign")

אפשר גם לציין את הגרסה כשמפעילים את השיטות get_service ו-get_type. הפעולה הזו תשנה את הגרסה שצוינה כשמפעילים את הלקוח:

client = GoogleAdsService.load_from_storage()
# This will load the v21 version of the GoogleAdsService.
googleads_service = client.get_service(
    "GoogleAdsService", version="v21")

client = GoogleAdsService.load_from_storage(version="v21")
# This will load the v19 version of a Campaign.
campaign = client.get_type("Campaign", version="v19")

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