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

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

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

from google.ads.googleads.client import GoogleAdsClient

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

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

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

client = GoogleAdsClient.load_from_storage(version=v25)

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

يتم تمثيل حقول كائنات النماذج الأولية التي تكون عمليات تعداد في Python من خلال نوع التعداد الأصلي . هذا يعني أنّه يمكنك قراءة قيمة العضو بسهولة. العمل مع مثيل 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. للحصول على تفاصيل عن الواجهتَين، يُرجى الاطّلاع على مستندات رسائل بروتوكول المخزن المؤقت للبيانات.

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

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

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

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

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

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

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