تتضمّن Google Calendar API حصصًا لضمان استخدامها بشكل عادل من قِبل جميع المستخدمين. هناك ثلاثة قيود مهمة يجب أخذها في الاعتبار عند استخدام Calendar API:
حصص استخدام واجهة برمجة التطبيقات: يتم فرضها لكل مشروع ولكل مستخدم. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة أنواع حصص استخدام Calendar API.
الحدود العامة لاستخدام "تقويم Google": إنّ Google Calendar API هي خدمة مشترَكة تتضمّن قيودًا لحماية الأداء العام لنظام Google Workspace. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة تجنُّب تجاوز حدود استخدام "تقويم Google"
الحدود التشغيلية: قد يتم تقييد هذه الحدود في أي وقت. على سبيل المثال، إذا حاولت الكتابة في تقويم واحد بسرعة متتالية.
حصص Calendar API
يتم فرض نوعَين من الحصص:
في الدقيقة لكل مشروع: هو عدد الطلبات التي يمكن أن يقدّمها مشروعك على Google Cloud في دقيقة واحدة.
في الدقيقة لكل مستخدم ولكل مشروع: هو عدد الطلبات التي يمكن أن يقدّمها أي مستخدم معيّن في مشروعك على السحابة الإلكترونية. يهدف هذا الحدّ إلى مساعدتك في ضمان توزيع عادل للاستخدام بين مستخدميك.
يتم احتساب الحصص في الدقيقة باستخدام نافذة منزلقة. إذا تجاوزت عدد الزيارات في الدقيقة حصتك خلال دقيقة واحدة، سيتم تقييد المعدّل خلال النافذة التالية لضمان بقاء استخدامك ضمن الحصص في المتوسط.
يوضّح الجدول التالي هذه الحدود:
| نوع حدّ الاستخدام | الحدّ |
|---|---|
| في الدقيقة لكل مشروع | 10,000 طلب |
| في الدقيقة لكل مستخدم ولكل مشروع | 600 طلب |
حد الفوترة اليومي
يحدّد هذا الحدّ اليومي لكل مشروع الحدّ الأقصى لعدد الطلبات التي يمكن أن يستخدمها مشروعك على Google Cloud خلال فترة 24 ساعة قبل تطبيق الرسوم.
لا يتم تحصيل رسوم إضافية مقابل الاستخدام ضمن هذا الحدّ الأقصى، ولا يتم تحصيل رسوم من حسابك على Google Cloud. ستتم مشاركة تفاصيل الفوترة الكاملة في وقت لاحق من عام 2026 مع إرسال إشعار قبل 90 يومًا على الأقل من تطبيق أي تغييرات.
لا يمكنك طلب زيادة هذا الحدّ الأقصى اليومي.
يوضّح الجدول التالي الحدّ الأقصى:
| نوع الحدّ الأقصى | الحدّ |
|---|---|
| في اليوم لكل مشروع | 1,000,000 طلب |
لمزيد من المعلومات، يُرجى الاطّلاع على مقالة نموذج Google Workspace الموحّد لأدوات الوكلاء وواجهات برمجة التطبيقات.
تحديد المشاكل وحلّها في ما يتعلّق بأخطاء الحصة المستندة إلى الوقت
بالنسبة إلى جميع الأخطاء المستندة إلى الوقت (الحدّ الأقصى لعدد N من الطلبات خلال X دقيقة)، ننصحك بأن يرصد الرمز البرمجي الاستثناء ويستخدم التمهُّل بين عمليات إعادة المحاولة الأسي المقتطع لضمان عدم توليد أجهزتك حملاً مفرطًا.
التمهُّل بين عمليات إعادة المحاولة الأسي هو استراتيجية عادية للتعامل مع الأخطاء في تطبيقات الشبكة. تعيد خوارزمية التمهُّل بين عمليات إعادة المحاولة الأسي محاولة إرسال الطلبات باستخدام أوقات انتظار متزايدة بشكل أسي بين الطلبات، وذلك حتى وقت أقصى للتمهُّل بين عمليات إعادة المحاولة. إذا استمرّت الطلبات في الفشل، من المهم أن تزداد حالات التأخير بين الطلبات بمرور الوقت إلى أن ينجح الطلب.
مثال على الخوارزمية
تعيد خوارزمية التمهُّل بين عمليات إعادة المحاولة الأسي محاولة إرسال الطلبات بشكل أسي، ما يؤدي إلى زيادة وقت الانتظار بين عمليات إعادة المحاولة حتى وقت أقصى للتمهُّل بين عمليات إعادة المحاولة. على سبيل المثال:
- أرسِل طلبًا إلى Google Calendar API.
- إذا تعذّر تنفيذ الطلب، انتظِر 1 +
random_number_millisecondsوأعِد محاولة إرسال الطلب. - إذا تعذّر تنفيذ الطلب، انتظِر 2 +
random_number_millisecondsوأعِد محاولة إرسال الطلب. - إذا تعذّر تنفيذ الطلب، انتظِر 4 +
random_number_millisecondsوأعِد محاولة إرسال الطلب. - وهكذا، حتى وقت
maximum_backoff. - واصِل الانتظار وإعادة المحاولة حتى عدد أقصى معيّن من عمليات إعادة المحاولة، ولكن لا تزد فترة الانتظار بين عمليات إعادة المحاولة.
حيث:
- وقت الانتظار هو
min(((2^n)+random_number_milliseconds), maximum_backoff), مع زيادةnبمقدار 1 لكل تكرار (طلب). random_number_millisecondsهو عدد عشوائي من الملّي ثانية أقل من أو يساوي 1,000. يساعد ذلك في تجنُّب الحالات التي تتم فيها مزامنة العديد من العملاء بسبب حالة معيّنة، ويعيدون جميعًا المحاولة في آنٍ واحد، ما يؤدي إلى إرسال الطلبات في موجات متزامنة. تتم إعادة احتساب قيمةrandom_number_millisecondsبعد كل طلب إعادة محاولة.maximum_backoffهو عادةً 32 أو 64 ثانية. تعتمد القيمة المناسبة على حالة الاستخدام.
يمكن أن يواصل العميل إعادة المحاولة بعد أن يصل إلى وقت maximum_backoff.
لا تحتاج عمليات إعادة المحاولة بعد هذه النقطة إلى مواصلة زيادة وقت التمهُّل بين عمليات إعادة المحاولة. على
سبيل المثال، إذا كان العميل يستخدم وقت maximum_backoff يبلغ 64 ثانية، يمكنه بعد الوصول إلى
هذه القيمة إعادة المحاولة كل 64 ثانية. في مرحلة معيّنة،
يجب منع العملاء من إعادة المحاولة إلى أجل غير مسمّى.
يعتمد وقت الانتظار بين عمليات إعادة المحاولة وعدد عمليات إعادة المحاولة على حالة الاستخدام وظروف الشبكة.
الأسعار
يمكنك استخدام Google Calendar API بشكل عادي بدون أي تكلفة إضافية. من المخطط أن يتم تحصيل رسوم من حساب الفوترة على Google Cloud في وقت لاحق من عام 2026 إذا تجاوزت حدود طلبات الحصة. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة نموذج Google Workspace الموحّد لأدوات الوكلاء وواجهات برمجة التطبيقات.
طلب زيادة الحصة
بناءً على استخدام مشروعك للموارد، قد تحتاج إلى طلب تعديل الحصة. تُعتبَر طلبات واجهة برمجة التطبيقات التي يقدّمها حساب خدمة مستخدِمة لحساب واحد. لا يضمن التقدم بطلب للحصول على حصة معدَّلة الموافقة. قد تستغرق طلبات تعديل الحصة التي ستؤدي إلى زيادة قيمة الحصة بشكل ملحوظ وقتًا أطول للموافقة عليها.
لا تتطابق الحصص بين جميع المشاريع. مع زيادة استخدامك لـ Google Cloud بمرور الوقت، قد تحتاج إلى زيادة قيم الحصة. إذا كنت تتوقّع زيادة ملحوظة في الاستخدام في المستقبل القريب، يمكنك طلب تعديلات الحصة بشكل استباقي من صفحة "الحصص وحدود النظام" في Google Cloud Console.
لمزيد من المعلومات، يُرجى الاطّلاع على المَراجع التالية:
تحديد المشاكل وحلّها
إذا تم تجاوز أي من الحصتين، سيتم تقييد المعدّل وستتلقّى رمز حالة 403
usageLimits
أو رمز حالة 429
usageLimits
ردًا على طلبات البحث.
في حال حدوث ذلك، يمكنك تجربة ما يلي:
تأكَّد من اتّباع جميع أفضل الممارسات: استخدام التمهُّل بين عمليات إعادة المحاولة الأسي، وترتيب أنماط الزيارات عشوائيًا، واستخدام الإشعارات الفورية.
إذا كان مشروعك يتوسع ولديك المزيد من المستخدمين، يمكنك طلب زيادة الحصة زيادة.
إذا بلغت حدود الحصة لكل مستخدم، يمكنك إجراء ما يلي:
إذا كنت تستخدم حساب خدمة، يمكنك توزيع الحمل على المستخدمين أو تقسيمه بين حسابات خدمة متعددة.
على الرغم من أنّه يمكنك طلب زيادة الحصة لكل مستخدم، لا يُنصح بشكل عام بزيادتها فوق القيمة التلقائية لأنّ تطبيقك قد يبدأ في بلوغ أنواع أخرى من الحدود، مثل الحدود العامة لاستخدام التقويم أو الحدود التشغيلية.
اختبِر حدود الحصة من خلال تسجيل مشروع منفصل للاختبار فقط يتضمّن إعدادًا مشابهًا لإعداد مشروع الإنتاج. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة اختبار طريقة التعامل مع حدّ الحصة.
ترتيب أنماط الزيارات عشوائيًا
تكون برامج "تقويم Google" عُرضة لأنماط الزيارات المفاجئة الناتجة عن تنفيذ عدة برامج عمليات في الوقت نفسه. على سبيل المثال، من الممارسات السيئة الشائعة لبرنامج "تقويم Google" إجراء مزامنة كاملة في منتصف الليل. سيؤدي ذلك على الأرجح إلى تجاوز الحصة في الدقيقة وتقييد المعدّل والتمهُّل بين عمليات إعادة المحاولة.
لتجنُّب ذلك، تأكَّد من توزيع الزيارات على مدار اليوم قدر الإمكان. إذا كان برنامجك بحاجة إلى إجراء مزامنة يومية، اطلب من البرنامج تحديد وقت عشوائي (مختلف لكل برنامج). إذا كنت بحاجة إلى إجراء عملية بشكل منتظم، غيِّر الفاصل الزمني بنسبة 25% +/-. سيؤدي ذلك إلى توزيع الزيارات بشكل أكثر توازنًا وتوفير تجربة أفضل بكثير للمستخدمين.
استخدام الإشعارات الفورية
من حالات الاستخدام الشائعة إجراء عملية كلما حدث تغيير في تقويم المستخدم. من الأنماط غير المستحسنة هنا إجراء استطلاع متكرّر لكل تقويم يهمّك. سيؤدي ذلك إلى استهلاك كل حصتك بسرعة كبيرة. على سبيل المثال، إذا كان تطبيقك يتضمّن 5,000 مستخدم ويستطلع تقويم كل مستخدم مرة واحدة في الدقيقة، يتطلّب ذلك حصة في الدقيقة تبلغ 5,000 على الأقل، حتى قبل إجراء أي عمل.
يمكن للتطبيقات من جهة الخادم الاشتراك في الإشعارات الفورية، ما يسمح لنا بإعلامك عندما يحدث شيء يهمّك. تتطلّب هذه الإشعارات المزيد من العمل لإعدادها، ولكنّها تسمح باستخدام حصتك بكفاءة أكبر بكثير، وتوفّر تجربة أفضل للمستخدمين. تأكَّد من تحديد eventType الذي تريد تلقّي إشعارات عنه. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة الإشعارات
الفورية.
التوزيع المناسب باستخدام حسابات الخدمة
إذا كان تطبيقك يقدّم طلبات باستخدام التفويض على مستوى النطاق، يتم تلقائيًا تحصيل الرسوم من حساب الخدمة في ما يتعلّق بحصص "في الدقيقة لكل مستخدم ولكل مشروع"، وليس من المستخدم الذي تنتحله. هذا يعني أنّ حساب الخدمة من المرجّح أن تنتهي حصته ويتم تقييد المعدّل، على الرغم من أنّه قد يعمل على تقاويم مستخدمين متعددين.
يمكنك تجنُّب ذلك باستخدام مَعلمة عنوان URL quotaUser (أو عنوان HTTP x-goog-quota-user) للإشارة إلى المستخدم الذي يتم تحصيل الرسوم منه. لا يتم استخدام ذلك إلا في عمليات احتساب الحصة. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة الحدّ من الطلبات لكل
مستخدم.
اختبار طريقة التعامل مع حدّ الحصة
للتأكّد من أنّ تطبيقك يمكنه التعامل بشكل سليم مع بلوغ حدود الحصة في الممارسة العملية (على سبيل المثال، من خلال عمليات إعادة المحاولة مع التمهُّل بين عمليات إعادة المحاولة الأسي) ولتقليل أي اضطرابات محتملة لمستخدميك ، ننصحك بشدة باختبار السيناريو في بيئة حقيقية.
لإجراء الاختبار بدون التأثير في استخدام تطبيقك الفعلي، ننصحك بتسجيل مشروع منفصل للاختبار فقط في Google Cloud Console، ثم ضبط شاشة طلب الموافقة على OAuth بطريقة مشابهة لمشروع الإنتاج. يمكنك بعد ذلك ضبط حدود الحصة المنخفضة بشكل مصطنع لهذا المشروع ومراقبة سلوك تطبيقك.