يفرض Google Calendar API حصصًا لضمان استخدام جميع المستخدمين له بشكل عادل. هناك ثلاثة قيود مهمة يجب مراعاتها عند استخدام Calendar API:
- يتم فرض حصص استخدام واجهة برمجة التطبيقات لكل مشروع ولكل مستخدم. راجِع القسم التالي للحصول على مزيد من المعلومات.
- حدود الاستخدام العامة في "تقويم Google": تجنَّب حدود استخدام "تقويم Google".
- الحدود التشغيلية: قد يتم فرض حدّ على عدد الطلبات في أي وقت. على سبيل المثال، إذا حاولت الكتابة إلى تقويم واحد بشكل متكرّر وسريع.
أنواع حصص استخدام Calendar API
يتم فرض نوعَين من الحصص:
- في الدقيقة لكل مشروع: يشير هذا المقياس إلى عدد الطلبات التي يرسلها مشروعك على 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 بدون أي تكلفة إضافية. لا يؤدي تجاوز حدود طلبات الحصة إلى فرض رسوم إضافية، ولا يتم تحصيل أي رسوم من حسابك.