تتضمّن Google Calendar API حصصًا للتأكّد من استخدامها بشكل عادل من قِبل جميع المستخدمين. هناك ثلاثة قيود مهمة يجب مراعاتها عند استخدام واجهة برمجة التطبيقات Calendar API:
- يتم فرض حصص استخدام واجهة برمجة التطبيقات لكل مشروع ولكل مستخدم. راجِع القسم التالي لمزيد من المعلومات.
- الحدود العامة لاستخدام "تقويم Google": تجنَّب تجاوز الحدود القصوى لاستخدام "تقويم Google".
- الحدود التشغيلية: قد يتم فرض قيود على معدّل التحميل في أي وقت. على سبيل المثال، إذا حاولت الكتابة في تقويم واحد بشكل متتابع وسريعة.
أنواع حصص استخدام واجهة برمجة التطبيقات Calendar API
يتم فرض نوعَين من الحصص:
- في الدقيقة لكل مشروع: يشير ذلك إلى عدد الطلبات التي يقدّمها مشروعك على Google Cloud.
- في الدقيقة لكل مشروع لكل مستخدم: يشير ذلك إلى عدد الطلبات التي يقدّمها أي مستخدم معيّن في مشروعك على Cloud. يهدف هذا الحد إلى مساعدتك في ضمان توزيع عادل لاستخدام التطبيق بين المستخدمين.
يتم احتساب الحصص كل دقيقة باستخدام فترة زمنية متحركة، لذا فإنّ أيّ زيادة مفاجئة في عدد الزيارات تتجاوز الحصة المحدّدة لك كل دقيقة خلال دقيقة واحدة ستؤدي إلى وضع حدود على معدّل الإرسال خلال الفترة الزمنية التالية لضمان أن يظلّ استخدامك ضمن الحصص في المتوسّط.
في حال تجاوز أيّ من الحصص، سيتم فرض حدّ أقصى على معدّل إرسال طلبات البحث وستتلقّى
رمز الحالة 403 usageLimits
أو
رمز الحالة 429 usageLimits
في طلبات البحث. في هذه الحالة، إليك الإجراءات التي يمكنك اتّخاذها:
- احرص على اتّباع جميع أفضل الممارسات: استخدام الفاصل الزمني المتزايد، تعشيب أنماط الزيارات، استخدام الإشعارات الفورية.
- إذا كان مشروعك ينمو وأصبح لديك المزيد من المستخدمين، يمكنك طلب زيادة الحصة لكل مشروع.
- إذا تمّ بلوغ الحدّ الأقصى للحصة لكلّ مستخدم، يمكنك إجراء ما يلي:
- إذا كنت تستخدم حساب خدمة، يمكنك تخصيص الحمل للمستخدمين أو تقسيمه بين حسابات خدمة متعددة.
- على الرغم من أنّه يمكنك طلب زيادة الحصة لكل مستخدم، إلا أنّه بشكل عام لا يُنصح بزيادتها فوق القيمة التلقائية لأنّ تطبيقك قد يبدأ في الوصول إلى أنواع أخرى من الحدود، على سبيل المثال، حدود استخدام التقويم العامة، أو الحدود التشغيلية.
طلب زيادة الحصة
لعرض حدود الاستخدام لمشروعك أو تغييرها، أو لطلب زيادة حصتك، اتّبِع الخطوات التالية:
- إذا لم يكن لديك حساب فوترة لمشروعك، أنشئ حسابًا.
- انتقِل إلى صفحة "واجهات برمجة التطبيقات المفعّلة" في "مكتبة واجهات برمجة التطبيقات" في "وحدة تحكّم واجهة برمجة التطبيقات"، واختَر واجهة برمجة تطبيقات من القائمة.
- للاطّلاع على الإعدادات المتعلّقة بالحصص وتغييرها، انقر على الحصص. للاطّلاع على إحصاءات الاستخدام، اختَر الاستخدام.
استخدام خوارزمية الرقود الأسي
عندما نريد منك تقليل معدّل الطلبات، سنعرض استجابة 403 "usageLimits" أو استجابة 429 (اطّلِع على مستندات الأخطاء الكاملة). هذا الخطأ ليس فادحًا ونتوقع منك إعادة محاولة إرسال الطلب بعد فاصل قصير. إذا استمرت الطلبات في الوصول بسرعة كبيرة، سنطلب منك إعادة إرسالها، وهكذا. لكي يعمل هذا الإجراء بشكل صحيح، من المهم أن تزداد حالات التأخير بين الطلبات بمرور الوقت.
بشكل عام، يجب استخدام الفاصل الزمني المتزايد المقطوع. يمكنك الاطّلاع على مستندات Cloud Storage لفهم آلية عمل هذه الطريقة والخوارزمية المفضّلة. إذا كنت تستخدم مكتبة عملاء Google، سيتم عادةً تنفيذ ذلك نيابةً عنك. يمكنك الرجوع إلى مستندات المكتبة. في العادة، يجب استخدام عملية تنفيذ المكتبة بدلاً من كتابة عملية تنفيذ خاصة بك.
ترتيب أنماط حركة المرور عشوائيًا
عملاء "تقويم Google" معرّضون لأنماط الزيارات المفاجئة الناتجة عن تنفيذ عملاء متعدّدين لعمليات في الوقت نفسه. على سبيل المثال، من الممارسات العميلة السيئة التي يتبعها عملاء "تقويم Google" هي إجراء مزامنة كاملة عند منتصف الليل. من المؤكد تقريبًا أنّ ذلك سيؤدي إلى تجاوز الحصة المحدّدة لك في الدقيقة، مما سيؤدي إلى فرض حدود على معدّل الإرسال وإعادة المحاولة.
لتجنُّب ذلك، احرص على توزيع الزيارات على مدار اليوم حيثما أمكن. إذا كان العميل بحاجة إلى إجراء مزامنة يومية، اطلب منه تحديد وقت عشوائي (يختلف من عميل لآخر). إذا كنت بحاجة إلى تنفيذ عملية بشكل منتظم، يمكنك تغيير الفاصل الزمني بنسبة %25 +/-. سيؤدي ذلك إلى توزيع الزيارات بشكلٍ أكثر توازناً وتقديم تجربة أفضل للمستخدمين.
استخدام الإشعارات الفورية
ومن حالات الاستخدام الشائعة الرغبة في تنفيذ إجراء عند حدوث تغيير في تقويم المستخدم. ومن الممارسات غير المُقترَحة إجراء استطلاعات متكرّرة لكل تقويم يهمّك. سيؤدي ذلك إلى استخدام كل حصتك بسرعة كبيرة. على سبيل المثال، إذا كان تطبيقك يتضمّن 5,000 مستخدم ويفحص تقويم كل مستخدم مرة واحدة في الدقيقة، سيتطلب ذلك حصة لا تقل عن 5,000 في الدقيقة حتى قبل تنفيذ أي عمل.
يمكن للتطبيقات من جهة الخادم التسجيل للحصول على إشعارات فورية، ما يتيح لنا إعلامك عند حدوث أمر مثير للاهتمام. تتطلّب هذه الحلول مزيدًا من العمل ل
إعدادها، ولكنها تسمح باستخدام حصتك بكفاءة أكبر بكثير، و
توفّر تجربة أفضل للمستخدم. احرص على تحديد eventType
التي تريد تلقّي إشعارات بشأنها. لمزيد من المعلومات، يُرجى الاطّلاع على
الإشعارات الفورية.
إعداد التقارير بشكل صحيح باستخدام حسابات الخدمة
إذا كان تطبيقك يُجري طلبات باستخدام
التفويض على مستوى النطاق،
يتم تحصيل الرسوم من حساب الخدمة تلقائيًا وفقًا لحصص "كل دقيقة لكل
مشروع لكل مستخدم"، وليس من المستخدم الذي تنتحل هويته. وهذا يعني
أنّه من المرجّح أن ينفد الحدّ الأقصى المسموح به لحساب الخدمة وأن يتمّ تقييد معدّل نقل البيانات،
حتى إذا كان يعمل على تقويمات مستخدمين متعدّدين. يمكنك تجنُّب
ذلك باستخدام مَعلمة عنوان URL quotaUser (أو عنوان HTTP
x-goog-quota-user) للإشارة إلى المستخدم الذي سيتم تحصيل الرسوم منه. لا يُستخدَم هذا الإجراء إلا لعمليات حساب
الحصص. اطّلِع على وضع حدود على الطلبات لكل مستخدم في مستندات Cloud للحصول على مزيد من المعلومات.
معالجة الحد الأقصى للحصة الاختبارية
لضمان أنّ تطبيقك يمكنه التعامل بسلاسة مع بلوغ حدود الحصة في العملية (مثلاً من خلال إعادة المحاولة مع فترة انتظار تصاعدية) ومحاولة التقليل من أي إزعاج محتمل للمستخدمين، ننصحك بشدة باختبار هذا السيناريو في بيئة حقيقية.
لكي لا يتداخل هذا الاختبار مع استخدامك الفعلي للتطبيق، ننصحك بتسجيل مشروع منفصل للاختبار فقط في وحدة تحكّم واجهة برمجة تطبيقات Google و ضبطه بطريقة مشابهة لمشروعك العلني. يمكنك بعد ذلك ضبط حصص منخفضة بشكل مصطنع لهذا المشروع وملاحظة سلوك تطبيقك.
الأسعار
يمكنك استخدام Google Calendar API بدون أي تكلفة إضافية. لا يؤدي تجاوز الحصة أو حدود الطلبات إلى تحمُّل رسوم إضافية ولا يتمّ تحصيل رسوم من حسابك.