واجهة برمجة التكامل — نظرة عامة
واجهة برمجة التكامل في Survanta هي واجهة HTTP برمجية مصممة للأنظمة الخارجية التي تحتاج إلى قراءة بيانات الاستبيانات من حساب Survanta الخاص بالمؤسسة. يشمل المستهلكون النموذجيون أدوات ذكاء الأعمال ومستودعات البيانات ولوحات التقارير وخطوط أنابيب ETL والتطبيقات التحليلية المخصصة التي تبنيها المؤسسة أو جهة تكامل خارجية.
لمن هذه الواجهة البرمجية؟
| نوع المستهلك | مثال |
|---|---|
| أدوات ذكاء الأعمال / التقارير | Power BI وTableau وMetabase لسحب النتائج التجميعية |
| خطوط أنابيب البيانات | وظائف ETL ليلية لاستخراج بيانات الاستجابات إلى مستودع بيانات |
| لوحات المعلومات المخصصة | تطبيقات ويب تبنيها المؤسسة لعرض مؤشرات أداء الاستبيانات |
| جهات التكامل الخارجية | موردون مكلفون ببناء تحليلات نيابة عن المؤسسة |
عملاء التكامل ليسوا مستخدمين بشريين للوحة التحكم. فهم لا يسجلون الدخول، ولا يمتلكون أدوار ASP.NET Identity، وليسوا أعضاء في أي مجموعة صلاحيات. يصادقون حصريًا بمفتاح API يُصدر عبر شاشة إدارة عملاء التكامل بواسطة مسؤول مؤسسة مخوّل أو مستخدم منصة مخوّل يعمل ضمن سياق صالح لمؤسسة محددة.
ما الذي يمكن للواجهة البرمجية الوصول إليه؟
يتحكم في الوصول مجموعة نطاقات التكامل الممنوحة للعميل عند إنشاء المفتاح. النطاقات المتاحة هي:
- ReportsRead — بيانات تعريف الاستبيانات وملخصات الاستجابات التجميعية.
- UsageRead — ملخص استخدام التكامل للمؤسسة.
- RawResponsesRead — صفوف الاستجابات الفردية. هذا النطاق حساس ولا ينبغي منحه إلا عندما يتطلب عقد التكامل ذلك صراحة.
كل استجابة مقيدة بالمؤسسة التي أصدرت مفتاح API المستخدم. لا يمكن لمفتاح صادر عن المؤسسة أ الوصول إلى بيانات المؤسسة ب.
كيف تعمل المصادقة؟
تستخدم جميع طلبات واجهة برمجة التكامل مخطط المصادقة IntegrationApiKey، ويجب أن تتضمن مفتاحًا صالحًا في ترويسة HTTP الخاصة بـ X-Survanta-Api-Key. تتطلب المصادقة عميلًا نشطًا غير ملغى وغير منتهي الصلاحية، ومؤسسة نشطة، ووصول اشتراك مسموحًا، وبقاء العميل ضمن الحد الفعلي التكاملات الخارجية، ونطاقات مفعلة في الخطة. يتطلب ReportsRead وUsageRead إمكانية الوصول إلى API التقارير، ويتطلب RawResponsesRead إمكانية الوصول إلى API الاستجابات الخام. تحدد المصادقة الناجحة سياق المؤسسة، وتحدّث LastUsedAt، وتكتب سجل تدقيق لاستدعاء الواجهة قبل أن تتحقق نقطة النهاية من نطاقها المطلوب.
لا يوجد cookie ولا JWT bearer token ولا جلسة مستخدم في مصادقة واجهة برمجة التكامل.
العلاقة بنظام الصلاحيات
نطاقات واجهة برمجة التكامل بُعد مختلف تماما عن نموذج صلاحيات System وTenant المستخدم من قِبل مستخدمي لوحة التحكم. تُخزَّن النطاقات في سجل عميل التكامل وليس في مجموعات الصلاحيات، وليس لها أي تفاعل مع فرض RequirePermission على مسارات لوحة التحكم.
عنوان URL الأساسي
تُقدَّم جميع نقاط نهاية التكامل تحت بادئة المسار /api/integrations/ على المضيف نفسه للوحة تحكم Survanta. يتحدد المضيف الدقيق بنشر المؤسسة.
الإصدار
الواجهة البرمجية حاليًا غير مرقمة بالإصدارات. لا يتضمن العقد الحالي ضمانًا مثبتًا في المستودع لقناة إشعار مسبق منفصلة، لذلك ينبغي للمستهلكين التحقق من عقود الاستجابة عند الترقية.