الانتقال إلى المحتوى الرئيسي
عندما تريد إدارة حواجز الحماية كـكود — إنشاء سياسة PII في CI، أو مقارنة نسختين قبل إصدار، أو سحب تغذية التطابقات إلى لوحة تحكّمك الخاصة — تتحدّث إلى مسارات /api/guardrail/*. هذه الصفحة هي مرجع guardrail api مساراً بمسار: كل نقطة نهاية، ودور مساحة العمل الذي تتطلبه، والمصادقة التي تتوقعها. لمعرفة ما هو حاجز الحماية وكيف تتألّف القواعد، اقرأ حواجز الحماية. هذه الصفحة هي المرافق على مستوى السلك.

​
1. المصادقة والنطاق

كل مسار /api/guardrail/* هو مستوى إدارة: يصادق بـجلسة وحدة التحكم أو رمز الوصول (نفس الهوية التي تسجّل بها الدخول إلى وحدة التحكم)، لا مفتاح ترحيل.
مفتاح الترحيل sk-orca-... لديك يصادق استدعاءات النموذج /v1/* — وهو لا يعمل على /api/guardrail/*. مسارات الضبط تستخدم رمز جلسة/وصول مستخدمك، ضمن نطاق مساحة العمل النشطة.
  • المسارات ضمن نطاق مساحة العمل — لا ترى أبداً سوى حواجز حماية مساحة العمل النشطة. لا شيء يعبر حدود مستأجر.
  • كل مسار مُقيَّد بـ RBAC حسب دور مساحة عملك (Viewer / Developer / Admin / Owner). القراءات مفتوحة لـ Viewer+؛ صندوق الرمل وكل الكتابات تتطلب Developer+؛ نقاط نهاية الإيجابية الكاذبة تتطلب Admin (Admin أو Owner).
معظم الفرق لا تستدعي هذه المسارات مباشرة أبداً — وحدة التحكم تقود كلها. لجأ إلى سطح REST عندما تريد حواجز الحماية في التحكّم بالمصدر، أو في CI، أو موصولة بأدواتك الخاصة.

​
2. استدعاء واحد ملموس — اسرد حواجز حمايتك

القراءة أبسط مكان للبدء. مُصادَقاً كأي عضو مساحة عمل (Viewer+): 
curl https://api.orcarouter.ai/api/guardrail/ \
  -H "Authorization: Bearer <your-access-token>" \
  -H "X-Workspace-Id: <workspace-id>"
تستعيد حواجز حماية مساحة العمل مع أعداد المفاتيح المرتبطة بها. لفحص أول طلب لك من البداية إلى النهاية بدلاً من ذلك — أنشئ سياسة، اربط مفتاحاً، أرسل استدعاءً — اتبع البدء السريع في 5 خطوات، الذي يفعل كل ذلك من وحدة التحكم.

​
3. نموذج الأدوار في جدول واحد

الإجراء الذي تتخذه، لا المسار، يختار الطبقة.
الإجراءالدور الأدنى
القراءة (سرد/جلب، تاريخ، تطابقات، تشغيلات تقييم)، تشغيل تقييمViewer+
تشغيل اختبار صندوق رملDeveloper+
إنشاء، تحديث، حذف، استرجاع، رفع/حذف مجموعة نصوصDeveloper+
تعليم / إلغاء تعليم تطابق كإيجابية كاذبةAdmin
تنطبق القراءات على صلاحية guardrails:read (يملكها Viewer فأعلى)؛ وتنطبق الكتابات على guardrails:write (Developer فأعلى). تعليم إيجابية كاذبة يتطلب إضافةً دور Admin. انظر النطاق والمفاتيح والسياسات لكيفية تركيب الأدوار والصلاحيات.

​
4. المسارات حسب المجال

الطريقة والمسارالدور
GET /api/guardrail/Viewer+
GET /api/guardrail/metaViewer+
GET /api/guardrail/my-permissionsأي عضو
GET /api/guardrail/:idViewer+
GET /api/guardrail/:id/tokensViewer+
POST /api/guardrail/testDeveloper+
POST /api/guardrail/Developer+
PUT /api/guardrail/Developer+
DELETE /api/guardrail/:idDeveloper+
تعيد meta مفردات المحرك — أنواع القواعد، والمراحل، والإجراءات، وكيانات PII، والإعدادات المسبقة، وفئات الإعدادات المسبقة — حتى تستطيع أداة بناء نموذج دون ترميز التعدادات بشكل صلب. تشغّل test السياسة الحالية على نص عينة في صندوق رمل: لا شيء يُحفظ، لا شيء يذهب للأعلى.
الطريقة والمسارالدور
GET /api/guardrail/:id/historyViewer+
GET /api/guardrail/:id/history/diffViewer+
GET /api/guardrail/:id/history/:versionViewer+
POST /api/guardrail/:id/revertDeveloper+
كل إنشاء وتحديث وحذف يكتب صف تاريخ في نفس المعاملة. تنسخ revert نسخة قديمة قُدُماً كنسخة جديدة — لا يُعدَّل التاريخ أبداً.
الطريقة والمسارالدور
POST /api/guardrail/:id/evalViewer+
GET /api/guardrail/:id/eval/runsViewer+
GET /api/guardrail/eval/runs/:run_idViewer+
GET /api/guardrail/eval/corporaViewer+
POST /api/guardrail/eval/corporaDeveloper+
GET /api/guardrail/eval/corpora/:idViewer+
DELETE /api/guardrail/eval/corpora/:idDeveloper+
شغّل حاجز حماية مقابل مجموعة نصوص فريق أحمر مدمّجة أو مجموعة JSONL مخصّصة ترفعها، ثم اقرأ الإخفاقات لكل عينة. مفيد لضبط معيار محكِّم أو إثبات أن سياسة تصطاد هجمات معروفة قبل أن تشحن.
الطريقة والمسارالدور
GET /api/guardrail/matchأي عضو
GET /api/guardrail/match/groupedأي عضو
GET /api/guardrail/match/statsأي عضو
GET /api/guardrail/match/exportأي عضو
GET /api/guardrail/match/cap-statusأي عضو
GET /api/guardrail/match/:idأي عضو
POST /api/guardrail/match/:id/mark-fpAdmin
DELETE /api/guardrail/match/:id/mark-fpAdmin
يسجّل التطابق نوع القاعدة، والإجراء، والمرحلة، وسلسلة تفاصيل — بالإضافة إلى السلسلة الفرعية المطابقة فقط إذا كان “Log raw content” مفعّلاً لذلك حاجز الحماية (مطفأ افتراضياً). لا تحمل مسارات القراءة وسيطة صلاحية إضافية، فيستطيع أي عضو مساحة عمل نشط الوصول إليها؛ ومساري mark-fp لـ Admin فقط (Admin أو Owner) ومحدودا المعدل.

​
5. الحل: أي حاجز حماية ينطبق

تدير المسارات أعلاه السياسات؛ ويقرر الحل أيّها يعمل على استدعاء ترحيل بعينه. إنه نموذج صريح-أو-افتراضي بلا تراجع صامت على ربط صريح:
  1. guardrail_id صريح على المفتاح ← ينطبق ذلك حاجز الحماية، إن كان موجوداً ومفعّلاً. الربط المعطّل هو مفتاح الإطفاء — وهو لا يتراجع.
  2. لا ربط ← حاجز الحماية الافتراضي المفعّل لمساحة العمل (is_default).
  3. لا هذا ولا ذاك ← لا فرض. الطلب متطابق بايت ببايت مع مساحة عمل لم تفعّل الميزة أبداً.
هذا هو السلوك الوحيد المختلف عن جدار الحماية: سياسة جدار حماية مرتبطة معطّلة تتراجع إلى افتراضي مساحة العمل، بينما حاجز حماية مرتبط معطّل يُحَل إلى لا شيء. انظر حواجز الحماية مقابل جدار الحماية.
اضبط guardrail_id على مفتاح عبر محرّر المفاتيح أو واجهة الرموز؛ 0/null يعني “لا ربط صريح”.

​
6. ماذا يعيد الحجب

عندما تُطلق قاعدة بإجراء block، يعيد استدعاء الترحيل (/v1/*، على مفتاح ترحيلك) — لا مسارات الإدارة هذه:
الحقلالقيمة
حالة HTTP400
رمز الخطأguardrail_blocked
تكلفة الحصةحجب مرحلة الإدخال يُطلق قبل الاستهلاك المسبق، فلا تُحمَّل أي حصة
إعادة المحاولةمعلَّم skip-retry
تسمّي الرسالة حاجز الحماية والقاعدة التي أُطلقت. لكتالوج الرموز الكامل ومسارات الفرز، انظر رموز الأخطاء و لماذا حُجب طلبي؟.

​
7. الإجراءات والمراحل وأنواع القواعد في لمحة

يعيد مسار meta هذه كتعدادات؛ وها هي للمرجع السريع.
  • الإجراءات: block (رفض، HTTP 400)، mask (نقّح التطابق، مرّر النص المنظَّف)، flag (سجّل فقط — راقب دون تغيير حركة المرور)، annotate (غير حاجب — سجّل التطابق واحقن ملاحظة قابلة للقراءة البشرية للأعلى حتى يُخبَر النموذج عنها قبل أن يجيب)، spotlight (غير حاجب — لفّ المقطع غير الموثوق المطابق بمحدّدات وأخبر النموذج بمعاملته كبيانات، لا تعليمات؛ دفاع ضد حقن المطالبة، في مرحلة الإدخال عملياً).
  • المراحل: input (الطلب)، output (استجابة النموذج)، أو both.
  • أنواع القواعد: keyword، regex، pii، max_chars، external، llm_judge، grounding.
تُفرض قواعد مرحلة الإخراج على كلتا الاستجابتين المتدفّقة وغير المتدفّقة: block يقطع البث، وmask يعيد كتابة المقاطع المطابقة في النطاق مع تدفّق المقاطع. على بثّ، لا يمكن سحب البايتات المُفرَّغة بالفعل، فلا يُتصرَّف بناءً على تطابق إلا بعد أن يُخزَّن مؤقتاً ما يكفي منه — لأقوى ضمان، افحص على مرحلة input، التي تطهّر الطلب قبل أن يراه النموذج أبداً. أثبت تركيبة المرحلة/البث الدقيقة لديك في صندوق الرمل أولاً.
لتجاوزات PII لكل كيان، والكيانات المخصّصة، ومحكِّم LLM، وحقول الترسيخ السياقي، انظر المرجع العميق في حواجز الحماية.

​
8. مراجع ذات صلة

Firewall API

نظير مستوى الإجراء — /api/workspace/firewall/* ومسارات البوابة.

Compliance API

/api/compliance/* — الحزم، والتقارير المُوقَّعة، والإقامة، والجاهزية.

رموز الأخطاء

كل رمز *_blocked، وحالة HTTP له، وماذا تفعل حياله.

حواجز الحماية (غوص عميق)

أنواع القواعد، وكيانات PII، والإعدادات المسبقة، والتقييمات، وتغذية التطابقات بالكامل.
انظر أيضاً حواجز الحماية مقابل جدار الحماية، كيف يفحص OrcaRouter حركة المرور، والمسرد.