مقدمة

تُرسي هذه الصفحة النموذج الأساسي قبل أن تبدأ التكامل. لا تسرد كل معامل من معاملات كل نقطة نهاية (endpoint)؛ بل تشرح الكائنات الرئيسية، وأنماط الطلبات، ونموذج حالة الجهاز، ودورة حياة الأوامر التي تستخدمها WLTE OpenAPI.

إذا كنت تريد فقط تنفيذ أول طلب فورًا، انتقل إلى البدء السريع.

ما هي WLTE OpenAPI؟

صُممت WLTE OpenAPI لأنظمة الخادم (server-side). تتيح لمنصتك قراءة أجهزة WLTE والتحكم فيها ومراقبتها.

القدرات النموذجية تشمل:

• سرد الأجهزة المتاحة لحساب معيّن
• قراءة حالة جهاز واحد وبيانات ملحقاته
• تحميل تعريفات نوع الجهاز والعمليات المدعومة
• إرسال أوامر المرحّلات (relay) وRS485 وأوامر الإعداد
• الاستعلام عن نتائج الأوامر
• استقبال أحداث الجهاز في الوقت الفعلي عبر WebSocket

المفاهيم الأساسية

المفهوم	الوصف
API Client	هوية المُستدعي، تُنشأ في Developer Console لتطبيق واحد
clientId / clientSecret	بيانات اعتماد جانب الخادم تُستخدم للحصول على access token
Access token	رمز قصير المدة يُستخدم لاستدعاء نقاط النهاية المحمية
الجهاز (Device)	جهاز WLTE متاح للحساب
نوع الجهاز (Device Type)	تعريف يصف الملحقات والعمليات المدعومة
حالة الملحقات (Peripheral State)	حالة المرحّلات، والمدخلات الرقمية، والمستشعرات، والمدخلات التناظرية، وملحقات أخرى
الأمر (Command)	طلب تنفيذ عملية واحدة على الجهاز، مثل التحكم في مرحّل، أو نقل بيانات RS485، أو تحديث إعداد
حدث WebSocket	إشعار فوري بتغيّرات الحالة، وتغيّرات الاتصال، وأحداث الطاقة، وما شابه

نموذج التكامل

يجب أن يحتفظ خادمك بـ clientSecret وأن يحصل على access token. لا يجوز للمتصفحات وتطبيقات الجوال والعملاء الآخرين تخزين clientSecret مباشرة.

REST API وWebSocket

REST API وWebSocket لا يحل أحدهما محل الآخر. كل منهما يخدم مسؤوليات مختلفة.

السيناريو	الطريقة الموصى بها
الحصول على access token	REST API
سرد الأجهزة	REST API
تحميل تعريفات نوع الجهاز	REST API
إرسال أوامر إلى جهاز	REST API أو WebSocket، حسب نموذج الاتصال لديك
الاستعلام عن نتائج الأوامر	REST API
تحديث جهاز واحد صراحةً	REST API عبر GET /devices/{deviceId} أو WebSocket عبر device.state.get
مراقبة أحداث الاتصال أو الانقطاع أو الطاقة أو تغيّر الحالة	WebSocket

للتكامل الأول، استخدم REST API للتحقق من المصادقة وسرد الأجهزة واستعلام حالة جهاز واحد. أضِف WebSocket عندما يحتاج منتجك إلى أحداث فورية.

راجع REST API مقابل WebSocket لمقارنة أكثر تفصيلًا.

نموذج حالة الجهاز

يجب تفسير حالة الجهاز بحسب حالة الاستخدام.

البيانات	حالة الاستخدام	الوصف
حالة قائمة الأجهزة	عروض القوائم، لوحات التحكم، المزامنة في الخلفية	بيانات متزامنة بالفعل من قِبل المنصة، مناسبة للعرض الجماعي
الحالة الفورية لجهاز واحد	تحديثات صفحة التفاصيل والتحقق قبل/بعد تنفيذ عملية	يحاول الخادم تحديث ذلك الجهاز بشكل فعّال
أحداث WebSocket	المراقبة المستمرة للحالة	إشعارات فورية بتغيّرات الاتصال، وأحداث الطاقة، وتغيّرات الملحقات، وما شابه

لا تستخدم استعلامات HTTP عالية التردد عبر جميع الأجهزة لمراقبة الملحقات أو حالة الانقطاع أو تغيّرات الطاقة. يجب أن تعتمد المراقبة المستمرة على أحداث WebSocket. بعد إعادة الاتصال، استخدم قائمة الأجهزة أو نقطة نهاية حالة الجهاز الواحد لإعادة إرساء الحالة الحرجة.

نموذج الأوامر

عادةً ما تمر أوامر الأجهزة بمرحلتين:

1. تقبل المنصة الطلب.
2. يؤكد الجهاز النتيجة النهائية، أو تنتهي مهلة الانتظار.

الحالات الشائعة:

الحالة	المعنى
SUCCESS	أكّد الجهاز النتيجة
TIMEOUT	لم تصل أي تأكيد نهائي ضمن نافذة الانتظار
FAILED	فشل الأمر أو رُفض صراحةً
SENT	أُرسل الأمر لكن لا يزال بلا حالة نهائية؛ يظهر هذا عادةً عند الاستعلام عن أمر موجود مسبقًا

لا تُثبت TIMEOUT أن الجهاز لم ينفّذ الأمر. فقد يكون نفّذه بينما تأخّر التأكيد أو فُقد. بالنسبة للأوامر ذات الآثار الجانبية، لا تكرر الطلب دون تروٍّ بعد انتهاء المهلة. اقرأ حالة الجهاز الحالية أولًا، ثم قرّر.

نموذج الصلاحيات والأمان

يستخدم API Client نطاقات (scopes) للتحكم في الوصول. القواعد الشائعة:

• عادةً ما تتطلب الاستعلامات للقراءة فقط device:read
• عادةً ما يتطلب التحكم في الجهاز device:control
• عادةً ما يتطلب إعداد الجهاز device:config
• عادةً ما تتطلب إدارة الجهاز device:manage

إذا أعاد الطلب AUTH_SCOPE_DENIED، تحدّد الاستجابة الصلاحية الناقصة. حدّث صلاحيات API Client في Developer Console واحصل على access token جديد.

حدود الأمان:

• خزّن clientSecret على خادمك فقط
• لا تكتب clientSecret أو access token أو تذاكر WebSocket في كود الواجهة الأمامية أو المستودعات العامة أو السجلات
• بعد تعطيل API Client أو حذفه، تُرفض الرموز الموجودة
• بعد تدوير سر (secret)، حدّث إعداد السر في خادمك واحصل على رمز جديد

مسار التكامل الموصى به

1. أنشئ API Client في Developer Console.
2. استخدم Bruno للتحقق من المصادقة وسرد الأجهزة واستعلام حالة جهاز واحد.
3. حمّل تعريفات نوع الجهاز لتأكيد الملحقات والعمليات المدعومة.
4. اختر REST API أو WebSocket أو كليهما بحسب سير عمل منتجك.
5. ادمج من خادمك باستخدام SDK أو استدعاءات HTTP/WebSocket مباشرة.
6. قبل الإنتاج، راجع الصلاحيات وحدود التكرار وإعادة المحاولة والتماثل (idempotency) وإخفاء السجلات الحساسة.

الخطوة التالية: انتقل إلى البدء السريع.