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

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

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

from google.ads.googleads.client import GoogleAdsClient

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

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

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

client = GoogleAdsClient.load_from_storage(version=v23)

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

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

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

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

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

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

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

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

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

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

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