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

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

أسلوبَي العميل 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 v13 version of GoogleAdsService will
# be returned.
client = GoogleAdsClient.load_from_storage(version="v13")
googleads_service = client.get_service("GoogleAdsService")

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

from google.ads.googleads.client import GoogleAdsClient

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

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

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

client = GoogleAdsClient.load_from_storage(version=v13)

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

حقول كائن Proto التي تمثل تعدادًا تمثيليًا تمثل لغة Python نوع 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. للحصول على تفاصيل عن الواجهتين، راجع مستندات رسائل Protobuf.

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

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

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

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

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

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

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