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