البيانات المباشرة (WebSocket)

مع الـ WebSocket تحصل على قراءات الأجهزة وتغييراتها في لحظة حدوثها. يستخدم تطبيق HAM الاتصال نفسه. لقراءة واحدة في كل مرة، REST API أبسط.

العنوان

wss://DEVICE_SERVER:9001

• DEVICE_SERVER هو قيمة الحقل device_server لكل جهاز. تجده بـ get_user_devices.php.
• يمكن أن تكون أجهزة حساب واحد على خوادم مختلفة. افتح اتصالًا واحدًا لكل خادم مختلف، وليس لكل جهاز.
• يجب أن يكون المنفذ 9001 مفتوحًا للاتصالات الصادرة. انظر متطلبات الشبكة.

تنسيق الرسالة

كل رسالة ترسلها مصفوفة JSON:

[command_id, payload]

command_id عدد صحيح. ابدأ من 1 وزده مع كل رسالة. للرد command_id نفسه.

الحجم الأقصى للرسالة 20 KiB. يغلق الخادم الاتصال إذا أرسلت رسالة أكبر.

1. المصادقة

الرسالة الأولى بعد الاتصال هي المصادقة:

[1, {"api_key": "YOUR_API_KEY"}]

يمكنك أيضًا إرسال {"access_token": "YOUR_ACCESS_TOKEN"}. انظر المصادقة.

الرد	المعنى
[]	نجاح
["Access Denied"]	مفتاح أو رمز خاطئ. يغلق الخادم الاتصال.
[1,[{},"Rate limit"]]	اتصالات كثيرة جدًا في وقت قصير

حد الاتصالات: 15 كل 60 ثانية لمفتاح API واحد. 25 كل 60 ثانية لرمز وصول واحد.

2. الاشتراك في الأجهزة (SUBSCRIBE)

[2, {"c": "SUBSCRIBE", "server": true, "serialnos": ["e11:123", "e9:456"], "unsubscribe-others": true}]

الحقل	المعنى
c	SUBSCRIBE
server	دائمًا true
serialnos	الأرقام التسلسلية للأجهزة على هذا الخادم
unsubscribe-others	true: يوقف الخادم الاشتراكات السابقة لهذا الاتصال

الرد: [2,[{},""]]. يتخطى الخادم الأجهزة التي ليس لديك وصول إليها. لا يرسل خطأ عنها.

لإيقاف كل الاشتراكات، أرسل [3, {"c": "UNSUBSCRIBE", "server": true}].

3. تحديثات الحالة

بعد الاشتراك مباشرة، يرسل الخادم الحالة الحالية لكل جهاز. بعد ذلك يرسل تحديثًا في كل مرة يتغير فيها شيء.

التحديثات كائنات JSON، وليست مصفوفات:

{
  "serialno": "e11:123",
  "R": { "T": 2082, "GI": 1, "GIC": 0, "GI2": 1, "GI2C": 0 },
  "O": [],
  "alarms": [],
  "is_local": false
}

الحقل	المحتوى
serialno	الجهاز
R	القراءات، خام، حسب رمز القراءة
O	قيم المخرجات، بترتيب output_names
T	الجداول الزمنية للجهاز
S	إعدادات الجهاز
previous	القيم المتراكمة للفترة السابقة، للأجهزة التي فيها عدادات
alarms	الإنذارات النشطة
is_local	true إذا كان اتصالك والجهاز على الشبكة نفسها

• يمكن أن يحتوي التحديث فقط على الحقول التي تغيرت. ادمجه في الحالة التي لديك.
• يجمع الخادم التغييرات لمدة 100 ms تقريبًا قبل أن يرسل تحديثًا.
• تجاهل الرسائل التي لا تعرفها.

لتحويل القيم الخام، استخدم تعريفات العائلة. انظر REST API.

إبقاء الاتصال مفتوحًا

• يرسل الخادم WebSocket pings. يجب أن ترد مكتبتك بـ pong. أغلب المكتبات تفعل ذلك تلقائيًا.
• إذا أُغلق الاتصال، فاتصل مرة أخرى. ينتظر التطبيق 100 ms في المرة الأولى و10 ثوانٍ بعد ذلك.
• بعد اتصال جديد، أرسل المصادقة والاشتراك مرة أخرى.

مثال Node.js

في Node.js 22 يوجد WebSocket مدمج.

const ws = new WebSocket('wss://DEVICE_SERVER:9001');
let id = 1;

ws.onopen = () => {
  ws.send(JSON.stringify([id++, { api_key: 'YOUR_API_KEY' }]));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (Array.isArray(msg) && msg.length === 0) {
    ws.send(JSON.stringify([id++, {
      c: 'SUBSCRIBE', server: true,
      serialnos: ['e11:123'], 'unsubscribe-others': true
    }]));
  } else if (!Array.isArray(msg) && msg.serialno) {
    console.log(msg.serialno, msg.R);
  }
};

يوجد مثال Node.js كامل في nodejs_hamapi_example.zip. يحتوي على المكتبة hamapi.js والملف example.js.

1. في example.js، اضبط server وapi_key والأرقام التسلسلية.
2. شغّل npm install، ثم node example.js.

لا تتصل المكتبة مرة أخرى عندما يُغلق الاتصال. أضف ذلك إلى الكود الخاص بك.

انظر أيضًا

• REST API
• Webhooks من القواعد