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

يمكن أن يكون استرداد مراجع لجميع فئات البروتوكول المتنوعة المطلوبة لاستخدام واجهة برمجة التطبيقات في 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 v21 version of GoogleAdsService will
# be returned.
client = GoogleAdsClient.load_from_storage(version="v21")
googleads_service = client.get_service("GoogleAdsService")

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

from google.ads.googleads.client import GoogleAdsClient

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

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

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

client = GoogleAdsClient.load_from_storage(version=v21)

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.

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

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

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

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

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

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

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