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

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

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

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

from google.ads.googleads.client import GoogleAdsClient

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

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

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

client = GoogleAdsClient.load_from_storage(version=v18)

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

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

>>> print(campaign.status)
CampaignStatus.PAUSED
>>> type(campaign.status)
<enum 'CampaignStatus'>
>>> print(campaign.status.value)
3

في بعض الأحيان، يكون من المفيد معرفة اسم الحقل الذي يتوافق مع قيمة enum كما هو موضّح أعلاه. يمكنك الوصول إلى هذه المعلومات باستخدام سمة name:

>>> print(campaign.status.name)
'PAUSED'
>>> type(campaign.status.name)
<class 'str'>

يختلف التفاعل مع القوائم المحددة حسب ما إذا تم ضبط الإعداد use_proto_plus على true أو false. لمعرفة التفاصيل حول الواجهات الاتّجاهيتين، يُرجى الاطّلاع على مستندات رسائل protobuf.

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

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

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

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

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

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

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