واکشی ارجاع به تمام کلاس‌های پروتوی مختلف مورد نیاز برای استفاده از API در پایتون می‌تواند پرمخاطب باشد و شما را ملزم می‌کند که درک ذاتی از API یا سوئیچ متنی مکرر برای ارجاع پروتوها یا مستندات داشته باشید.
روش های get_service و get_type مشتری
این دو روش دریافت کننده به شما امکان می دهند هر سرویس یا شیء را در 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")
Enums
در حالی که می‌توانید از روش 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 Object که enum هستند در پایتون با نوع enum بومی نشان داده می شوند. این بدان معنی است که شما به راحتی می توانید ارزش عضو را بخوانید. کار با نمونه campaign از مثال قبلی در پاسخ پایتون:
>>> 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 تنظیم کرده باشید، تعامل با enums متفاوت است. برای جزئیات بیشتر در مورد این دو رابط، به مستندات پیام های protobuf مراجعه کنید.
نسخه سازی
چندین نسخه از API به طور همزمان نگهداری می شوند. در حالی که v18 ممکن است آخرین نسخه باشد، نسخه های قبلی هنوز تا غروب آفتاب در دسترس هستند. این کتابخانه شامل کلاس‌های پیام اولیه جداگانه است که با هر نسخه فعال 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 پیدا کنید.