كل ما تفعله واجهة الويب يمر عبر REST API نفسها، فكل ما يمكنك النقر عليه يمكنك برمجته. الـ API عبارة عن JSON فوق HTTP(S) على منفذ الويب (الافتراضي 8090) وموثّقة مباشرةً في التطبيق (… › REST API، Swagger UI).

المصادقة
طريقتان:
- ملف تعريف ارتباط الجلسة — يعيد
POST /auth/v1/loginمع{"username":"…","password":"…"}ملف تعريف ارتباط؛ أرسله مع كل طلب. تتبع الجلسات سياسة الأمان (مهلة الخمول، وتسجيل دخول مفرد/متعدد). - HTTP Basic: أرسل
Authorization: Basic …مع كل طلب (للسكربتات والعملاء المتوافقين مع Kepware؛ عبر HTTPS فقط). يحمل الاستدعاء صلاحيات ذلك المستخدم وإجراءاته المعطَّلة ووصوله إلى الموارد. ولقراءة التقارير من الأنظمة الخارجية يُستخدم مفتاح وصول إلى البيانات (Authorization: Bearer mhkey_…).
curl -c c.txt -X POST https://scada.example.com/auth/v1/login \
-H "Content-Type: application/json" -d '{"username":"apiuser","password":"••••"}'
مجموعات نقاط النهاية الرئيسية
| المجموعة | أمثلة | الغرض |
|---|---|---|
/auth/v1/* | login وme وlogout وforgot | المصادقة |
/config/v1/project/* | channels وchannels/{ch}/devices و…/tags (GET/POST/PUT/DELETE) | إعدادات المشروع، بالنموذج نفسه لتصدير JSON |
/config/v1/settings | GET/PUT | إعدادات الخادم |
/config/v1/license/* | activate وrefresh وrelease وupdate-check | الترخيص |
/config/v1/scada/* | screens وlibrary وsymbols | شاشات SCADA |
/config/v1/advanced و/aliases و/alarms و/logger | CRUD | الإضافات |
/runtime/v1/values?tags=A.B.C,… | GET | القيم الحية مع الجودة والطوابع الزمنية |
/runtime/v1/write | POST {"tag":"A.B.C","value":42} | الكتابة إلى جهاز (مع التدقيق) |
/runtime/v1/status و/metrics و/services/* | GET/POST | السلامة، والمعالج/الذاكرة، والتحكم في الخدمات |
/runtime/v1/events و/audit | GET | سجلا الأحداث والتدقيق |
/logger/v1/history?tag=…&from=…&to=… | GET | بيانات الأرشيف |
/iotgateway/* | GET/POST | خادم REST لجسر البيانات المتوافق مع Kepware (راجع جسر البيانات) |
تعيد كتابات الإعدادات 409 عند تعارض الإصدارات (غيّر شخص آخر المشروع)، و402 عند تجاوز حد وسوم الترخيص، و403 عند نقص صلاحية أو تعطيل إجراء أو عندما ترفض صلاحيات الموارد الوصول. وعند الإجراء المعطَّل يذكره الجسم: { "code": 403, "action": "alarms.ack", "message": "Requires 'alarms.ack' permission." }. تُقرأ صلاحيات المستدعي وإجراءاته المعطَّلة عبر GET /auth/v1/me (permissions وdenied)، وفهرس الإجراءات عبر GET /auth/v1/capabilities (actions)؛ انظر الأدوار والصلاحيات.
أمثلة
قراءة ثلاثة وسوم:
curl -b c.txt "http://localhost:8090/runtime/v1/values?tags=Plant.PLC1.Flow,Plant.PLC1.Pressure,Plant.PLC1.Pump1_Run"
[{"tag":"Plant.PLC1.Flow","value":412.6,"quality":"Good","ts":"2026-09-05T10:20:41.008Z"}, …]
كتابة قيمة مرجعية:
curl -b c.txt -X POST http://localhost:8090/runtime/v1/write \
-H "Content-Type: application/json" -d '{"tag":"Plant.PLC1.Setpoint","value":55}'
إنشاء جهاز مع وسومه في استدعاء واحد:
curl -b c.txt -X POST http://localhost:8090/config/v1/project/channels/Plant/devices \
-H "Content-Type: application/json" \
-d '{"name":"PLC2","idString":"10.0.0.6:502","unitId":1,"scanRateMs":1000,
"tags":[{"name":"Flow","address":"40001","dataType":"Float"},{"name":"Run","address":"00001","dataType":"Boolean","readWrite":"RW"}]}'
تصدير/استيراد المشروع كاملاً (تصدير المشروع الكامل واستيراده لا يعملان إلا بحساب Root):
curl -b c.txt http://localhost:8090/config/v1/project/export -o project.json
curl -b c.txt -X POST http://localhost:8090/config/v1/project/import?mode=merge -H "Content-Type: application/json" --data-binary @project.json
حدود المعدل والأمان
- محاولات تسجيل الدخول محدودة المعدل (429 بعد إخفاقات متكررة).
- كل استدعاء يغيّر البيانات يُكتب في سجل التدقيق مع المستخدم وعنوان IP وملخص الحمولة.
- قراءة القيم الحية رخيصة (في الذاكرة)؛ تجنب الاستعلام بأسرع من معدل مسح الجهاز — واشترك عبر OPC UA أو MQTT بدلاً من ذلك للبيانات عالية المعدل.
Swagger / OpenAPI
افتح … › REST API في التطبيق للاطلاع على وثيقة OpenAPI التفاعلية (يتطلب تسجيل الدخول). وهي تسرد كل مسار مع المخططات وتتيح لك تجربة الاستدعاءات بجلستك.
MergenHub