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

השגת הפניות לכל מחלקות הפרוטו השונות שנדרשות לשימוש ב-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 v23 version of GoogleAdsService will
# be returned.
client = GoogleAdsClient.load_from_storage(version="v23")
googleads_service = client.get_service("GoogleAdsService")

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

from google.ads.googleads.client import GoogleAdsClient

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

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

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

client = GoogleAdsClient.load_from_storage(version=v23)

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'>

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

ניהול גרסאות

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

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

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

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

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

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