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

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

طريقتَا 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 v16 version of GoogleAdsService will
# be returned.
client = GoogleAdsClient.load_from_storage(version="v16")
googleads_service = client.get_service("GoogleAdsService")

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

from google.ads.googleads.client import GoogleAdsClient

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

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

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

client = GoogleAdsClient.load_from_storage(version=v16)

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

يتم تمثيل حقول كائنات Proto التي تكون تعدادًا في بايثون بالنوع الأصلي enum. هذا يعني أنه يمكنك بسهولة قراءة قيمة العضو. استخدام مثيل campaign من المثال السابق في حلقة repl نفسها من 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.

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

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

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

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

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

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

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