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

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

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

• الحدود القصوى العامة لاستخدام "تقويم Google": واجهة برمجة التطبيقات الخاصة بـ "تقويم Google" هي خدمة مشترَكة تتضمّن قيودًا لحماية الأداء العام لنظام Google Workspace. لمزيد من المعلومات، يُرجى الاطّلاع على تجنُّب حدود استخدام "تقويم Google".

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

حصص 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. إذا لم ينجح الطلب، انتظِر لمدة 2 + random_number_milliseconds وأعِد محاولة إرساله.
4. في حال تعذّر تنفيذ الطلب، انتظِر 4 ثوانٍ + random_number_milliseconds ثم أعِد محاولة تنفيذ الطلب.
5. وهكذا، حتى maximum_backoff مرة.
6. واصِل الانتظار وإعادة المحاولة حتى بلوغ الحدّ الأقصى لعدد المحاولات، ولكن لا تزد فترة الانتظار بين المحاولات.

where:

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

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

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

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

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

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

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

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

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

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

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

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

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

حصص MCP في التقويم

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

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

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

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

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

حصص مجموعة أدوات بروتوكول سياق النموذج (MCP) في التقويم

يوضّح الجدول التالي تكلفة طلب البحث لكل 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".

مواضيع ذات صلة

• إرسال طلبات مجمّعة
• نصائح بشأن الأداء
• تجنُّب تجاوز حدود استخدام "تقويم Google"