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

بما أنّ 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

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

تحدّ الحِصص لكل مساحة من معدّل طلبات البحث في مساحة معيّنة، ويتم مشاركتها بين جميع تطبيقات 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	1
عدد عمليات قراءة الأقسام في الثانية	users.sections.list users.sections.items.list	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.

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

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