واجهات API العامة
يحصل كل مفتاح API على حد لكل خطة، مع دفعات للعملاء حسني التصرف وقيمة Retry-After دقيقة للبقية.
البيانات الأساسيةواجهات API
تحديد المعدل
حدود معدل ذرية على الخادم. GCRA بأمر واحد، أو محددات مسماة بالنافذة المنزلقة أو دلو الرموز أو الدلو المتسرب. دون حاجة إلى Lua.
- أمر ذري لكل طلب
- 1
- خوارزميات
- 4
- سكربتات Lua
- 0
الخطوة 1 من 5
مسموح
10 طلبات في الدقيقة للمستخدم 42. يقول الرد إن الطلب مسموح، ويذكر الحد والمتبقي.
جلسة توضيحيةplaying
# مسموح
hotkv> GCRA.LIMIT ratelimit:user:42 60000 10
1) (integer) 0
2) (integer) 10
3) (integer) 9
4) (integer) -1
5) (integer) 6000
عرض متحرك بأوامر HotKV حقيقية وردود توضيحية. انقر على أي خطوة للانتقال إليها. تبقى الأوامر والردود بالإنجليزية، تمامًا كما تكتبها وتراها في HotKV.
المشكلة
واجهة API بلا حدود يفصلها عن الانقطاع عميل واحد سيئ التصرف. والتحقق في شيفرة التطبيق يعني قراءة وحسابًا وكتابة، وتتسلل الطلبات المتزامنة عبر الفجوات بينها. وينتهي الأمر بكثير من الفرق إلى صيانة سكربت Lua لمجرد جعل العملية ذرية.
كيف يتعامل HotKV معها
يقرر GCRA.LIMIT ويسجّل في خطوة واحدة، فلا يستطيع عميلان متزامنان أن يمرا معًا على الحالة نفسها، ويُعاد ملء الحد بسلاسة بدل أن يُصفَّر عند حدود النافذة. وللحدود التي تديرها بالاسم، يُنشئ RATELIMIT.CREATE محددًا بالنافذة المنزلقة أو دلو الرموز أو الدلو المتسرب، مع إحصاءات لما سمح به وما رفضه.
خطوة بخطوة
ما يحدث، أمرًا بأمر
- 01
مسموح
10 طلبات في الدقيقة للمستخدم 42. يقول الرد إن الطلب مسموح، ويذكر الحد والمتبقي.
GCRA.LIMIT ratelimit:user:42 60000 10 - 02
دفعة من روبوت
يستهلك روبوت الكشط حصة الدفعة، ثم يُبلَّغ بمدة الانتظار. والطلب المرفوض لا يغيّر شيئًا.
GCRA.LIMIT ratelimit:bot:7 60000 10 - 03
محدد مسمى لخطة
يحصل عملاء الخطة المجانية على 100 طلب في الدقيقة بنافذة منزلقة.
RATELIMIT.CREATE free_plan 100 60000 ALGO sliding_window - 04
طلب موزون
تكلّف نقطة نهاية التصدير 20 وحدة، فتستهلك جزءًا أكبر من الحصة.
RATELIMIT.CHECK free_plan customer:881 COST 20 - 05
شاهد ما فعله المحدد
الإعدادات والمفاتيح المتتبَّعة ومجاميع الطلبات المسموحة والمرفوضة.
RATELIMIT.STATS free_plan
أين يناسب
سيناريوهات من الواقع
نماذج تسجيل الدخول والتسجيل
تُقيَّد المحاولات لكل IP ولكل حساب لإبطاء هجمات حشو بيانات الاعتماد.
الاستدعاءات الصادرة
تبقى الاستدعاءات إلى API شريك أو مزوّد LLM تحت حصتها عبر كل عامل في الأسطول.
مدمج
ما تحصل عليه
GCRA بأمر واحد
إعادة ملء سلسة مع دفعات، وفحص وتحديث ذريان، ووقت لإعادة المحاولة عند الرفض.
GCRA.LIMITGCRA.RESETمحددات مسماة
النافذة المنزلقة أو دلو الرموز أو الدلو المتسرب، تُنشأ مرة واحدة وتُفحص لكل مفتاح.
RATELIMIT.CREATERATELIMIT.CHECKطلبات موزونة
يمكن أن تُحسب الاستدعاءات المكلفة كعدة طلبات. يأخذ GCRA.LIMIT عددًا، ويأخذ RATELIMIT.CHECK قيمة COST.
COSTالإحصاءات
مجاميع المسموح والمرفوض لكل محدد.
RATELIMIT.STATSأسئلة شائعة
هل أحتاج إلى سكربت Lua لتحديد المعدل؟
لا. يجري كل من GCRA.LIMIT وRATELIMIT.CHECK الفحص كاملًا كأمر ذري واحد.
أيهما أستخدم؟
لا يحتاج GCRA.LIMIT إلى أي إعداد ويعمل على كل خطة. أما المحددات المسماة RATELIMIT.* فتضيف اختيار الخوارزمية والإحصاءات، وهي جزء من خطتي Performance وScale.
كم يكلّف الطلب المرفوض؟
لا شيء. استدعاء GCRA المرفوض يترك المحدد دون تغيير، فلا يُعاقَب العميل الذي يعيد المحاولة أكثر.
حالات استخدام ذات صلة
جرّبه على عبء عملك
يتحدث HotKV بروتوكول Redis، لذا يمكنك توجيه عميل موجود إليه وتشغيل هذه الأوامر نفسها.