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

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

روش‌های 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 v25 version of GoogleAdsService will
# be returned.
client = GoogleAdsClient.load_from_storage(version="v25")
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="v25")
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="v25")

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

گاهی اوقات دانستن نام فیلدی که با مقدار شمارشی مطابقت دارد مفید است. بااستفاده از مشخصه name می‌توانید به این اطلاعات دسترسی پیدا کنید:

>>> print(campaign.status.name)
'PAUSED'
>>> type(campaign.status.name)
<class 'str'>

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

نسخه‌بندی

چندین نسخه از API به‌طور هم‌زمان نگهداری می‌شوند. اگرچه v25 جدیدترین نسخه است، نسخه‌های قبلی تا زمانی که منسوخ شوند همچنان دردسترس هستند. کتابخانه شامل کلاس‌های پیام اولیه جداگانه‌ای است که با هر نسخه فعال API مطابقت دارند. برای دسترسی به کلاس پیام برای نسخه‌ای خاص، پارامتر کلیدواژه version را هنگام مقداردهی اولیه کارخواه ارائه دهید تا همیشه نمونه‌ای از آن نسخه داده‌شده را برگرداند:

from google.ads.googleads.client import GoogleAdsClient

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

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

اگر پارامتر کلیدواژه version ارائه نشود، کتابخانه به‌طور پیش‌فرض از بالاترین نسخه API پشتیبانی‌شده توسط بسته google-ads نصب‌شده شما ("v25" در جدیدترین نسخه پخش) استفاده می‌کند. توجه داشته باشید که نسخه‌های جزئی میانای برنامه‌سازی کاربردی (مثل v25.1) بااستفاده از رشته نسخه اصلی آن‌ها (version="v25") قابل‌دسترسی هستند. فهرست به‌روزشده‌ای از جدیدترین و دیگر نسخه‌های دردسترس را می‌توانید در بخش پیمایش سمت راست اسناد مرجع میانای برنامه‌سازی کاربردی پیدا کنید.