نظرة عامة والمصادقة
واجهة Configuration API متوافقة مع المعايير الصناعية. العنوان الأساسي: http://<host>:8090/config/v1/project.
| المصادقة | HTTP Basic (اسم المستخدم/كلمة المرور) أو ملف تعريف ارتباط جلسة الواجهة. |
| الصيغة | JSON. |
| الصلاحية | تتطلب كل نقطة نهاية صلاحية؛ وصلاحيتا القراءة والكتابة منفصلتان لكل وحدة (انظر الأدوار والصلاحيات). الطلب من دون الصلاحية يعيد 403 وتحمل الرسالة اسم الصلاحية المطلوبة (Requires 'MeteringManage, WaterManage' permission.). وإذا وُجدت الصلاحية لكن ذلك الإجراء معطَّل للمستخدم أعطى محتوى 403 مفتاح الإجراء في الحقل action: { "code": 403, "action": "alarms.ack", "message": "Requires 'alarms.ack' permission." }. كل المفاتيح: مرجع الإجراءات. |
| رموز الحالة | 201 (نجحت جميعها)، 207 (جزئي)، 400 (فشلت جميعها)، 401 (لا بيانات دخول أو غير صالحة)، 403 (لا صلاحية)، 409 (تعارض؛ POST بمعرّف موجود)، 415 (نوع المحتوى غير مدعوم)، 429 (طلبات كثيرة جدًا أو قفل بسبب محاولات دخول خاطئة). |
curl -u admin:PAROLA http://localhost:8090/config/v1/project/channels
ما الذي تغيّر في 3.10.1 (لكاتبي السكربتات)
| أسماء الصلاحيات | يعطي GET /auth/v1/me الصلاحيات كقائمة أسماء (permissions). ويعيد GET /auth/v1/capabilities كل الأسماء وافتراضيات الأدوار والإعدادات المسبقة وتخطيط نافذة الصلاحيات (groups). الأسماء الجديدة: AlarmsManage، DataLoggingManage، Metering، MeteringManage، Water، WaterManage، Reports، ReportsManage، Workflows، WorkflowsManage، DataBridge. |
| فهرس الإجراءات | أُضيف إلى استجابة GET /auth/v1/capabilities الحقل actions: [{ key, cap, module, kind, ui }]، 95 عنصرًا. cap هي الصلاحية الأم للإجراء، و module مفتاح الوحدة في نافذة الصلاحيات، و kind: create | edit | delete | run | export | manage. و ui: true يعني أن الإجراء يُطبَّق في الواجهة فقط (alarms.export، metering.export، water.export: لا نقطة نهاية مستقلة لها في الخادم). |
| الإجراءات المعطَّلة | أُضيف إلى استجابة GET /auth/v1/me الحقل denied: مفاتيح الإجراءات المعطَّلة فعليًا للمستدعي (بعد اتحاد ملفه الخاص ومجموعته؛ وهو فارغ لـ Root ولدور المسؤول). يستطيع العميل النظر في هذه القائمة قبل إظهار زر؛ والعملاء القدامى الذين يتجاهلون الحقل المجهول لا يتأثرون. |
| حفظ القيود (لـ Root فقط) | محتوى POST /auth/v1/users/{name}/permissions هو { permissions, useRoleDefault, restrict }؛ ومحتوى PUT /auth/v1/groups/{name} هو { permissions, restrict }. و restrict مصفوفة مفاتيح الإجراءات المعطَّلة: إذا لم يكن الحقل في المحتوى لم تتغيّر القيود المحفوظة (السكربت القديم لا يحذف القيود)، والمصفوفة الفارغة تزيل القيود، والمفتاح المجهول يعيد 400 (والمفاتيح في الحقل unknown) ولا يُحفظ شيء. وإضافة إجراء جديد إلى قائمة مستخدم منتمٍ إلى مجموعة وبلا صلاحيات خاصة تعيد 400 (reason: "groupProfile"): فالقيد يُمنح للمجموعة. |
| سجلات المستخدمين والمجموعات | GET /auth/v1/users: permissions هي المجموعة الفعلية (الخاصة ∪ المجموعة)؛ و ownPermissions مجموعة المستخدم الخاصة (null إذا لم تكن له صلاحيات خاصة)؛ و restrict و ownRestrict قائمة الإجراءات المعطَّلة الخاصة بالمستخدم؛ و denied النتيجة الفعلية؛ و restrictApplies يبيّن هل تدخل قائمته الخاصة في النتيجة الفعلية (false في دور المسؤول ولدى المستخدم المنتمي إلى مجموعة وبلا صلاحيات خاصة). GET /auth/v1/groups: الحقل restrict في كل مجموعة. |
| نقاط القراءة المرتبطة بإجراء | نقاط القراءة لا تفحص إجراءً؛ والاستثناءات ثلاثة: GET /config/v1/logger/export (log.export)، GET /config/v1/meteringreports/{id}/template (report.download)، GET /uaserver/v1/instance-certificate (cert.instance). وقراءة التقرير بمفتاح الوصول إلى البيانات (mhkey_) تتطلب أيضًا إجراء report.download لدى مالكه. |
| الإعدادات | يعيد GET /config/v1/settings الأقسام التي تستطيع تغييرها فقط مملوءة؛ وتأتي الأقسام الأخرى بالقيم الافتراضية وأسماؤها في قائمة hiddenSections. محاولة تغيير قسم لا تراه تعيد 403؛ وعند الحفظ تُحفظ القيمة المخزَّنة لتلك الأقسام كما هي. والقسم الذي عُطِّل إجراؤه (مثلًا: عند تعطيل settings.opcua القسم opcUa) يدخل قائمة hiddenSections أيضًا؛ ومحتوى 403 لمحاولة تغيير قسم كهذا يحمل أسماء الأقسام (denied) والإجراء (action). وفي استجابة GET /ai/v1/settings الأعلام canProvider و canPrompt و canSkills. |
| الترخيص والصحة | يعطي GET /config/v1/license الحالة فقط من دون صلاحية إعدادات الخادم (limited: true). ويعيد GET /health للطلب البعيد من دون تسجيل دخول product و status و tagCount فقط. |
| إنشاء السجلات | يعيد POST /config/v1/scada/screens و POST /config/v1/logger/groups الرمز 409 إذا حمل المحتوى معرّف سجل موجود؛ استخدم PUT للتحديث. ولا يقبل POST /config/v1/project/import/bundle إلا Content-Type: application/json (415). |
| قفل دخول Basic | 8 كلمات مرور خاطئة خلال 5 دقائق: قفل 5 دقائق لكل اسم مستخدم (429). |
| خلف وكيل | لا تُقبل ترويسات X-Forwarded-* إلا من وكيل موثوق. |
نقاط النهاية الرئيسية
| GET | /config/v1/project — معلومات المشروع |
| GET/POST | /config/v1/project/channels — القنوات |
| GET/POST | …/channels/{ch}/devices — الأجهزة |
| PUT | …/devices/{dev} — تحديث الجهاز |
| POST | …/devices/{dev}/tags — إضافة وسم (مفرد/مصفوفة=دفعة) |
| GET | /runtime/v1/status — العدّادات |
| GET | /runtime/v1/values?prefix=Kanal.Cihaz — القيمة الحية |
| POST | /runtime/v1/write — {"path":"K.C.Tag","value":1} |
أمثلة
# Kanaldaki cihazlar
curl -u admin:PAROLA http://localhost:8090/config/v1/project/channels/Modbus_1/devices
# Değer yaz
curl -u admin:PAROLA -X POST http://localhost:8090/runtime/v1/write \
-H "Content-Type: application/json" -d '{"path":"Modbus_1.Dev1.Setpoint","value":42}'
# Canlı değer oku
curl -u admin:PAROLA "http://localhost:8090/runtime/v1/values?prefix=Modbus_1.Dev1"