MergenHub Envest

REST API

المصادقة وواجهة الإعدادات والقيم المباشرة والكتابة وSwagger وأمثلة بـ curl.

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

الإعدادات › الويب وREST API — المنفذ وHTTPS وCORS وخيارات الوصول إلى API
الإعدادات › الويب وREST API — المنفذ وHTTPS وCORS وخيارات الوصول إلى API

المصادقة

طريقتان:

  1. ملف تعريف ارتباط الجلسة — يعيد POST /auth/v1/login مع {"username":"…","password":"…"} ملف تعريف ارتباط؛ أرسله مع كل طلب. تتبع الجلسات سياسة الأمان (مهلة الخمول، وتسجيل دخول مفرد/متعدد).
  2. 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/settingsGET/PUTإعدادات الخادم
/config/v1/license/*activate وrefresh وrelease وupdate-checkالترخيص
/config/v1/scada/*screens وlibrary وsymbolsشاشات SCADA
/config/v1/advanced و/aliases و/alarms و/loggerCRUDالإضافات
/runtime/v1/values?tags=A.B.C,…GETالقيم الحية مع الجودة والطوابع الزمنية
/runtime/v1/writePOST {"tag":"A.B.C","value":42}الكتابة إلى جهاز (مع التدقيق)
/runtime/v1/status و/metrics و/services/*GET/POSTالسلامة، والمعالج/الذاكرة، والتحكم في الخدمات
/runtime/v1/events و/auditGETسجلا الأحداث والتدقيق
/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 التفاعلية (يتطلب تسجيل الدخول). وهي تسرد كل مسار مع المخططات وتتيح لك تجربة الاستدعاءات بجلستك.