يمكن أن يكون استرجاع المراجع لجميع فئات 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
للكلمات الرئيسية، ستستخدم المكتبة أحدث إصدار تلقائيًا. يمكن العثور على قائمة معدّلة بأحدث الإصدارات والإصدارات الأخرى المتوفّرة في قسم التنقّل الأيمن من الوثائق الخاصة بمرجع واجهة برمجة التطبيقات.