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

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

طريقة get_service وget_type للعميل

تتيح لك طريقتا التلقي هاتين باسترداد أي خدمة أو نوع كائن في واجهة برمجة التطبيقات. يتم استخدام الطريقة get_service لاسترداد برامج الخدمة. تُستخدم get_type لأي كائن آخر. يتم تحديد فئات برامج الخدمة في الرمز البرمجي ضمن مسار الإصدار google/ads/googleads/v*/services/services/، ويتم تحديد جميع الأنواع ضمن فئات العناصر المختلفة، google/ads/googleads/v*/common|enums|errors|resources|services/types/. يتم إنشاء جميع التعليمات البرمجية الموجودة أسفل دليل الإصدار، لذا من أفضل الممارسات استخدام هذه الطرق بدلاً من استيراد الكائنات مباشرةً، في حالة تغيير هيكل قاعدة التعليمات البرمجية.

إليك مثال على كيفية استخدام طريقة 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 v17 version of GoogleAdsService will
# be returned.
client = GoogleAdsClient.load_from_storage(version="v17")
googleads_service = client.get_service("GoogleAdsService")

إليك مثال على كيفية استخدام طريقة get_type لاسترداد مثيل Campaign.

from google.ads.googleads.client import GoogleAdsClient

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

عمليات التعداد

يمكنك استخدام طريقة get_type لاسترداد قيم التعداد، إلّا أنّ كل مثيل من نوع GoogleAdsClient يحتوي أيضًا على السمة enums التي تُحمّل قيم التعداد بشكل ديناميكي باستخدام الآلية نفسها المتّبعة في طريقة get_type. تم تصميم هذه الواجهة لتكون أبسط وأسهل في القراءة من استخدام get_type:

client = GoogleAdsClient.load_from_storage(version=v17)

campaign = client.get_type("Campaign")
campaign.status = client.enums.CampaignStatusEnum.PAUSED

يتم تمثيل حقول كائنات Proto التي هي تعدادات في بايثون باستخدام نوع enum الأصلي. هذا يعني أنه يمكنك قراءة قيمة العضو بسهولة. العمل مع المثيل campaign من المثال السابق في نسخة Python:

>>> 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. للحصول على تفاصيل عن الواجهتين، يُرجى الاطّلاع على مستندات رسائل النموذج الأوّلي.

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

ويتم الاحتفاظ بإصدارات متعددة من واجهة برمجة التطبيقات في الوقت نفسه. قد يكون الإصدار v17 هو أحدث إصدار، إلا أنّه لا يزال بالإمكان الوصول إلى الإصدارات الأقدم إلى أن يتم إيقافها نهائيًا. ستتضمن المكتبة فئات رسائل أولية منفصلة تتوافق مع كل إصدار نشط لواجهة برمجة التطبيقات. للوصول إلى فئة رسالة لإصدار معيّن، وفِّر مَعلمة الكلمة الرئيسية version عند إعداد جهاز عميل لكي تعرض دائمًا مثيلاً من تلك النسخة المحدّدة:

client = GoogleAdsService.load_from_storage(version="/google-ads/api/reference/rpc/v17/")
# The Campaign instance will be from the v17 version of the API.
campaign = client.get_type("Campaign")

ويمكن أيضًا تحديد الإصدار عند استدعاء الطريقتين get_service وget_type. سيؤدي القيام بذلك إلى إلغاء الإصدار المقدم عند تهيئة العميل:

client = GoogleAdsService.load_from_storage()
# This will load the v17 version of the GoogleAdsService.
googleads_service = client.get_service(
    "GoogleAdsService", version="v17")

client = GoogleAdsService.load_from_storage(version="v17")
# This will load the v15 version of a Campaign.
campaign = client.get_type("Campaign", version="v15")

إذا لم يتم توفير مَعلمة version للكلمات الرئيسية، ستستخدم المكتبة أحدث إصدار تلقائيًا. يمكن العثور على قائمة محدَّثة بأحدث الإصدارات المتاحة والإصدارات الأخرى في قسم التنقّل الأيمن من وثائق مرجع واجهة برمجة التطبيقات.