حدود الاستخدام

تتضمّن Google Calendar API حصصًا لضمان استخدامها بشكل عادل من قِبل جميع المستخدمين. هناك ثلاثة قيود مهمة يجب مراعاتها عند استخدام Calendar API:

  • حصص استخدام واجهة برمجة التطبيقات: يتم فرضها لكل مشروع ولكل مستخدم. لمزيد من المعلومات، يُرجى الاطّلاع على أنواع حصص استخدام Calendar API.

  • حدود الاستخدام العامة في "تقويم Google": واجهة برمجة تطبيقات "تقويم Google" هي خدمة مشتركة لها قيود لحماية الأداء العام لنظام Google Workspace. للمزيد من المعلومات، انظر تجنب حدود استخدام التقويم

  • الحدود التشغيلية: قد يتم فرض هذه الحدود في أي وقت. على سبيل المثال، إذا حاولت الكتابة في تقويم واحد بشكل متتالٍ وسريع.

حصص Calendar API

يتم فرض نوعَين من الحصص:

  • في الدقيقة لكل مشروع: يشير ذلك إلى عدد الطلبات التي يمكن لمشروعك على Google Cloud إجراؤها في دقيقة واحدة.

  • في الدقيقة لكل مستخدم لكل مشروع: يشير ذلك إلى عدد الطلبات التي يمكن لأي مستخدم معيّن إجراؤها في مشروعك على السحابة الإلكترونية. يهدف هذا الحدّ إلى مساعدتك في ضمان توزيع عادل للاستخدام بين المستخدمين.

يتم احتساب الحصص في الدقيقة باستخدام نافذة متحركة. إذا تجاوزت حصتك في الدقيقة الواحدة، سيتم فرض حد على معدل الاستخدام خلال الفترة التالية لضمان بقاء متوسط استخدامك ضمن الحصص المحددة.

يوضّح الجدول التالي هذه الحدود:

نوع الحدّ الأقصى للاستخدام الحدّ
في الدقيقة لكل مشروع ‫10,000 طلب
في الدقيقة لكل مستخدم لكل مشروع ‫600 طلب

حد الفوترة اليومي

يحدّد هذا الحدّ الأقصى لكل يوم لكل مشروع الحدّ الأقصى لعدد الطلبات التي يمكن لمشروعك على Google Cloud استخدامها خلال فترة 24 ساعة قبل تطبيق الرسوم.

ولا يؤدي الاستخدام ضمن هذا الحدّ إلى فرض رسوم إضافية، ولا تتم فوترة حسابك على Google Cloud. ستتم مشاركة تفاصيل الفوترة الكاملة في وقت لاحق من عام 2026، مع إرسال إشعار قبل 90 يومًا على الأقل من سريان أي تغييرات.

ولا يمكنك طلب زيادة هذا الحدّ اليومي.

يوضّح الجدول التالي الحدّ الأقصى:

نوع الحدّ الأقصى الحدّ
في اليوم لكل مشروع ‫1,000,000 طلب

لمزيد من المعلومات، يُرجى الاطّلاع على النموذج الموحّد في Google Workspace لأدوات وواجهات برمجة التطبيقات الخاصة بالوكلاء.

حلّ الأخطاء المتعلّقة بالحصص المستندة إلى الوقت

بالنسبة إلى جميع الأخطاء المستندة إلى الوقت (الحد الأقصى لعدد الطلبات هو N لكل X دقيقة)، ننصحك بأن يرصد الرمز البرمجي الاستثناء ويستخدم تأخيرًا أسيًا مقتطعًا للتأكّد من أنّ أجهزتك لا تُنشئ حملاً زائدًا.

