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

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

طرق 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 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.

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

يتم الاحتفاظ بإصدارات متعددة من واجهة برمجة التطبيقات في الوقت نفسه. مع أنّ v25 هو أحدث إصدار، سيظل بإمكانك استخدام الإصدارات السابقة إلى أن يتم إيقافها نهائيًا. تتضمّن المكتبة فئات رسائل proto منفصلة تتوافق مع كل إصدار نشط من واجهة برمجة التطبيقات. للوصول إلى فئة رسائل لإصدار معيّن، قدِّم مَعلمة الكلمة الرئيسية 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، ستستخدم المكتبة تلقائيًا أعلى إصدار من واجهة برمجة التطبيقات يتوافق مع حزمة google-ads المثبَّتة ("v25" في الإصدار الأخير). يُرجى العِلم أنّه يمكن الوصول إلى إصدارات واجهة برمجة التطبيقات الثانوية (مثل v25.1) باستخدام سلسلة رقم الإصدار الرئيسي (version="v25"). ويمكنك الاطّلاع على قائمة معدَّلة بأحدث الإصدارات والإصدارات الأخرى المتاحة في قسم التنقّل على الجانب الأيسر من مستندات مرجع واجهة برمجة التطبيقات.