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

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

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

בדוגמה הבאה אפשר לראות איך משתמשים ב-method‏ 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 v26 version of GoogleAdsService will
# be returned.
client = GoogleAdsClient.load_from_storage(version="v26")
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)

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

from google.ads.googleads.client import GoogleAdsClient

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

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

from google.ads.googleads.client import GoogleAdsClient

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

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

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