تُعدّ استراتيجية التراجع الأسي استراتيجية عادية لمعالجة الأخطاء في تطبيقات الشبكة. تعيد خوارزمية الرقود الأسي الثنائي محاولة إرسال الطلبات باستخدام أوقات انتظار متزايدة بشكل كبير بين الطلبات، حتى الوصول إلى الحد الأقصى لوقت الرقود. إذا استمر تعذُّر تنفيذ الطلبات، من المهم زيادة حالات التأخير بين الطلبات بمرور الوقت إلى أن يتم تنفيذ الطلب بنجاح.

مثال على الخوارزمية

تعيد خوارزمية الرقود الأسي الثنائي محاولة إرسال الطلبات بشكل أسي، ما يؤدي إلى زيادة وقت الانتظار بين عمليات إعادة المحاولة إلى الحد الأقصى لوقت الرقود. على سبيل المثال:

  1. أرسِل طلبًا إلى Google Calendar API.
  2. إذا تعذّر تنفيذ الطلب، انتظِر لمدة 1 + random_number_milliseconds وأعِد محاولة تنفيذ الطلب.
  3. إذا تعذّر تنفيذ الطلب، انتظِر لمدة ثانيتين + random_number_milliseconds وأعِد محاولة تنفيذ الطلب.
  4. إذا تعذّر تنفيذ الطلب، انتظِر 4 + random_number_milliseconds وأعِد محاولة تنفيذ الطلب.
  5. وهكذا، حتى المرة الـ maximum_backoff.
  6. واصِل الانتظار وإعادة المحاولة حتى الوصول إلى الحد الأقصى لعدد المحاولات، ولكن لا تزد فترة الانتظار بين المحاولات.

حيث:

  • وقت الانتظار هو 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" بدون أي تكلفة إضافية. ومن المتوقّع أن يؤدي تجاوز حدود طلبات الحصة إلى فرض رسوم على حساب الفوترة في Google Cloud في وقت لاحق من عام 2026. لمزيد من المعلومات، يُرجى الاطّلاع على النموذج الموحّد في Google Workspace لأدوات الوكلاء وواجهات برمجة التطبيقات.

طلب زيادة الحصة

بناءً على استخدامك لموارد مشروعك، قد تحتاج إلى طلب تعديل الحصة. تُعتبر طلبات البيانات من واجهة برمجة التطبيقات التي يجريها حساب خدمة على أنّها تستخدم حسابًا واحدًا. لا يضمن التقدم بطلب للحصول على حصة معدَّلة الموافقة. قد تستغرق طلبات تعديل الحصة التي من شأنها زيادة قيمة الحصة بشكل كبير وقتًا أطول للموافقة عليها.

لا تتوفّر الحصص نفسها لجميع المشاريع. مع زيادة استخدامك لـ Google Cloud بمرور الوقت، قد تحتاج إلى زيادة قيم الحصص. إذا كنت تتوقّع زيادة ملحوظة في الاستخدام قريبًا، يمكنك طلب تعديل الحصص بشكل استباقي من صفحة الحصص والحدود القصوى للنظام في Google Cloud Console.

لمزيد من المعلومات، يُرجى الاطّلاع على المراجع التالية:

تحديد المشاكل وحلّها

في حال تجاوز أيّ من الحصتين، سيتم فرض حدّ أقصى على معدّل الزحف وستتلقّى رمز الحالة 403 usageLimits أو رمز الحالة 429 usageLimits ردًا على طلبات البحث التي ترسلها.

