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

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

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

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

الحصص المحدّدة لكل مشروع

تحدّ حصص كل مشروع من معدّل طلبات البحث لمشروع Google Cloud، وبالتالي تنطبق على تطبيق Chat واحد يستدعي طرق 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
عدد رسائل CustomEmoji في الدقيقة	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 المدرَجة لكل حصة.

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

الحصة لكل مساحة	طُرق واجهة برمجة التطبيقات للدردشة	الحدّ (في الثانية)
عمليات القراءة في الثانية	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
عدد عمليات الكتابة في Reaction في الثانية	spaces.messages.reactions.create	5
عدد عمليات كتابة الرسائل في الثانية أثناء استيراد البيانات إلى Google Chat	spaces.messages.create	10

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

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

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

الحصة لكل مستخدم	طُرق واجهة برمجة التطبيقات للدردشة	الحدّ (في الثانية)
عدد عمليات الكتابة في الثانية لرموز Emoji المخصّصة	customEmojis.create customEmojis.delete	1
عدد قراءات CustomEmoji في الثانية	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. واصِل الانتظار وإعادة المحاولة حتى الوصول إلى الحدّ الأقصى لعدد المحاولات، ولكن لا تزد فترة الانتظار بين المحاولات.

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

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

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