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

بما أنّ Google Chat API هي خدمة مشترَكة، نفرض حصصًا وقيودًا لضمان استخدامها بشكل عادل من قِبل جميع المستخدمين وحماية الأداء العام لـ Google Workspace.

إذا تجاوزت حصة معيّنة، ستتلقّى استجابة برمز حالة HTTP هو 429: Too many requests. قد تؤدي عمليات التحقّق الإضافية من الحدّ الأقصى لمعدّل الطلبات على Chat في الخلفية إلى ظهور استجابة الخطأ نفسها. في حال حدوث هذا الخطأ، عليك استخدام خوارزمية الرقود الأسي الثنائي وإعادة المحاولة لاحقًا. طالما أنّك تلتزم بالحِصص المحدّدة في الدقيقة والمدرَجة في الجداول التالية، ليس هناك حدّ لعدد الطلبات التي يمكنك إرسالها يوميًا.

قد تنطبق أنواع متعدّدة من الحِصص على طرق Chat API، مثل الحِصص لكل مشروع ولكل مساحة ولكل مستخدم.

الحِصص لكل مشروع

تحدّ الحِصص لكل مشروع من معدّل طلبات البحث لمشروع Google Cloud، وبالتالي تنطبق على تطبيق Chat واحد يستدعي طرق Chat API المحدّدة لكل حصة.

يوضّح الجدول التالي حدود طلبات البحث لكل مشروع. يمكنك أيضًا الاطّلاع على هذه الحدود في صفحة "الحِصص".

الحصة لكل مشروع	طرق Chat API	الحدّ (لكل 60 ثانية)
عدد عمليات كتابة الرسائل في الدقيقة	spaces.messages.create spaces.messages.patch spaces.messages.delete	3000
عدد عمليات قراءة الرسائل في الدقيقة	spaces.messages.get spaces.messages.list	3000
عدد عمليات كتابة العضوية في الدقيقة	spaces.members.create spaces.members.delete	300
عدد عمليات قراءة العضوية في الدقيقة	spaces.members.get spaces.members.list	3000
عدد عمليات كتابة المساحة في الدقيقة	spaces.setup spaces.create spaces.patch spaces.delete	60
عدد عمليات قراءة المساحة في الدقيقة	spaces.get spaces.list spaces.findDirectMessage	3000
عدد عمليات كتابة المرفقات في الدقيقة	media.upload	600
عدد عمليات قراءة المرفقات في الدقيقة	spaces.messages.attachments.get media.download	3000
عدد عمليات كتابة التفاعلات في الدقيقة	spaces.messages.reactions.create spaces.messages.reactions.delete	600
عدد عمليات قراءة التفاعلات في الدقيقة	spaces.messages.reactions.list	3000
عدد عمليات كتابة الرموز التعبيرية المخصّصة في الدقيقة	customEmojis.create customEmojis.delete	600
عدد عمليات قراءة الرموز التعبيرية المخصّصة في الدقيقة	customEmojis.get customEmojis.list	3000
عدد عمليات كتابة الأقسام في الدقيقة	users.sections.create users.sections.delete users.sections.patch users.sections.position users.sections.items.move	600
عدد عمليات قراءة الأقسام في الدقيقة	users.sections.list users.sections.items.list	3000
عدد عمليات قراءة التوفّر في الدقيقة	users.availability.get	3000
عدد عمليات كتابة التوفّر في الدقيقة	users.availability.update users.availability.markAsActive users.availability.markAsAway users.availability.markAsDoNotDisturb	3000

الحِصص لكل مساحة

تحدّ الحِصص لكل مساحة من معدّل طلبات البحث في مساحة معيّنة، ويتم مشاركتها بين جميع تطبيقات Chat التي تعمل في تلك المساحة وتستدعي طرق Chat API المدرَجة لكل حصة.

يوضّح الجدول التالي حدود طلبات البحث لكل مساحة:

الحصة لكل مساحة	طرق Chat API	الحدّ (لكل ثانية)
عدد عمليات القراءة في الثانية	media.download spaces.get spaces.members.get spaces.members.list spaces.messages.get spaces.messages.list spaces.messages.attachments.get spaces.messages.reactions.list	15
عدد عمليات الكتابة في الثانية	media.upload spaces.delete spaces.patch spaces.messages.create (تنطبق حدود إضافية على الويب هوك) spaces.messages.delete spaces.messages.patch spaces.messages.reactions.delete	1
عدد عمليات كتابة "إنشاء تفاعل" في الثانية	spaces.messages.reactions.create	5
عدد عمليات كتابة الرسائل في الثانية أثناء استيراد البيانات إلى Google Chat	spaces.messages.create	10

الحِصص لكل مستخدم

تحدّ الحِصص لكل مستخدم من معدّل طلبات البحث لمستخدم Google Chat. تتعلّق طلبات البحث بجميع تطبيقات Chat التي تستدعي طريقة Chat API نيابةً عن مستخدم (باستخدام مصادقة المستخدم).

يوضّح الجدول التالي حدود طلبات البحث لكل مستخدم:

الحصة لكل مستخدم	طرق Chat API	الحدّ (لكل ثانية)
عدد عمليات كتابة الرموز التعبيرية المخصّصة في الثانية	customEmojis.create customEmojis.delete	1
عدد عمليات قراءة الرموز التعبيرية المخصّصة في الثانية	customEmojis.get customEmojis.list	15
عدد عمليات الكتابة في الثانية	users.sections.create users.sections.delete users.sections.patch users.sections.position users.sections.items.move users.availability.update users.availability.markAsActive users.availability.markAsAway users.availability.markAsDoNotDisturb	1
عدد عمليات القراءة في الثانية	users.sections.list users.sections.items.list users.availability.get	15

حدود الاستخدام الإضافية

يمكن أن يؤدي ارتفاع عدد الزيارات إلى واجهة برمجة التطبيقات التي تستهدف المساحة نفسها إلى تفعيل حدود داخلية إضافية لا تظهر في صفحة "الحِصص".

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

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

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

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

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

1. أرسِل طلبًا إلى Google Chat 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 Cloud بمرور الوقت، قد تحتاج إلى زيادة قيم الحِصص. إذا كنت تتوقّع زيادة ملحوظة في الاستخدام في المستقبل القريب، يمكنك طلب تعديلات الحصة بشكل استباقي من صفحة الحِصص وحدود النظام في Google Cloud Console.

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

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

حِصص خادم Chat MCP

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

حِصص Chat MCP

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

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

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

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

نوع حدّ الاستخدام	تكلفة طلب البحث
لكل دقيقة ولكل مشروع	3,000
لكل دقيقة ولكل مستخدم ولكل مشروع	300

مجموعات أدوات Chat MCP

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

نقطة نهاية	الأداة	تكلفة طلب البحث
/mcp/v1	list_messages	1
	search_conversations	10
	search_messages	10
	send_message	10

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