נתונים חיים (WebSocket)

עם ה-WebSocket אתם מקבלים את המדידות ואת השינויים של המכשירים ברגע שהם קורים. אפליקציית HAM משתמשת באותו חיבור. למדידה אחת בכל פעם, REST API פשוט יותר.

כתובת

wss://DEVICE_SERVER:9001

• DEVICE_SERVER הוא הערך של השדה device_server של כל מכשיר. אתם מוצאים אותו עם get_user_devices.php.
• המכשירים של חשבון אחד יכולים להיות בשרתים שונים. פתחו חיבור אחד לכל שרת שונה, לא חיבור אחד לכל מכשיר.
• פורט 9001 חייב להיות פתוח לחיבורים יוצאים. ראו דרישות רשת (ל-IT).

פורמט ההודעה

כל הודעה שאתם שולחים היא מערך 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.

שמירה על החיבור פתוח

• השרת שולח pings של WebSocket. הספרייה שלכם חייבת לענות עם 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 מכללים