دریافت ارجاعات به تمام کلاسهای مختلف پروتو که برای استفاده از API در پایتون مورد نیاز هستند، میتواند طولانی باشد و مستلزم آن است که شما درک ذاتی از API داشته باشید یا مرتباً برای ارجاع به پروتوها یا مستندات، context-switch کنید.
متدهای get_service و get_type کلاینت
این دو متد getter به شما امکان میدهند هر سرویس یا شیء type را در API بازیابی کنید. متد get_service برای بازیابی کلاینتهای سرویس استفاده میشود. get_type برای هر شیء دیگری استفاده میشود. کلاسهای کلاینت سرویس در کد زیر مسیر نسخه google/ads/googleads/v*/services/services/ تعریف شدهاند و همه نوعها زیر دستههای مختلف شیء، google/ads/googleads/v*/common|enums|errors|resources|services/types/ شدهاند. تمام کد زیر دایرکتوری version تولید میشود، بنابراین در صورت تغییر ساختار کدبیس، بهتر است به جای وارد کردن مستقیم اشیاء، از این متدها استفاده کنید.
در اینجا مثالی از نحوه استفاده از متد 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 v23 version of GoogleAdsService will
# be returned.
client = GoogleAdsClient.load_from_storage(version="v23")
googleads_service = client.get_service("GoogleAdsService")
در اینجا مثالی از نحوه استفاده از متد get_type برای بازیابی یک نمونه Campaign آورده شده است.
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage(version="v23")
campaign = client.get_type("Campaign")
انومها
اگرچه میتوانید از متد get_type برای بازیابی Enumها استفاده کنید، هر نمونه GoogleAdsClient دارای یک ویژگی enums نیز هست که به صورت پویا Enumها را با استفاده از همان مکانیزم متد get_type بارگذاری میکند. این رابط کاربری به گونهای طراحی شده است که سادهتر و خواناتر از استفاده get_type باشد:
client = GoogleAdsClient.load_from_storage(version=v23)
campaign = client.get_type("Campaign")
campaign.status = client.enums.CampaignStatusEnum.PAUSED
فیلدهای شیء اولیه که enum هستند در پایتون توسط نوع enum بومی نمایش داده میشوند. این بدان معناست که میتوانید به راحتی مقدار عضو را بخوانید. کار با نمونه campaign از مثال قبلی در یک 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 به طور همزمان نگهداری میشوند. در حالی که v23 ممکن است آخرین نسخه باشد، نسخههای قبلی هنوز تا زمان انقضا قابل دسترسی هستند. این کتابخانه شامل کلاسهای پیام proto جداگانهای است که با هر نسخه فعال API مطابقت دارند. برای دسترسی به یک کلاس پیام برای یک نسخه خاص، هنگام مقداردهی اولیه یک کلاینت، پارامتر کلمه کلیدی version را وارد کنید تا همیشه نمونهای از آن نسخه داده شده را برگرداند:
client = GoogleAdsService.load_from_storage(version="/google-ads/api/reference/rpc/v23/")
# The Campaign instance will be from the v23 version of the API.
campaign = client.get_type("Campaign")
همچنین میتوان هنگام فراخوانی متدهای get_service و get_type نسخه را مشخص کرد. انجام این کار، نسخه ارائه شده هنگام مقداردهی اولیه کلاینت را لغو میکند:
client = GoogleAdsService.load_from_storage()
# This will load the v23 version of the GoogleAdsService.
googleads_service = client.get_service(
"GoogleAdsService", version="v23")
client = GoogleAdsService.load_from_storage(version="v23")
# This will load the v21 version of a Campaign.
campaign = client.get_type("Campaign", version="v21")
اگر هیچ پارامتر کلمه کلیدی version ارائه نشود، کتابخانه به طور پیشفرض از آخرین نسخه استفاده میکند. لیست بهروز شدهای از آخرین نسخهها و سایر نسخههای موجود را میتوانید در بخش ناوبری سمت چپ مستندات مرجع API پیدا کنید.