إرسال القياسات عبر واجهة HTTP API

يمكن لأي نظام قادر على إرسال طلب HTTP بمتن JSON أن يغذّي FreeMaint Connect: Node-RED، أو Home Assistant، أو بوابة تقرأ Modbus، أو متحكم PLC، أو نص برمجي خاص بك. أنشئ اتصالًا من نوع «واجهة HTTP API (Node-RED، نص برمجي…)» للحصول على عنوان URL ومفتاح الوصول الخاصين به.

الطلب

الطريقة: POST، إلى عنوان URL المعروض عند إنشاء الاتصال (ينتهي بـ /connect/ingest/generic).
الترويسة Authorization: Bearer متبوعةً بمفتاح الوصول.
الترويسة Content-Type: application/json.
يرد FreeMaint بالرمز 202 عند قبول البيانات، وتُخزَّن في غضون ثوانٍ.

متن الطلب

يسرد المتن الأجهزة تحت items. لكل جهاز معرّف (device)، واسم عرض اختياري، ووقت اختياري (ts بتنسيق ISO 8601)، ونقاطه. ولكل نقطة key وvalue، ويُستحسن أن تتضمن unit وquantity. تعرض شاشة الإنشاء مثالًا كاملًا يمكنك نسخه.

حقول النقطة

key

اسم القناة على هذا الجهاز، مثل power أو energy_total. المفتاح نفسه يصل دائمًا إلى القناة نفسها.

value

قيمة رقمية.

unit

مثل W أو kWh أو °C أو mm/s. تُحوَّل الطاقة بوحدة Wh أو MWh إلى kWh، ودرجات الحرارة إلى °C، وسرعة الاهتزاز إلى mm/s. تُحوَّل الضغوط بوحدة Pa أو hPa أو kPa أو mbar أو psi أو inH2O أو inWC أو mmH2O إلى bar. لقراءة قناة بوحدة أخرى، اختر وحدة العرض في FreeMaint. تعرض صفحة القناة وحدة آخر قراءة تحت «الوحدة المستلَمة». حالة الأحرف مهمة لبادئتَي ميلي وميغا: mW وmWh تعنيان ميلي، وMW وMWh تعنيان ميغا. تُقبل أيضًا أسماء وحدات BACnet بأحرف كبيرة أو صغيرة: «PASCALS» و«inches-of-water» و«kilowatt-hours»…

quantity

الكمية المقيسة، مثل power أو energy أو temperature أو vibration_velocity. تتيح لـ FreeMaint اختيار الوحدة والمخطط المناسبين.

kind

القيمة CUMULATIVE لعدّاد لا يتناقص أبدًا (إجمالي طاقة، ساعات تشغيل). عندئذٍ يحسب FreeMaint الاستهلاك بين القراءات. احذف هذا الحقل إذا كانت القيمة قياسًا بسيطًا.

الحدود

حتى 500 جهاز و5,000 نقطة في الطلب الواحد.
حتى 120 طلبًا في الدقيقة لكل اتصال؛ وبعد ذلك يرد FreeMaint بالرمز 429، وينبغي أن يعيد نظامك المحاولة لاحقًا.
يتلقى الطلب غير الصحيح الصياغة استجابة 400 تحدد المشكلة، مما يسهّل إصلاح بوابة مضبوطة بشكل خاطئ.
تُحتسب كل قناة جديدة ضمن حد القنوات النشطة في خطتك.

نصيحة

إعدادات نموذجية: تدفق Node-RED يقرأ عداد طاقة Modbus كل دقيقة ويرسل قيمه؛ أو أتمتة Home Assistant تمرّر قراءات حساس؛ أو موجّه Teltonika ترسل ميزة Data to Server فيه القراءات.

تحذير

احفظ مفتاح الوصول سرًّا: فكل من يملكه يستطيع إرسال بيانات إلى هذا الاتصال. إذا احتُمل تسرّبه، فأنشئ مفتاحًا جديدًا واختر «إلغاؤه الآن».