دوال الحصول على الخدمة والنوع

قد يكون جلب المراجع لجميع فئات proto المختلفة المطلوبة لاستخدام واجهة برمجة التطبيقات في Python مطوّلاً ويتطلّب منك فهمًا جوهريًا لواجهة برمجة التطبيقات أو التبديل المتكرر للسياق للإشارة إلى protos أو المستندات.

طريقتَا get_service وget_type للعميل

تتيح لك هاتان الطريقتان استرداد أي خدمة أو عنصر نوع في واجهة برمجة التطبيقات. يتم استخدام طريقة 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 المضمّن. هذا يعني أنه يمكنك قراءة قيمة العضو مباشرة. Working with the campaign instance from the previous example in a 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.

تحديد الإصدار

تتم صيانة إصدارات متعددة من واجهة برمجة التطبيقات في الوقت نفسه. على الرغم من أنّ الإصدار v26 هو الأحدث، لا يزال بإمكانك الوصول إلى الإصدارات السابقة إلى أن يتم إيقافها نهائيًا. تتضمّن المكتبة فئات رسائل proto منفصلة تتوافق مع كل إصدار نشط من واجهة برمجة التطبيقات. للوصول إلى فئة رسالة لإصدار معيّن، يجب تقديم مَعلمة الكلمة الرئيسية 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"). ويمكن العثور على قائمة محدَّثة بأحدث الإصدارات والإصدارات الأخرى المتاحة في قسم التنقّل على يمين مستندات مرجع واجهة برمجة التطبيقات.