إذا حدث ذلك، يمكنك تجربة ما يلي:

  1. احرص على اتّباع جميع أفضل الممارسات: استخدِم تأخير المحاولة الأسي وأنماط الزيارات العشوائية والإشعارات الفورية.

  2. إذا كان مشروعك ينمو ولديك المزيد من المستخدمين، يمكنك طلب زيادة الحصة.

  3. إذا بلغت الحدود القصوى المسموح بها لحصة الاستخدام لكل مستخدم، يمكنك إجراء ما يلي:

    • إذا كنت تستخدم حساب خدمة، يمكنك توزيع الحمل على المستخدمين أو تقسيمه بين حسابات خدمة متعددة.

    • على الرغم من أنّه يمكنك طلب زيادة في الحصة لكل مستخدم، لا يُنصح بشكل عام بزيادتها عن القيمة التلقائية لأنّ تطبيقك قد يبدأ في الوصول إلى أنواع أخرى من الحدود، مثل حدود الاستخدام العامة للتقويم أو حدود التشغيل.

  4. اختبِر حدود الحصة من خلال تسجيل مشروع تجريبي منفصل له إعدادات مشابهة لمشروع الإنتاج. لمزيد من المعلومات، يُرجى الاطّلاع على اختبار معالجة الحدّ الأقصى للحصة.

تغيير أنماط حركة المرور عشوائيًا

تكون برامج "تقويم Google" عرضة لأنماط الزيارات المتقطعة الناتجة عن إجراء عدة برامج لعمليات في الوقت نفسه. على سبيل المثال، من الممارسات السيئة الشائعة لعميل "تقويم Google" إجراء مزامنة كاملة في منتصف الليل. سيؤدي ذلك بالتأكيد إلى تجاوز حصتك في الدقيقة وسيؤدي إلى تقييد معدل الطلبات والتراجع.

ولتجنّب ذلك، تأكَّد من توزيع الزيارات على مدار اليوم كلما أمكن. إذا كان العميل بحاجة إلى إجراء مزامنة يومية، اطلب منه تحديد وقت عشوائي (مختلف لكل عميل). إذا كنت بحاجة إلى إجراء عملية بشكل منتظم، يمكنك تغيير الفاصل الزمني بنسبة +/- 25%. سيؤدي ذلك إلى توزيع عدد الزيارات بشكل متساوٍ أكثر وتقديم تجربة أفضل للمستخدمين.

استخدام الإشعارات الفورية

من حالات الاستخدام الشائعة تنفيذ إجراء كلما حدث تغيير في تقويم المستخدم. من الأنماط المضادة هنا إجراء استطلاع متكرر لكل تقويم مهم. سيؤدي ذلك إلى استهلاك حصتك بالكامل بسرعة كبيرة. على سبيل المثال، إذا كان تطبيقك يضم 5,000 مستخدم ويستطلع تقويم كل مستخدم مرة واحدة في الدقيقة، يتطلب ذلك حصة في الدقيقة لا تقل عن 5,000، حتى قبل تنفيذ أي عمل.

يمكن للتطبيقات من جهة الخادم التسجيل لتلقّي الإشعارات الفورية، ما يتيح لنا إعلامك عند حدوث أمر يهمّك. يتطلّب إعداد هذه الميزات المزيد من العمل، ولكنّها تتيح استخدام حصتك بشكل أكثر فعالية، وتوفّر تجربة أفضل للمستخدمين. تأكَّد من تحديد eventType التي تريد تلقّي إشعارات بشأنها. لمزيد من المعلومات، يُرجى الاطّلاع على الإشعارات الفورية.

التخصيص المناسب مع حسابات الخدمة

إذا كان تطبيقك ينفّذ طلبات باستخدام التفويض على مستوى النطاق، يتم تلقائيًا تحصيل رسوم من حساب الخدمة في ما يتعلّق بحصص "في الدقيقة لكل مستخدم لكل مشروع"، وليس من المستخدم الذي تنتحل هويته. وهذا يعني أنّ حساب الخدمة سيستنفد على الأرجح حصته وسيتم تقييد معدله، على الرغم من أنّه قد يعمل على تقاويم عدة مستخدمين.

يمكنك تجنُّب ذلك باستخدام مَعلمة عنوان URL‏ quotaUser (أو عنوان HTTP‏ x-goog-quota-user) لتحديد سلسلة عشوائية (تصل إلى 40 حرفًا) تحدّد بشكل فريد كل مستخدم مميّز. تستخدم واجهة برمجة التطبيقات Calendar API هذه القيمة فقط لاحتساب الحصص.

