MQTT.js
Release 5.10.3
MQTT.JS هي مكتبة عميل لبروتوكول MQTT ، مكتوبة في JavaScript لـ Node.js والمتصفح.
MQTT.JS هو مشروع مفتوح المصدر مفتوح ، راجع القسم المساهم لمعرفة معنى هذا.
v5.0.0 (07/2023)
MqttClient new مطلوب الآن.V4.0.0 (تم إصداره 04/2020) يزيل دعم جميع إصدارات عقدة نهاية الحياة ، ويدعم الآن العقدة V12 و V14. كما أنه يضيف تحسينات على تسجيل تصحيح الأخطاء ، إلى جانب بعض إضافات الميزات.
كتغيير كسر ، يتم تضمين معالج الأخطاء افتراضيًا في عميل MQTT.JS ، لذلك إذا تم تنبعث أي أخطاء ولم ينشئ المستخدم معالج حدث على العميل للأخطاء ، فلن ينفصل العميل نتيجة للأخطاء غير المعروفة. بالإضافة إلى ذلك ، تمت إضافة أخطاء TLS النموذجية مثل ECONNREFUSED ، ECONNRESET إلى قائمة من أخطاء TLS التي ستنبعث من عميل MQTT.JS ، وبالتالي يمكن التعامل معها كأخطاء اتصال.
يضيف V3.0.0 دعم MQTT 5 ، ودعم العقدة v10.x ، والعديد من الإصلاحات لتحسين الموثوقية.
ملاحظة: دعم MQTT V5 هو تجريبي لأنه لم يتم تنفيذه من قبل الوسطاء حتى الآن.
V2.0.0 يزيل دعم Node V0.8 و V0.10 و V0.12 ، وهو أسرع 3x في إرسال الحزم. كما أنه يزيل جميع الوظائف التي تم إهمالها في V1.0.0 ، وخاصة mqtt.createConnection و mqtt.Server . من v2.0.0 ، تتم استعادة الاشتراكات عند إعادة الاتصال إذا clean: true . V1.xx موجود الآن في LTS ، وسيستمر في دعمه طالما أن هناك مستخدمين V0.8 و V0.10 و V0.12.
كتغيير كسر ، تتم إزالة خيار encoding في العميل القديم ، والآن كل شيء هو UTF-8 باستثناء password في رسالة الاتصال payload في رسالة النشر ، والتي هي Buffer .
تغيير آخر في كسر هو أن MQTT.JS الآن الافتراضيات إلى MQTT V3.1.1 ، وذلك لدعم الوسطاء القدامى ، يرجى قراءة Doc خيارات العميل.
v1.0.0 يحسن البنية الإجمالية للمشروع ، الذي يتم تقسيمه الآن إلى ثلاثة مكونات: MQTT.JS يحتفظ بالعميل ، ويتضمن اتصال MQTT رمز اتصال Barebone للاستخدام من جانب الخادم ، ويتضمن MQTT-Packet محلل البروتوكول والمولد. يعمل العميل الجديد على تحسين الأداء بعامل بنسبة 30 ٪ ، ويتم تضمين دعم WebSocket (تم إهمال MOWs الآن) ، ولديه دعم أفضل لـ QOS 1 و 2. لا يزال واجهة برمجة التطبيقات السابقة مدعومة ولكنها تم إهمالها ، على هذا النحو ، لم يتم توثيقها في هذه القراءة.
npm install mqtt --saveمن أجل البساطة ، دعنا نضع المشترك والناشر في نفس الملف:
const mqtt = require ( "mqtt" ) ;
const client = mqtt . connect ( "mqtt://test.mosquitto.org" ) ;
client . on ( "connect" , ( ) => {
client . subscribe ( "presence" , ( err ) => {
if ( ! err ) {
client . publish ( "presence" , "Hello mqtt" ) ;
}
} ) ;
} ) ;
client . on ( "message" , ( topic , message ) => {
// message is Buffer
console . log ( message . toString ( ) ) ;
client . end ( ) ;
} ) ;الإخراج:
Hello mqttيمكن استخدام MQTT.JS في التطبيقات الأصلية React. لاستخدامه ، انظر المثال الأصلي React
إذا كنت ترغب في تشغيل وسيط MQTT الخاص بك ، فيمكنك استخدام Mosquitto أو Aedes-Cli ، وإطلاقه.
يمكنك أيضًا استخدام مثيل اختبار: test.mosquitto.org.
إذا كنت لا ترغب في تثبيت وسيط منفصل ، فيمكنك محاولة استخدام Aedes.
const mqtt = require ( "mqtt" ) // require mqtt
const client = mqtt . connect ( "mqtt://test.mosquitto.org" ) // create a client import mqtt from "mqtt" ; // import namespace "mqtt"
let client = mqtt . connect ( "mqtt://test.mosquitto.org" ) ; // create a client import { connect } from "mqtt" ; // import connect from mqtt
let client = connect ( "mqtt://test.mosquitto.org" ) ; // create a client MQTT.JS يحدد الأمر للتفاعل مع وسيط. من أجل توفيره على مسارك ، يجب عليك تثبيت MQTT.JS على مستوى العالم:
npm install mqtt -gثم ، على محطة واحدة
mqtt sub -t ' hello ' -h ' test.mosquitto.org ' -vعلى آخر
mqtt pub -t ' hello ' -h ' test.mosquitto.org ' -m ' from MQTT.js ' انظر mqtt help <command> للحصول على مساعدة الأمر.
يستخدم MQTT.JS حزمة التصحيح لأغراض تصحيح الأخطاء. لتمكين سجلات التصحيح ، أضف متغير البيئة التالي في وقت التشغيل:
# ( example using PowerShell, the VS Code default )
$env:DEBUG='mqttjs*' جزء مهم من أي اتصال WebSocket هو ما يجب القيام به عند انخفاض الاتصال ويحتاج العميل إلى إعادة الاتصال. لدى MQTT دعم إعادة الاتصال المدمج الذي يمكن تكوينه لتصرف بطرق تناسب التطبيق.
transformWsUrl (WebSocket فقط)عندما يسقط اتصال MQTT ويحتاج إلى إعادة الاتصال ، من الشائع أن تتطلب أن يتم الحفاظ على أي مصادقة مرتبطة بالاتصال مع آلية المصادقة الأساسية. على سبيل المثال ، قد تمر بعض التطبيقات برمز مصادقة مع خيارات الاتصال على الاتصال الأولي ، في حين قد تتطلب الخدمات السحابية الأخرى توقيع عنوان URL مع كل اتصال.
بحلول الوقت الذي يحدث فيه إعادة الاتصال في دورة حياة التطبيق ، قد تكون بيانات AUTH الأصلية قد انتهت صلاحيتها.
لمعالجة هذا ، يمكننا استخدام خطاف يسمى transformWsUrl لمعالجة أي من عنوان URL للاتصال أو خيارات العميل في وقت إعادة الاتصال.
مثال (تحديث ClientId واسم المستخدم على كل إعادة توصيل):
const transformWsUrl = ( url , options , client ) => {
client . options . username = `token= ${ this . get_current_auth_token ( ) } ` ;
client . options . clientId = ` ${ this . get_updated_clientId ( ) } ` ;
return ` ${ this . get_signed_cloud_url ( url ) } ` ;
}
const connection = await mqtt . connectAsync ( < wss url > , {
... ,
transformWsUrl : transformUrl ,
} );الآن في كل مرة يتم فيها فتح اتصال WebSocket جديد (نأمل ألا يكون ذلك كثيرًا) ، سنحصل على عنوان URL جديد موقّعًا أو بيانات رمزية جديدة.
ملاحظة: لا يدعم هذا الخطاف حاليًا الوعود ، مما يعني أنه من أجل استخدام أحدث رمز للمصادقة ، يجب أن يكون لديك بعض الآلية الخارجية التي تعمل على التعامل مع المصادقة على مستوى التطبيق بحيث يمكن لاتصال WebSocket ببساطة الحصول على أحدث رمز أو عنوان URL الموقّع.
createWebsocket (WebSocket فقط)عندما تحتاج إلى إضافة محول أو رأس مخصص لـ WebSocket لفتح اتصال من خلال وكيل مع مصادقة مخصصة ، يتيح لك هذا الاتصال إنشاء مثيل خاص بك من WebSocket والذي سيتم استخدامه في عميل MQTT.
const createWebsocket = ( url , websocketSubProtocols , options ) => {
const subProtocols = [
websocketSubProtocols [ 0 ] ,
'myCustomSubprotocolOrOAuthToken' ,
]
return new WebSocket ( url , subProtocols )
}
const client = await mqtt . connectAsync ( < wss url > , {
... ,
createWebsocket : createWebsocket ,
} );reconnectPeriod للتأكد من أن عميل MQTT يحاول تلقائيًا إعادة الاتصال عند إسقاط الاتصال ، يجب عليك تعيين خيار العميل reconnectPeriod إلى قيمة أكبر من 0. ستؤدي قيمة 0 إلى تعطيل إعادة الاتصال ثم إنهاء الاتصال النهائي عند انخفاضه.
القيمة الافتراضية هي 1000 مللي ثانية مما يعني أنه سيحاول إعادة توصيل ثانية واحدة بعد فقدان الاتصال.
لاحظ أن هذا سيمكن فقط إعادة الاتصال بعد مهلة اتصال ، أو بعد اتصال ناجح. لن يمكّن (افتراضيًا) الاتصالات التي يتم رفضها بنشاط بخطأ Connack بواسطة الخادم.
لتمكين إعادة الاتصال التلقائي لأخطاء Connack ، قم بتعيين reconnectOnConnackError: true .
إذا قام العميل بتعيين الخيار autoUseTopicAlias:true ، فإن mqtt.js يستخدم اسم الاسم المستعار للموضوع الحالي تلقائيًا.
سيناريو مثال:
1. PUBLISH topic: ' t1 ' , ta:1 (register)
2. PUBLISH topic: ' t1 ' - > topic: ' ' , ta:1 (auto use existing map entry)
3. PUBLISH topic: ' t2 ' , ta:1 (register overwrite)
4. PUBLISH topic: ' t2 ' - > topic: ' ' , ta:1 (auto use existing map entry based on the receent map)
5. PUBLISH topic: ' t1 ' (t1 is no longer mapped to ta:1)لا يحتاج المستخدم إلى إدارة الموضوع الذي يتم تعيينه إلى أي موضوع اسمه. إذا أراد المستخدم تسجيل الاسم المستعار للموضوع ، فقم بنشر الموضوع باستخدام Topic Toffice. إذا أراد المستخدم استخدام الاسم المستعار للموضوع ، فانتشر موضوعًا بدون اسم "اسم". إذا كان هناك اسم مستعار تم تعيينه ، ثم أضفته كخاصية وقم بتحديث الموضوع إلى سلسلة فارغة.
إذا قام العميل بتعيين الخيار autoAssignTopicAlias:true ، فإن MQTT.JS يستخدم الاسم المستعار للموضوع الحالي تلقائيًا. في حالة عدم وجود اسم مستعار للموضوع ، قم بتعيين اسم مستعار جديد للموضوع الشاغر تلقائيًا. إذا تم استخدام الاسم المستعار للموضوع بالكامل ، فسيتم كتابة إدخال LRU (الأقل استخدامًا مؤخرًا).
سيناريو مثال:
The broker returns CONNACK (TopicAliasMaximum:3)
1. PUBLISH topic: ' t1 ' - > ' t1 ' , ta:1 (auto assign t1:1 and register)
2. PUBLISH topic: ' t1 ' - > ' ' , ta:1 (auto use existing map entry)
3. PUBLISH topic: ' t2 ' - > ' t2 ' , ta:2 (auto assign t1:2 and register. 2 was vacant)
4. PUBLISH topic: ' t3 ' - > ' t3 ' , ta:3 (auto assign t1:3 and register. 3 was vacant)
5. PUBLISH topic: ' t4 ' - > ' t4 ' , ta:1 (LRU entry is overwritten)كما يمكن للمستخدم تسجيل زوج المواضيع-alias يدويًا باستخدام Publish Topic: "البعض" ، TA: X. إنه يعمل بشكل جيد مع تعيين الاسم المستعار للموضوع التلقائي.
mqtt.connect()mqtt.connectAsync()mqtt.Client()mqtt.Client#connect()mqtt.Client#publish()mqtt.Client#publishAsync()mqtt.Client#subscribe()mqtt.Client#subscribeAsync()mqtt.Client#unsubscribe()mqtt.Client#unsubscribeAsync()mqtt.Client#end()mqtt.Client#endAsync()mqtt.Client#removeOutgoingMessage()mqtt.Client#reconnect()mqtt.Client#handleMessage()mqtt.Client#connectedmqtt.Client#reconnectingmqtt.Client#getLastMessageId()mqtt.Store()mqtt.Store#put()mqtt.Store#del()mqtt.Store#createStream()mqtt.Store#close()يتصل بالوسيط المحدد بواسطة عنوان URL المحدد والخيارات ويعيد عميلًا.
يمكن أن يكون عنوان URL على البروتوكولات التالية: "MQTT" ، "MQTTS" ، "TCP" ، "TLS" ، "WS" ، "WSS" ، "WXS" ، "Alis". إذا كنت تحاول الاتصال بمقبس UNIX ، فما عليك سوى إلحاق لاحقة +unix بالبروتوكول (على سبيل المثال: mqtt+unix ). سيؤدي ذلك إلى تعيين خاصية unixSocket تلقائيًا.
يمكن أن يكون عنوان URL أيضًا كائنًا كما تم إرجاعه بواسطة URL.parse() ، في هذه الحالة يتم دمج الكائنين ، أي يمكنك تمرير كائن واحد مع كل من عنوان URL وخيارات الاتصال.
يمكنك أيضًا تحديد خيارات servers مع المحتوى: [{ host: 'localhost', port: 1883 }, ... ] ، في هذه الحالة يتم تكرار هذه الصفيف في كل اتصال.
بالنسبة لجميع الخيارات المتعلقة بـ MQTT ، راجع مُنشئ العميل.
غلاف غير متزامن حول وظيفة connect .
إرجاع Promise يحل إلى مثيل mqtt.Client عندما يقوم العميل بإطلاق حدث 'connect' أو 'end' ، أو يرفض بخطأ إذا تم إطلاق 'error' .
لاحظ أن خيار manualConnect سيؤدي إلى إرجاع الوعد الذي تم إرجاعه بواسطة هذه الوظيفة على عدم حلها أو رفضها لأن العميل الأساسي لا يطلق أي أحداث أبدًا.
تلتف فئة Client اتصال العميل إلى وسيط MQTT على طريقة نقل تعسفية (TCP ، TLS ، WebSocket ، ECC). Client هو eventemitter الذي يحتوي على أحداث خاصة به
يتعامل Client تلقائيًا مع ما يلي:
الحجج هي:
streamBuilder هي وظيفة تُرجع فئة فرعية من فئة Stream التي تدعم حدث connect . عادة net.Socket .options هي خيارات اتصال العميل (انظر: حزمة الاتصال). الافتراضات: wsOptions : هل خيارات اتصال WebSocket. الافتراضي هو {} . إنه خاص بـ WebSockets. للحصول على الخيارات المحتملة ، إلقاء نظرة على: https://github.com/websockets/ws/blob/master/doc/ws.md.
keepalive : 60 ثانية ، تعيين على 0 لتعطيل
reschedulePings : إعادة جدولة رسائل ping بعد إرسال الحزم ( true )
clientId : 'mqttjs_' + Math.random().toString(16).substr(2, 8)
protocolId : 'MQTT'
protocolVersion : 4
clean : true ، اضبط على خطأ لتلقي رسائل QOS 1 و 2 أثناء عدم الاتصال بالإنترنت
reconnectPeriod : 1000 مللي ثانية ، الفاصل بين اثنين من إعادة الاتصال. تعطيل إعادة الاتصال التلقائي عن طريق الإعداد إلى 0 .
reconnectOnConnackError : false ، ما إذا كان سيتم إعادة الاتصال أيضًا إذا تم استلام connack مع خطأ.
connectTimeout : 30 * 1000 مللي ثانية ، حان الوقت للانتظار قبل استلام connack
username : اسم المستخدم الذي يتطلبه الوسيط الخاص بك ، إن وجد
password : كلمة المرور المطلوبة من قبل وسيطك ، إن وجد
incomingStore : متجر للحزم الواردة
outgoingStore : متجر للحزم الصادرة
queueQoSZero : إذا تم كسر الاتصال ، فإن قائمة انتظار رسائل QOS Zero الصادرة ( true افتراضي)
customHandleAcks : ميزة MQTT 5 من حزم المعالجة المخصصة وحزم Pubrec. رد الاتصال:
customHandleAcks: function ( topic , message , packet , done ) { /*some logic with calling done(error, reasonCode)*/ } autoUseTopicAlias : تمكين الاسم المستعار للموضوع التلقائي باستخدام الوظائف
autoAssignTopicAlias : تمكين الاسم المستعار للموضوع التلقائي تعيين الوظيفة
properties : الخصائص MQTT 5.0. object يدعم الخصائص التالية:
sessionExpiryInterval : تمثيل فاصل انتهاء صلاحية الجلسة في number ،receiveMaximum : تمثيل number القيمة الحد الأقصى لاستلام ،maximumPacketSize : تمثيل الحد الأقصى لحزمة الحزمة التي يرغب العميل في قبول number ،topicAliasMaximum : يمثل تمثيل القيمة الملقائية الحد الأقصى لقيمة الحد الأقصى إلى أعلى قيمة سيقبلها العميل باعتباره اسم مستعار للموضوع الذي أرسله number الخادم ،requestResponseInformation : يستخدم العميل هذه القيمة لطلب الخادم لإرجاع معلومات الاستجابة في Connack boolean ،requestProblemInformation : يستخدم العميل هذه القيمة للإشارة إلى ما إذا كان يتم إرسال سلسلة السبب أو خصائص المستخدم في حالة الفشل boolean ،userProperties : يُسمح لخاصية المستخدم بالظهور عدة مرات لتمثيل اسم متعدد الأسماء ، object أزواج القيمة ،authenticationMethod : اسم طريقة المصادقة المستخدمة string المصادقة الموسعة ،authenticationData : البيانات الثنائية التي تحتوي على بيانات المصادقة binary authPacket : إعدادات object حزمة Auth
will : رسالة سيتم إرسالها بواسطة الوسيط تلقائيًا عندما ينفصل العميل بشكل سيء. التنسيق هو:
topic : موضوع النشرpayload : رسالة للنشرqos : جودة الخدمةretain : العلم الاحتفاظproperties : خصائص الإرادة بواسطة MQTT 5.0:willDelayInterval : تمثيل فاصل التأخير في number ،payloadFormatIndicator : Will Will Message Is UTF-8 بيانات الحرف المشفرة أو عدم boolean ،messageExpiryInterval : القيمة هي عمر رسالة الإرادة في ثوانٍ ويتم إرسالها كفاصل زمني لانتهاء النشر عندما ينشر الخادم number رسالة الإرادة ،contentType : وصف محتوى string الرسائل الإرادة ،responseTopic : السلسلة التي تُستخدم كاسم موضوع string رسائل استجابة ،correlationData : يتم استخدام بيانات الارتباط من قبل مرسل رسالة الطلب لتحديد طلب رسالة الاستجابة عند استلامها binary ،userProperties : يُسمح لخاصية المستخدم بالظهور عدة مرات لتمثيل object أزواج القيمة المتعددة transformWsUrl : اختياري (url, options, client) => url لبروتوكولات WS/WSS فقط. يمكن استخدامها لتنفيذ عناوين URL لتوقيع والتي يمكن أن تنتهي صلاحيتها عند الاتصال.
createWebsocket : url, websocketSubProtocols, options) => Websocket لبروتوكولات WS/WSS فقط. يمكن استخدامها لتنفيذ محول أو تطبيق مخصص لـ WebSocket.
resubscribe : إذا تم كسر الاتصال وإعادة الاتصال ، يتم الاشتراك في مواضيع مشتركة تلقائيًا مرة أخرى ( true افتراضي)
messageIdProvider : مخصص موفر MessageId. عند تعيين new UniqueMessageIdProvider() ، يتم توفير رسالة غير تعارض.
log : وظيفة سجل مخصصة. الافتراضي يستخدم حزمة التصحيح.
manualConnect : يمنع المُنشئ للاتصال connect . في هذه الحالة بعد استدعاء mqtt.connect ، يجب عليك الاتصال client.connect .
timerVariant : الإعدادات الافتراضية إلى auto ، والتي تحاول تحديد المؤقت الأكثر ملاءمة بالنسبة لك البيئة ، إذا كنت تواجه مشكلات في اكتشاف ، فيمكنك ضبطها على worker أو native . إذا كان لا أحد يناسبك ، فيمكنك تمرير كائن مؤقت بمجموعة محددة وخصائص مسح:
timerVariant: {
set : ( func , timer ) => setInterval ( func , timer ) ,
clear : ( id ) => clearInterval ( id )
} forceNativeWebSocket : قم بالتعيين على True إذا كنت تواجه مشكلات في الكشف (أي أن ws does not work in the browser ) لفرض استخدام WebSocket الأصلي. من المهم أن نلاحظ أنه إذا تم تعيينه على TRUE للعميل الأول الذي تم إنشاؤه ، فسيستخدم جميع العملاء WebSocket الأصلي. وعلى العكس ، إذا لم يتم تعيينه أو تعيينه على خطأ ، فسيستخدم الجميع نتيجة الكشف.
unixSocket : إذا كنت ترغب في الاتصال بمقبس Unix ، فقم بتعيين هذا على True
في حالة مطلوب MQTTS (MQTT أكثر من TLS) ، يتم تمرير كائن options إلى tls.connect() . في حالة استخدام شهادة توقيع ذاتيًا ، قم بتعيين rejectUnauthorized: false . ومع ذلك ، كن حذرًا لأن هذا يعرضك على الرجل المحتمل في الهجمات الوسطى ولا ينصح به للإنتاج.
لأولئك الذين يدعمون بروتوكولات TLS المتعددة على منفذ واحد ، مثل MQTTS و MQTT على WSS ، استخدم خيار ALPNProtocols . يتيح لك ذلك تحديد بروتوكول تفاوض بروتوكول طبقة التطبيق (ALPN). يمكنك تعيين ALPNProtocols كصفيف السلسلة أو المخزن المؤقت أو UINT8Array استنادًا إلى الإعداد الخاص بك.
إذا كنت تتصل مع وسيط يدعم فقط MQTT 3.1 (ليس 3.1.1 متوافق) ، فيجب عليك تمرير هذه الخيارات الإضافية:
{
protocolId : 'MQIsdp' ,
protocolVersion : 3
}تم تأكيد ذلك على RabbitMQ 3.2.4 ، وعلى البعوض <1.3. النسخة البعوض 1.3 و 1.4 تعمل بشكل جيد بدون هؤلاء.
'connect' function (connack) {}
المنبعثة على اتصال ناجح (إعادة) (أي connack rc = 0).
connack حزمة كوناك. عندما يكون خيار الاتصال clean false ، يكون لدى الخادم جلسة سابقة لخيار اتصال clientId ، فإن علامة connack.sessionPresent true . عندما يكون هذا هو الحال ، يمكنك الاعتماد على الجلسة المخزنة ويفضل عدم إرسال أوامر الاشتراك للعميل. 'reconnect' function () {}
المنبعثة عندما تبدأ إعادة الاتصال.
'close' function () {}
المنبعثة بعد الانفصال.
'disconnect' function (packet) {}
المنبعثة بعد تلقي حزمة قطع الاتصال من الوسيط. ميزة MQTT 5.0.
'offline' function () {}
المنبعث عندما يذهب العميل في وضع عدم الاتصال.
'error' function (error) {}
ينبعث عندما لا يمكن للعميل الاتصال (أي connack rc! = 0) أو عند حدوث خطأ في التحليل.
سيتم تنبعث أخطاء TLS التالية كحدث error :
ECONNREFUSEDECONNRESETEADDRINUSEENOTFOUND'end' function () {}
ينبعث عندما يتم استدعاء mqtt.Client#end() . إذا تم تمرير رد الاتصال إلى mqtt.Client#end() ، يتم انبعاث هذا الحدث بمجرد عودة رد الاتصال.
'message' function (topic, message, packet) {}
ينبعث عندما يتلقى العميل حزمة نشر
topic الموضوع من الحزمة المستلمةmessage من الحزمة المستلمةpacket حزمة ، كما هو محدد في MQTT-Packet 'packetsend' function (packet) {}
المنبعث عندما يرسل العميل أي حزمة. ويشمل ذلك حزم .published () بالإضافة إلى الحزم المستخدمة من قبل MQTT لإدارة الاشتراكات والاتصالات
packet حزمة ، كما هو محدد في MQTT-Packet 'packetreceive' function (packet) {}
المنبعث عندما يتلقى العميل أي حزمة. ويشمل ذلك حزم من الموضوعات المشتركة وكذلك الحزم المستخدمة من قبل MQTT لإدارة الاشتراكات والاتصالات
packet حزمة ، كما هو محدد في MQTT-Packet بشكل افتراضي يتصل العميل عندما يتم استدعاء مُنشئ. لمنع ذلك ، يمكنك تعيين خيار manualConnect إلى true واتصل client.connect() يدويًا.
نشر رسالة إلى موضوع
topic هو موضوع نشره ، Stringmessage هي الرسالة للنشر أو Buffer أو Stringoptions هي خيارات النشر مع: بما في ذلك:qos ، Number ، الافتراضي 0retain بالاحتفاظ بالعلم ، Boolean ، الافتراضي falsedup Mark كعلم مكرر ، Boolean ، خطأ falseproperties : object خصائص MQTT 5.0payloadFormatIndicator : الحمولة النافعة هي بيانات الحرف المشفرة UTF-8 أو عدم boolean ،messageExpiryInterval : عمر رسالة التطبيق number ،topicAlias : القيمة المستخدمة لتحديد الموضوع بدلاً من استخدام number اسم الموضوع ،responseTopic : السلسلة التي تُستخدم كاسم موضوع string رسائل استجابة ،correlationData : يستخدمه مرسل رسالة الطلب لتحديد طلب رسالة الاستجابة عند استلامها binary ،userProperties : يُسمح لخاصية المستخدم بالظهور عدة مرات لتمثيل اسم متعدد الأسماء ، object أزواج القيمة ،subscriptionIdentifier : تمثيل معرف number الاشتراك ،contentType : سلسلة تصف محتوى string رسائل التطبيقcbStorePut - function () ، يتم إطلاقه عند وضع الرسالة في outgoingStore إذا كان QoS 1 أو 2 .callback - function (err, packet) ، تم إطلاقه عند اكتمال معالجة جودة الخدمة ، أو عند الإطار التالي إذا كان QOS 0. حدوث خطأ إذا تم قطع العميل. Async publish . إرجاع Promise<Packet | undefined> .
messageId .اشترك في موضوع أو موضوعات
topic هو موضوع String للاشتراك أو Array من الموضوعات للاشتراك فيها. يمكن أن يكون أيضًا كائنًا ، وله مفاتيح كائن اسم الموضوع وكقيمة QOS ، مثل {'test1': {qos: 0}, 'test2': {qos: 1}} . MQTT topic Wildcard يتم دعم أحرف بطاقة Wildcard ( + - للمستوى الفردي و # - للمستوى المتعدد)options هي خيارات الاشتراك معها ، بما في ذلك:qos ، الافتراضي 0nl NO MQTT 5.0 علامة (إذا كانت القيمة صحيحة ، يجب عدم إعادة توجيه رسائل التطبيق إلى اتصال مع عميل يساوي العميل الخاص باتصال النشر)rap كما تم نشر MQTT 5.0 علامة (إذا كان ذلك صحيحًا ، فإن رسائل التطبيق التي تم إعادة توجيهها باستخدام هذا الاشتراك ، احتفظ بعلم الاحتفاظ الذي تم نشره معهم. إذا كانت رسائل تطبيق خاطئة ، يتم إعادة توجيهها باستخدام هذا الاشتراك ، تم تعيين علامة الاحتفاظ بـ 0.)rh الاحتفاظ بالتعامل مع MQTT 5.0 (يحدد هذا الخيار ما إذا كان يتم إرسال الرسائل المحتجزة عند إنشاء الاشتراك.)properties : objectsubscriptionIdentifier : تمثيل معرف number الاشتراك ،userProperties : يُسمح لخاصية المستخدم بالظهور عدة مرات لتمثيل object أزواج القيمة المتعددةcallback - function (err, granted) رد الاتصال على Suback حيث:err خطأ الاشتراك أو خطأ يحدث عند فصل العميلgranted هي مجموعة من {topic, qos} حيث:topic مشترك في الموضوعqos هو مستوى جودة الخدمة الممنوحة عليه subscribe غير المتزامن. يعيد Promise<ISubscriptionGrant[]> .
إلغاء الاشتراك من موضوع أو موضوعات
topic هو موضوع String أو مجموعة من الموضوعات لإلغاء الاشتراك منoptions : خيارات إلغاء الاشتراك.properties : objectuserProperties : يُسمح لخاصية المستخدم بالظهور عدة مرات لتمثيل object أزواج القيمة المتعددةcallback - function (err) ، أطلقت على Unsback. يحدث خطأ إذا كان العميل يفصل. غير متزامن unsubscribe . يعود Promise<void> .
أغلق العميل ، يقبل الخيارات التالية:
force : إن نقله إلى True سيغلق العميل على الفور ، دون انتظار أن تكون الرسائل أثناء الطيران قد أقيمت. هذه المعلمة اختيارية.options : خيارات الانفصال.reasonCode : افصل number رمز السببproperties : objectsessionExpiryInterval : تمثيل فاصل انتهاء صلاحية الجلسة في number ،reasonString : تمثيل سبب string الاتصال ،userProperties : يُسمح لخاصية المستخدم بالظهور عدة مرات لتمثيل اسم متعدد الأسماء ، object أزواج القيمة ،serverReference : السلسلة التي يمكن أن يستخدمها العميل لتحديد خادم آخر لاستخدام stringcallback : سيتم استدعاؤه عند إغلاق العميل. هذه المعلمة اختيارية. end غير متزامنة. يعود Promise<void> .
إزالة رسالة من المنتهية المنتهية ولايته. سيتم استدعاء رد الاتصال الصادر بالخطأ ("تم إزالة الرسالة") إذا تمت إزالة الرسالة.
بعد استدعاء هذه الوظيفة ، يتم إصدار MessageId ويصبح قابلاً لإعادة الاستخدام.
mId : MessageId من الرسالة في المنتهية المنتهية ولايته.الاتصال مرة أخرى باستخدام نفس الخيارات مثل Connect ()
التعامل مع الرسائل بدعم الضغط على الظهر ، واحد في وقت واحد. تجاوز الإرادة ، ولكن دائما اتصل callback ، أو سيتم تعليق العميل.
Boolean: اضبط على true إذا كان العميل متصلاً. false خلاف ذلك.
الرقم: احصل على معرف الرسالة الأخير. هذا هو للرسائل المرسلة فقط.
Boolean: اضبط على true إذا كان العميل يحاول إعادة الاتصال بالخادم. false خلاف ذلك.
التنفيذ في الذاكرة لمتجر الرسائل.
options هي خيارات المتجر:clean : الرسائل true والنظيفة عند الإغلاق ( true افتراضي) تطبيقات أخرى من mqtt.Store :
يضيف حزمة إلى المتجر ، الحزمة هي أي شيء يحتوي على خاصية messageId . يتم استدعاء رد الاتصال عند تخزين الحزمة.
يخلق دفقًا مع جميع الحزم في المتجر.
يزيل حزمة من المتجر ، الحزمة هي أي شيء يحتوي على خاصية messageId . يتم استدعاء رد الاتصال عند إزالة الحزمة.
يغلق المتجر.
مهم
البروتوكول الوحيد المدعوم في المتصفحات هو MQTT عبر WebSockets ، لذلك يجب عليك استخدام ws:// أو wss:// .
بينما يتم استخدام وحدة WS في NodeJS ، يتم استخدام WebSocket في المتصفحات. هذا شفاف تمامًا للمستخدمين باستثناء ما يلي:
لا يتم دعم wsOption في المتصفحات.
لا تسمح المتصفحات بالتقاط العديد من أخطاء WebSocket لأسباب أمنية على النحو التالي:
يمكن أن يسمح الوصول إلى هذه المعلومات لصفحة ويب ضارة للحصول على معلومات حول شبكتك ، بحيث تتطلب المتصفحات الإبلاغ عن جميع أخطاء وقت الاتصال بطريقة لا يمكن تمييزها.
لذا ، لا يجوز للاستماع إلى client.on('error') .
يتم تجميع MQTT.JS باستخدام ESBUILD. يتم اختباره يعمل مع جميع الحزم مثل WebPack و Vite و React.
يمكنك العثور على جميع إصدارات حزم MQTT في مجلد dist :
mqtt.js - تنسيق iife ، غير مصغرةmqtt.min.js - تنسيق iife ، مصغرةmqtt.esm.js - تنسيق ESM مُعجّلبدءًا من MQTT.JS> 5.2.0 يمكنك استيراد MQTT في الكود الخاص بك مثل هذا:
import mqtt from 'mqtt'سيتم التعامل مع هذا تلقائيا من قبل الحزمة الخاصة بك.
وإلا يمكنك اختيار استخدام حزمة محددة مثل:
import * as mqtt from 'mqtt/dist/mqtt'
import * as mqtt from 'mqtt/dist/mqtt.min'
import mqtt from 'mqtt/dist/mqtt.esm'تتوفر حزمة MQTT.JS من خلال http://unpkg.com ، وتحديدا على https://unpkg.com/mqtt/dist/mqtt.min.js. راجع http://unpkg.com للحصول على الوثائق الكاملة على نطاقات الإصدار.
إليكم كيف يعمل جودة الخدمة:
حول استهلاك البيانات ، من الواضح ، QOS 2> QOS 1> QOS 0 ، إذا كان هذا مصدر قلق لك.
بدءًا من V5 ، يتم كتابة هذا المشروع في TypeScript ويتم تضمين تعريفات النوع في الحزمة.
مثال:
import { connect } from "mqtt"
const client = connect ( 'mqtt://test.mosquitto.org' ) يدعم برنامج WeChat Mini. استخدم بروتوكول wxs . انظر مستندات WeChat.
import 'abortcontroller-polyfill/dist/abortcontroller-polyfill-only' // import before mqtt.
import 'esbuild-plugin-polyfill-node/polyfills/navigator'
const mqtt = require ( "mqtt" ) ;
const client = mqtt . connect ( "wxs://test.mosquitto.org" , {
timerVariant : 'native' // more info ref issue: #1797
} ) ; يدعم برنامج Ali Mini. استخدم بروتوكول alis . انظر مستندات Alipay.
const mqtt = require ( "mqtt" ) ;
const client = mqtt . connect ( "alis://test.mosquitto.org" ) ; MQTT.JS هو مشروع مفتوح المصدر . هذا يعني أن:
يتم إعطاء الأفراد الذين يقدمون مساهمات مهمة وقيمة الوصول إلى المشروع للمساهمة كما يرون مناسبة. يشبه هذا المشروع ويكي مفتوح أكثر من مشروع المصدر المفتوح القياسي.
راجع ملف المساهمة. md لمزيد من التفاصيل.
MQTT.JS ممكن فقط بسبب العمل الممتاز للمساهمين التاليين:
| اسم | جيثب | تغريد |
|---|---|---|
| آدم رود | جيثب/adamvr | Twitter/@adam_vr |
| ماتيو كولينا | جيثب/ماكولينا | Twitter/@Matteocollina |
| ماكسيم أجور | جيثب/4Rzael | تويتر/@4RZAEL |
| Siarhei Buntsevich | Github/Scarry1992 | |
| دانييل لاندو | جيثب/روبرتسلاندو |
إذا كنت ترغب في دعم MQTT.JS ، فيرجى التفكير في رعاية المؤلف والمحافظة النشطة:
معهد ماساتشوستس للتكنولوجيا
