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

تتضمّن 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 دقيقة)، ننصح بأن يرصد الرمز البرمجي الاستثناء ويستخدم التمهُّل الأسي الثنائي المقتطع لضمان عدم توليد أجهزتك حملاً مفرطًا.

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

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

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

1. أرسِل طلبًا إلى Google Calendar API.
2. إذا تعذّر إرسال الطلب، انتظِر 1 + random_number_milliseconds وأعِد محاولة إرسال الطلب.
3. إذا تعذّر إرسال الطلب، انتظِر 2 + 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 Calendar API بشكل عادي بدون أي تكلفة إضافية. من المخطط أن يتم تحصيل رسوم من حساب الفوترة على Google Cloud في وقت لاحق من عام 2026 إذا تجاوزت حدود طلبات الحصة. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة نموذج Google Workspace الموحّد لأدوات الوكلاء وواجهات برمجة التطبيقات.

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

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

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

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

• لمحة عن تعديلات الحصة
• الاطّلاع على نسبة استهلاكك من الحصة وحدودها
• طلب حدّ أعلى للحصة

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

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

في هذه الحالة، يمكنك تجربة ما يلي:

1. تأكَّد من اتّباع جميع أفضل الممارسات: استخدام التمهُّل الأسي الثنائي، وترتيب أنماط حركة المرور عشوائيًا، واستخدام الإشعارات الفورية.

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

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

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

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

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

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

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

لتجنُّب ذلك، تأكَّد من توزيع حركة المرور على مدار اليوم قدر الإمكان. إذا كان برنامجك بحاجة إلى إجراء مزامنة يومية، اطلب من البرنامج تحديد وقت عشوائي (مختلف لكل برنامج). إذا كنت بحاجة إلى إجراء عملية بشكل منتظم، غيِّر الفاصل الزمني بنسبة ‎+/- 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"

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

• في الدقيقة لكل مشروع: هي تكلفة طلب البحث لمشروعك على 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

لمزيد من المعلومات، يُرجى الاطّلاع على مرجع Calendar MCP API.

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

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