لاستخدام quotaUser لفرض حدود معدّل الطلبات لكل مستخدم على مستوى مستخدمين مختلفين، يجب أن تستوفي طلباتك المتطلبات التالية:

  • تضمين مفتاح واجهة برمجة تطبيقات محظور حسب عنوان IP: يمكنك تمرير مفتاح واجهة برمجة التطبيقات في مَعلمة طلب البحث key، وضبط هذا المفتاح باستخدام قيود عنوان IP التي تحدّد عناوين IP العامة لخوادم الخلفية. في حال حذف مفتاح واجهة برمجة التطبيقات أو عدم ضبط قيود عنوان IP، ستتجاهل واجهة برمجة التطبيقات Calendar API المَعلمة quotaUser وستخصم من الحصة المتاحة لحساب Authenticator (مثل حساب الخدمة).

  • حذف عنوان X-Goog-User-Project: لا يتم إرسال عنوان HTTP‏ X-Goog-User-Project في الطلبات التي تستخدم quotaUser. يؤدي توفير مشروع مستخدم إلى إلغاء مفتاح واجهة برمجة التطبيقات لتحديد الحصة، لذا تتجاهل Calendar API السمة quotaUser.

لمزيد من المعلومات، يُرجى الاطّلاع على تحديد الطلبات لكل مستخدم.

اختبار التعامل مع الحدّ الأقصى للحصة

للتأكّد من أنّ تطبيقك يمكنه التعامل بسلاسة مع بلوغ حدود الحصة عمليًا (على سبيل المثال، من خلال إعادة المحاولة مع تأخير أسي) ولتقليل أي اضطرابات محتملة للمستخدمين، ننصح بشدة باختبار السيناريو في بيئة حقيقية.

لإجراء الاختبار بدون تداخل مع استخدام التطبيق الفعلي، ننصحك بتسجيل مشروع منفصل مخصّص للاختبار فقط في Google Cloud Console ثم ضبط شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth بطريقة مشابهة لمشروع الإنتاج. يمكنك بعد ذلك ضبط حدود الحصص المنخفضة بشكل مصطنع لهذا المشروع ومراقبة سلوك تطبيقك.

الحصص المتاحة لخادم MCP في "تقويم Google"

يستخدم خادم MCP في "تقويم Google" مقياسًا لتخصيص تكلفة طلبات البحث. توضّح الجداول التالية تكلفة طلب البحث لكل طريقة من طرق خادم MCP في "تقويم Google" حسب القسم:

حصص بروتوكول سياق النموذج (MCP) في "تقويم Google"

يتم فرض نوعَين من الحصص:

  • في الدقيقة لكل مشروع: هذه هي تكلفة طلب البحث لمشروعك على Google Cloud لمدة دقيقة واحدة.

  • في الدقيقة لكل مستخدم لكل مشروع: هذه هي تكلفة طلب البحث لمشروعك على السحابة الإلكترونية على Google Cloud في الدقيقة الواحدة التي يمكن لأي مستخدم معيّن استخدامها.

يوضّح الجدول التالي هذه الحصص:

نوع الحدّ الأقصى للاستخدام تكلفة طلب البحث
في الدقيقة لكل مشروع 10,000
في الدقيقة لكل مستخدم لكل مشروع 600

الحصص المخصّصة لمجموعة أدوات MCP في "تقويم Google"

يوضّح الجدول التالي تكلفة طلب البحث لكل مجموعة أدوات calendarmcp.googleapis.com:

نقطة نهاية الأداة تكلفة طلب البحث

/mcp/v1

create_event

1

delete_event

10

get_event

1

list_events

1

respond_to_event

1

search_events

1

update_event

1

suggest_time

1

list_calendars

1

لمزيد من المعلومات، يُرجى الاطّلاع على مرجع واجهة برمجة التطبيقات MCP لـ "تقويم Google".