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

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

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

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

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

כך משתמשים ב-method get_type כדי לאחזר מכונה של Campaign.

from google.ads.googleads.client import GoogleAdsClient

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

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

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

client = GoogleAdsClient.load_from_storage(version=v17)

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

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

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

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

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

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

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

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