دليل المطوّر
مرجع النطاقات
تتيح لك نطاقات الصلاحيات الدقيقة تحديد ما يمكن لمفتاح API أو عميل OAuth الوصول إليه داخل مساحة العمل.
نظرة عامة
النطاقات سلاسل نصية مفصولة بمسافات ترتبط بمفتاح API أو بعميل OAuth. وعند وصول أي طلب، تتحقّق واجهة API من نطاقات الرمز مقابل العملية المطلوبة. وهو النموذج نفسه المعتمد في GitHub وStripe، مألوف وقابل للتدقيق وسهل الفهم.
النطاقات اختيارية. فإن لم تُحدَّد، تحصل بيانات الاعتماد على وصول كامل إلى مساحة العمل (بما يعادل مشرفًا). ونوصي بمنح الحد الأدنى من النطاقات اللازمة لكل تكامل.
النطاقات
| النطاق | ما يتيحه | الطرق | نقاط النهاية |
|---|---|---|---|
polls:read | قراءة الاستطلاعات ومحتواها وبياناتها الوصفية. | GET | /polls, /polls/{id} |
polls:write | إنشاء الاستطلاعات وتحديثها وحذفها. | POST, PATCH, DELETE | /polls, /polls/{id} |
results:read | قراءة النتائج المجمّعة لكل شريحة وسجل المصوّتين. | GET | /polls/{id}/results, /polls/{id}/responses, /polls/{id}/votes |
responses:write | إرسال الإجابات والأصوات إلى الاستطلاعات. | POST | /polls/{id}/responses, /polls/{id}/votes |
sessions:write | إنشاء الجلسات المباشرة والتحكّم فيها. | POST | /sessions, /sessions/{id}/control |
sessions:read | قراءة حالة الجلسة المباشرة (الحالة، الشريحة الحالية، عدد المشاركين). | GET | /sessions/{id} |
media:write | رفع الوسائط (الصور، YouTube) وتقديمها لاستخدامها في الأسئلة. | POST | /media |
export:read | تنزيل النتائج كملف CSV أو تقرير PDF. | GET | /polls/{id}/export |
ai:write | استخدم الذكاء الاصطناعي لتوليد محتوى الاستطلاعات. | POST | /polls/{id}/branch |
النطاقات على مفاتيح API
تُطبَّق نطاقات مفاتيح API على كل طلب. فالمفتاح المنشأ بمجموعة نطاقات غير فارغة لا يستطيع استدعاء سوى نقاط النهاية التي تغطيها، وأي طلب يحتاج نطاقًا لا يملكه المفتاح يتلقّى 403 insufficient_scope. أما المفتاح المنشأ بلا نطاقات فله وصول كامل إلى مساحة العمل (راجع الوضع الافتراضي أدناه). عيّن نطاقات المفتاح عند إنشائه في بوابة المطوّرين.
النطاقات على عملاء OAuth
يطبّق عملاء OAuth النطاقات عند إصدار الرمز. فعند استدعاء POST /api/oauth/token مع المعامل scope، لا تُمنح إلا النطاقات المسندة إلى العميل وقت إنشائه. وطلب نطاق غير مسند يُسقَط بصمت من الرمز.
وإذا لم يُرسَل scope في طلب الرمز، فإن الرمز يرث جميع النطاقات المسندة إلى العميل (أو وصولًا كاملًا إذا لم يكن للعميل أي نطاقات).
راجع دليل OAuth 2.0 للاطلاع على خطوات الإعداد كاملة.
الوضع الافتراضي (بلا نطاقات محدّدة)
بيانات الاعتماد التي لا نطاقات لها تملك وصولًا كاملًا إلى مساحة العمل، بما يعادل مشرفًا. استخدمها في:
- الأتمتة الشخصية في مساحة عمل تملكها
- النماذج الأولية والتطوير
أما تكاملات الإنتاج المشتركة بين الفرق أو مع أطراف خارجية، فحدّد لها دائمًا الحد الأدنى من النطاقات المطلوبة.
هل لا تزال لديك أسئلة؟
يسعد فريقنا بمساعدتك.