إدخال بيانات الأجهزة إلى SaaS الخاص بك

حالة الاستخدام

استخدم هذا النمط عندما تكون قدرة أجهزة WLTE جزءًا من منتجك الخاص (SaaS متعدد المستأجرين، أو نظام تشغيل داخلي، أو ما شابه). يتفاعل مستخدموك النهائيون مع منتجك ونظام حساباتك الخاص — ولا يلمسون بيانات اعتماد WLTE مباشرة أبدًا.

• يدعم حساب WLTE واحد وAPI Client واحد كامل نشرك، وليس بيانات اعتماد لكل عميل نهائي.
• الأجهزة ضمن حساب WLTE مسطّحة؛ لا يوجد مفهوم للمستأجر (tenant). أي الأجهزة تنتمي لأي عميل هو تعيين تملكه وتحافظ عليه أنت.
• تحتاج الأحداث الحيّة إلى التدفق باستمرار إلى مسار بياناتك الخاص (قاعدة بيانات، طابور رسائل، WebSocket أو webhook خاص بك)، بدلًا من أن تحتفظ كل صفحة لكل عميل نهائي باتصالها الخاص بـ WLTE.

لا تُسلّم clientId أو clientSecret أو access token أبدًا لعميل نهائي. لا تفترض أن الأجهزة ضمن حساب واحد معزولة حسب المستأجر — إنها ليست كذلك.

البنية الموصى بها

خدمتك الخلفية فقط تحتفظ ببيانات اعتماد WLTE. حافظ على تعيين deviceId → tenantId، واخدم جميع المستأجرين من اتصال WebSocket واحد، ووزّع البيانات عبر بقية نظامك.

التنفيذ خطوة بخطوة

1. صمّم وحافظ على تعيين deviceId → tenantId (أو معرّف العميل/الموقع الخاص بك). لا تميّز حسابات WLTE بين المستأجرين — هذا الجدول هو بنية البيانات المركزية للتكامل بأكمله.
2. احصل على access token من API Client الواحد لديك، المحفوظ في الخادم: device:read للاستخدام للقراءة فقط، إضافةً إلى device:control أو device:config إذا كنت ترسل أوامر.
3. استدعِ سرد الأجهزة (بالإنجليزية) وسرد تعريفات نوع الجهاز (بالإنجليزية) لبناء خط أساس الحالة الأولي، ثم قسّمه إلى عروض لكل مستأجر باستخدام جدول التعيين لديك.
4. أنشئ تذكرة WebSocket (بالإنجليزية) أحادية الاستخدام وأنشئ اتصالًا واحدًا — وليس واحدًا لكل مستأجر — لاستقبال أحداث الاتصال، وأحداث تغيّر الحالة، وأحداث الطاقة (بالإنجليزية).
5. في كل حدث، ابحث أولًا عن المستأجر بحسب deviceId، ثم اكتب إلى مخزنك أو طابورك الخاص بحيث تستطيع API/WebSocket/webhook لديك دفعه إلى عملاء ذلك المستأجر.
6. عندما يُصدر عميل نهائي طلب تحكم، فوّضه أولًا مقابل نظام صلاحياتك الخاص (صلاحيات منتجك لكل مستأجر، وليس نطاق WLTE)، ثم اجعل خدمتك الخلفية تُوكِّل (proxy) الطلب إلى WLTE بمفتاح تماثلية.
7. خزّن بنفسك نتائج الأوامر والأحداث حيثما تحتاج إلى احتفاظ طويل المدى أو سجل فوترة — لا تعيد WLTE تشغيل سجل الأحداث التاريخي، وتُحفظ سجلات الأوامر لفترة وجيزة فقط.

الواجهات والأحداث الرئيسية

الغرض	المرجع
بناء خط أساس الحالة	سرد الأجهزة (بالإنجليزية)
عروض متعددة المستأجرين موجّهة بالقدرات	سرد تعريفات نوع الجهاز (بالإنجليزية)
إضافة جهاز إلى الحساب	إضافة جهاز إلى الحساب (بالإنجليزية)
مصادقة WebSocket	إنشاء WebSocket Ticket (بالإنجليزية)
تغيّرات الاتصال	أحداث اتصال الجهاز (بالإنجليزية)
تغيّرات حالة الملحقات	حدث تغيّر حالة الجهاز (بالإنجليزية)
إشعارات فقدان الطاقة واستعادتها	أحداث طاقة الجهاز (بالإنجليزية)
توكيل أمر تحكم	إنشاء أمر مرحّل (بالإنجليزية)
الاستعلام عن نتيجة أمر	الحصول على نتيجة أمر (بالإنجليزية)

الفشل والتعافي

• تُحتسب حدود التكرار لكل API Client. يتشارك عدة مستأجرين لحساب واحد ميزانية حد تكرار واحدة — يمكن لمعدل مرتفع من مستأجر واحد استنفاد حصة الحساب بأكمله، لذا حدّد المعدل وضع في طابور على طبقتك الخاصة بدلًا من تمرير معدل طلبات عملائك النهائيين مباشرة إلى WLTE.
• عند فقدان اتصال WebSocket الصاعد، أعِد اتصال ذلك الاتصال الواحد جانب الخادم بدلًا من إعادة الاتصال لكل مستأجر؛ ضع علامة على البيانات النازلة كقديمة محتملة أثناء إعادة الاتصال.
• الأحداث المفقودة أثناء الانقطاع لا تُعاد. أعِد بناء خط أساس الحالة عبر REST بعد إعادة الاتصال، ثم استأنف التحديثات الموجّهة بالأحداث.
• تُحفظ سجلات الأوامر ومفاتيح التماثلية على جانب WLTE لنحو 48 ساعة فقط. خزّن بنفسك نتائج الأوامر والحالة النهائية إذا احتجت نافذة تدقيق أو فوترة أطول.
• عند 429 RATE_LIMITED، انتظر Retry-After. لا تنفّذ حلقة إعادة محاولة مستقلة منفصلة لكل مستأجر في خدمتك الخاصة.

اعتبارات الإنتاج

• يجب ألّا يرى العملاء النهائيون أو يحصلوا أبدًا، تحت أي ظرف، على clientId أو clientSecret أو access token الخاص بـ WLTE — يجب أن تمر كل استدعاء لـ WLTE عبر خدمتك الخلفية.
• نطاقات WLTE الأربعة (device:read/device:control/device:config/device:manage) صلاحيات خشنة على مستوى الحساب. لا تحل محل نموذج صلاحياتك الدقيق الخاص بكل عميل — إنهما طبقتا تفويض منفصلتان.
• عامل تعيين deviceId → tenantId كأهم جدول في نظامك؛ حافظ على مزامنته كلما أُضيفت أو أُزيلت أجهزة من الحساب، أو أضاف العملاء أو أزالوا مواقع، لتجنّب انتقال البيانات إلى المستأجر الخطأ.
• خطّط لميزانية حد التكرار مسبقًا: يُنمّي عدد المستأجرين حجم طلباتك خطيًا، لكن حد تكرار الحساب لا ينمو معه.
• راجع نطاقات التفويض (بالإنجليزية) لاطلاع على تركيبات النطاقات المتاحة، وحدود التكرار وإعادة المحاولة (بالإنجليزية) لأبعاد حد التكرار.

الخطوات التالية

• بناء لوحة مراقبة للأجهزة
• REST API أم WebSocket
• نطاقات التفويض (بالإنجليزية)
• حدود التكرار وإعادة المحاولة (بالإنجليزية)