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

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

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

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

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

from google.ads.googleads.client import GoogleAdsClient

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

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

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

client = GoogleAdsClient.load_from_storage(version=v18)

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

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

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

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

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

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

ניהול גרסאות

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

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

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

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

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

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