يفرض 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 بدون أي تكلفة إضافية. لا يؤدي تجاوز حدود طلبات الحصة إلى فرض رسوم إضافية، ولا يتم تحصيل أي رسوم من حسابك.