أفضل الممارسات

تتناول هذه الصفحة مجموعة من أفضل الممارسات التي يجب أخذها في الاعتبار عند تطوير التطبيقات استنادًا إلى واجهة برمجة تطبيقات "مدير إعلانات Google".

إعادة استخدام برامج/رموز الخدمة أثناء التنفيذ

يؤدي إنشاء عميل/رمز خدمة جديد إلى تكلفة هامشية مرتبطة بجلب WSDL وتخصيص الموارد. إن أمكن، قم بإنشاء عميل/قسيمة الخدمة مرة واحدة في بداية التنفيذ وجعلها متاحة للفئات والدوال حسب الحاجة.

استخدام التقسيم على صفحات عند استرجاع العناصر

تتوافق جميع الخدمات مع طريقة get*ByStatement() التي تتيح فلترة النتائج باستخدام بنية PQL. يمكن استخدام العبارتَين LIMIT وOFFSET لتقسيم مجموعات النتائج الكبيرة إلى صفحات، ما يؤدي إلى تجنُّب انقطاع الفترات الزمنية والحفاظ على أحجام صفحات الاستجابة معقولة. يتراوح حجم الصفحة المقترَح بين 200 و500، بناءً على مدى تعقيد العناصر.

طلبات التعديل المجمّع

عند تغيير كائنات متعددة من النوع نفسه، يمكنك الحصول على أداء أفضل من خلال إرسال جميع العناصر في طلب update*() نفسه. هناك نفقة هامشية على العميل والخادم لكل طلب، ويمكن أن يكون التجميع وسيلة فعّالة لتقليل عدد الطلبات. على سبيل المثال، يمكنك استخدام updateOrders لتعديل مجموعة من الطلبات بدلاً من طلب واحد في كل مكالمة.

استخدام معلمات الربط في PQL

معلمات الربط هي طريقة لوضع المتغيرات في عبارة استعلام PQL. تشير PQL إلى متغير ربط باسم بدون مسافات تبدأ بنقطتين، على سبيل المثال، :name. يتم تقديم مثال رمز في صفحة بنية PQL.

ننصح باستخدام متغيرات الربط لأنّها تحسّن إمكانية قراءة الرمز البرمجي عن طريق إزالة الحاجة إلى ربط السلاسل والمتغيرات في عبارة طلب بحث. كما أنها تسهل إعادة استخدام عبارات PQL، حيث يمكن إجراء استعلامات جديدة عن طريق استبدال قيم معلمات الربط.

منح امتيازات المستخدم باعتدال

عند استخدام UserService لإنشاء/تحديث أدوار المستخدمين، احرص على عدم منح المستخدمين امتيازات لا يحتاجون إليها. يمكن الوصول إلى العديد من ميزات واجهة برمجة التطبيقات باستخدام مجموعة من الأدوار بدلاً من تعيين دور المشرف للمستخدم. يُرجى الرجوع إلى مستندات الأذونات عند تحديد الأدوار التي يجب تخصيصها للمستخدم. بالإضافة إلى ذلك، بصفتك مطور تطبيقات تابعًا لجهة خارجية، احرص على تحديد مستوى الوصول الذي يحتاجه تطبيقك عندما تطلب من الشبكة إنشاء مستخدم نيابةً عنك، حيث قد يكون الدور الذي يتضمن امتيازات أقل من المشرف كافيًا.

لا تتجاوز حدود الحصة المسموح بها

تفرض واجهة برمجة تطبيقات "مدير الإعلانات" العديد من حدود الحصص لزيادة القوة. ومن المهم إبقاء تطبيقاتك ضمن هذه الحدود ومعرفة كيفية الرد على أي من أخطاء الحصة التي يمكن أن تعرضها واجهة برمجة التطبيقات.

حصة واجهة برمجة التطبيقات

إنّ الحصة الأولى المطبَّقة على طلبات البيانات من واجهة برمجة التطبيقات هي حصة على مستوى الشبكة. بالنسبة إلى حسابات "مدير إعلانات Google 360"، الحدّ الأقصى المسموح به هو 8 طلبات في الثانية، وبالنسبة إلى حسابات "مدير الإعلانات"، يبلغ الحدّ الأقصى طلبَين في الثانية. ويؤدي تجاوز هذا الحدّ إلى حدوث خطأ QuotaError.EXCEEDED_QUOTA. وتنطبق جميع طلبات البيانات من واجهة برمجة التطبيقات التي تم إجراؤها على شبكتك على هذه الحصة، بما في ذلك تطبيقات الجهات الخارجية التي منحتها أنت أو شخص ما في شركتك إمكانية الوصول إلى واجهة برمجة التطبيقات إلى شبكتك.

الحصص الخاصة بالنظام

حصة واجهة برمجة التطبيقات وحدها لا تكفي لتوفير حماية كافية لبعض الأنظمة التي تستهلك قدرًا كبيرًا من الموارد ضمن "مدير الإعلانات". وتحدّد أنظمة إعداد التقارير والتوقعات حصصها الخاصة التي يمكن أن تؤدي إلى حدوث أخطاء في واجهة برمجة التطبيقات: QuotaError.REPORT_JOB_LIMIT و ForecastError.EXCEEDED_QUOTA، على التوالي.

معالجة أخطاء الحصة

إذا واجه تطبيقك أيًّا من أخطاء الحصّة الواردة أعلاه، يمكنك تنفيذ استراتيجية لإعادة محاولة طلب البيانات من واجهة برمجة التطبيقات. ننصحك بالانتظار لمدة 5 ثوانٍ على الأقل أولاً، وفي حال استمرار ظهور الخطأ، استخدِم الرقود الأسي الثنائي لزيادة الوقت بين عمليات إعادة المحاولة. وإذا لم تنجح إعادة المحاولة، عليك إجراء تدقيق لتطبيقات واجهة برمجة التطبيقات لمعرفة ما إذا كان هناك أي مستخدمين على شبكتك يستنفدون حصتك.