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

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

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

from google.ads.googleads.client import GoogleAdsClient

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

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

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

client = GoogleAdsClient.load_from_storage(version=v20)

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

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

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

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

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

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