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

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

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

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

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

حصص Calendar API

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

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

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

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

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

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

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

يحدّد هذا الحد لكل مشروع في اليوم الحد الأقصى لعدد الطلبات التي يمكن لمشروعك على السحابة الإلكترونية استخدامها خلال فترة 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. إذا بلغت الحدود القصوى المسموح بها لحصة الاستخدام لكل مستخدم، يمكنك إجراء ما يلي:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

نوع الحدّ الأقصى للاستخدام	تكلفة طلب البحث
في الدقيقة لكل مشروع	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"