دریافت‌کننده‌های نوع و سرویس

واکشی ارجاع‌ها به همه کلاس‌های proto مختلف موردنیاز برای استفاده از API در Python می‌تواند طولانی باشد و مستلزم این است که درک ذاتی از API داشته باشید یا به‌طور مکرر برای ارجاع به proto یا اسناد، بافت را تغییر دهید.

روش‌های get_service و get_type مشتری

این دو روش دریافت‌کننده به شما امکان می‌دهند هر سرویس یا شیء نوعی را در API بازیابی کنید. از روش get_service برای بازیابی کارخواهان سرویس استفاده می‌شود. get_type برای شیء دیگری استفاده شده است. کلاس‌های مشتری سرویس در کد تحت مسیر نسخه google/ads/googleads/v*/services/ تعریف شده‌اند و همه انواع تحت دسته‌های مختلف شیء google/ads/googleads/v*/common|enums|errors|resources|services/types/ تعریف شده‌اند. همه کدهای زیر دایرکتوری نسخه تولید می‌شوند، بنابراین بهترین روش این است که به‌جای وارد کردن مستقیم اشیا، از این روش‌ها استفاده کنید تا درصورت تغییر ساختار پایگاه کد، مشکلی پیش نیاید.

مثال زیر نحوه استفاده از روش 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)

مثال زیر نشان می‌دهد که چگونه از روش get_type برای بازیابی نمونه Campaign استفاده کنید:

from google.ads.googleads.client import GoogleAdsClient

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

شمارشی‌ها

درحالی‌که می‌توانید از روش get_type برای بازیابی شمارشی‌ها استفاده کنید، هر نمونه GoogleAdsClient نیز دارای یک ویژگی enums است که به‌طور پویا شمارشی‌ها را بااستفاده از همان مکانیزم روش 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 که شمارشی هستند در 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'>

تعامل با شمارشی‌ها بسته به اینکه پیکربندی use_proto_plus روی true یا false تنظیم شده باشد متفاوت است. برای جزئیات مربوط به این دو میانای کاربری، به اسناد پیام‌های protobuf مراجعه کنید.

نسخه‌بندی

چندین نسخه از میانای برنامه‌سازی کاربردی به‌طور هم‌زمان نگهداری می‌شود. درحالی‌که v26 جدیدترین نسخه است، نسخه‌های قبلی هنوز تا زمان منسوخ شدن قابل‌دسترسی هستند. کتابخانه شامل کلاس‌های پیام proto جداگانه‌ای است که با هر نسخه فعال 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 ارائه نشده باشد، کتابخانه به‌طور پیش‌فرض از بالاترین نسخه میانای برنامه‌سازی کاربردی پشتیبانی‌شده توسط بسته google-ads نصب‌شده شما ("v26" در جدیدترین نسخه پخش) استفاده می‌کند. توجه داشته باشید که نسخه‌های جزئی میانای برنامه‌سازی کاربردی (مثل v25.1) بااستفاده از رشته نسخه عمده آن‌ها (version="v25") قابل‌دسترسی هستند. فهرست به‌روزشده جدیدترین نسخه‌ها و دیگر نسخه‌های دردسترس را می‌توانید در بخش پیمایش سمت راست سند مرجع میانای برنامه‌سازی کاربردی پیدا کنید.