التواصل مع مركز IoT باستخدام بروتوكول MQTT

مقالة
06/27/2023

توضح هذه المقالة كيف يمكن للأجهزة استخدام سلوكيات MQTT المدعومة للتواصل مع Azure IoT Hub. يمكّن مركز IoT الأجهزة من الاتصال بنقاط نهاية جهاز في مركز IoT باستخدام:

MQTT v3.1.1 على منفذ TCP 8883
MQTT v3.1.1 عبر WebSocket على منفذ TCP 443.

إشعار

تتوفر بعض الميزات المذكورة في هذه المقالة، مثل المراسلة من السحابة إلى الجهاز والجهاز المزدوج وإدارة الجهاز، في الطبقة القياسية لـ IoT Hub فقط. لمزيد من المعلومات حول مستويات IoT Hub الأساسية والقياسية/المجانية، راجع اختيار طبقة IoT Hub المناسبة للحل الخاص بك.

يجب تأمين جميع اتصالات الجهاز لمركز IoT باستخدام TLS/SSL. لذلك، لا يدعم IoT Hub الاتصالات غير الآمنة عبر منفذ TCP 1883.

مقارنة دعم MQTT في مركز IoT وشبكة الأحداث

مركز إنترنت الأشياء ليس وسيط MQTT كامل الميزات ولا يدعم جميع السلوكيات المحددة في معيار MQTT v3.1.1. إذا كان الحل الخاص بك يحتاج إلى MQTT، نوصي بدعم MQTT في Azure Event Grid. تتيح Event Grid الاتصال ثنائي الاتجاه بين عملاء MQTT حول مواضيع هرمية مرنة باستخدام نموذج مراسلة pub-sub. كما أنه يمكنك من توجيه رسائل MQTT إلى خدمات Azure أو نقاط النهاية المخصصة لمزيد من المعالجة.

يوضح الجدول التالي الاختلافات في دعم MQTT بين الخدمتين:

IoT Hub	Event Grid
نموذج خادم العميل مع اقتران ضيق بين الأجهزة والتطبيقات السحابية.	نموذج النشر والاشتراك الذي يفكك الناشرين والمشتركين.
دعم ميزات محدود ل MQTT v3.1.1، ودعم ميزات محدود ل MQTT v5 في المعاينة. لم يتم التخطيط لمزيد من دعم الميزات.	دعم بروتوكول MQTT v3.1.1 وv5، مع المزيد من دعم الميزات والامتثال للصناعة المخطط لها.
مواضيع ثابتة ومعرفة مسبقا.	مواضيع هرمية مخصصة مع دعم أحرف البدل.
لا يوجد دعم للبث من السحابة إلى الجهاز والاتصال من جهاز إلى جهاز.	يدعم البث من جهاز إلى سحابة، وبث من سحابة إلى جهاز، وأنماط اتصال من جهاز إلى جهاز.
256 كيلوبايت كحد أقصى لحجم الرسالة.	512 كيلوبايت كحد أقصى لحجم الرسالة.

الاتصال بمركز IoT

يمكن للجهاز استخدام بروتوكول MQTT للاتصال بمركز IoT باستخدام أحد الخيارات التالية:

Azure IoT SDKs.
بروتوكول MQTT مباشرة.

تم حظر منفذ MQTT (منفذ TCP 8883) في العديد من بيئات الشبكات المؤسسية والتعليمية. إذا لم تتمكن من فتح المنفذ 8883 في جدار الحماية، نوصي باستخدام MQTT عبر WebSockets. يتصل MQTT عبر WebSockets عبر المنفذ 443، والذي يفتح دائما تقريبا في بيئات الشبكات. لمعرفة كيفية تحديد MQTT وMQTT عبر بروتوكولات WebSockets عند استخدام Azure IoT SDKs، راجع استخدام حزم SDK للجهاز.

استخدام حزم SDK للجهاز

حزم SDK للجهاز التي تدعم بروتوكول MQTT متوفرة لـ Java وNode.js وC وC# وPython. تستخدم SDKs بالجهاز آلية المصادقة التي تم اختيارها لإنشاء اتصال بمركز إنترنت الأشياء. ينبغي، لاستخدام بروتوكول MQTT، تعيين معلمة بروتوكول العميل إلى MQTT. يمكنك أيضا تحديد MQTT عبر WebSockets في معلمة بروتوكول العميل. تتصل SDKs للجهاز، بشكل افتراضي، بمركز IoT مع تعيين علامة CleanSession إلى 0 واستخدام QoS 1 لتبادل الرسائل مع مركز IoT. في حين أنه من الممكن تكوين QoS 0 لتبادل الرسائل بشكل أسرع، يجب الانتباه إلى أن التسليم غير مضمون وغير معترف به. يُشار غالبًا، لهذا السبب، إلى QoS 0 باسم "fire and forget".

عند توصيل جهاز بمركز IoT، توفر SDKs بالجهاز أساليب تمكن الجهاز من تبادل الرسائل مع مركز IoT.

يحتوي الجدول التالي على ارتباطات إلى نماذج التعليمات البرمجية لكل لغة مدعومة ويحدد المعلمة لاستخدامها لإنشاء اتصال ب IoT Hub باستخدام MQTT أو MQTT عبر بروتوكول WebSockets.

اللغة	معلمة بروتوكول MQTT	MQTT عبر معلمة بروتوكول WebSockets
Node.js	azure-iot-device-mqtt.Mqtt	azure-iot-device-mqtt.MqttWs
Java	IotHubClientProtocol.MQTT	IotHubClientProtocol.MQTT_WS
C	MQTT_Protocol	MQTT_WebSocket_Protocol
C#‎	TransportType.Mqtt	يعود TransportType.Mqtt إلى MQTT عبر WebSockets إذا فشل MQTT. لتحديد MQTT عبر WebSockets فقط، استخدم TransportType.Mqtt_WebSocket_Only
Python	يدعم MQTT بشكل افتراضي	أضف `websockets=True` في الاستدعاء لإنشاء العميل

يوضح الجزء التالي كيفية تحديد MQTT عبر بروتوكول WebSockets عند استخدام Azure IoT Node.js SDK:

var Client = require('azure-iot-device').Client;
var Protocol = require('azure-iot-device-mqtt').MqttWs;
var client = Client.fromConnectionString(deviceConnectionString, Protocol);

يوضح الجزء التالي كيفية تحديد MQTT عبر بروتوكول WebSockets عند استخدام Azure IoT Python SDK:

from azure.iot.device.aio import IoTHubDeviceClient
device_client = IoTHubDeviceClient.create_from_connection_string(deviceConnectionString, websockets=True)

هام

تتضمن هذه المقالة خطوات لتوصيل جهاز باستخدام توقيع وصول مشترك، يسمى أيضا مصادقة المفتاح المتماثل. طريقة المصادقة هذه ملائمة للاختبار والتقييم، ولكن مصادقة جهاز باستخدام شهادات X.509 هي نهج أكثر أمانا. لمعرفة المزيد، راجع أفضل ممارسات > الأمان أمان الاتصال.

مهلة افتراضية لاتصال مستمر

لضمان استمرار الاتصال بمركز العميل/IoT، ترسل كل من الخدمة والعميل بانتظام اختبار اتصال مستمر إلى بعضهما البعض. يرسل العميل الذي يستخدم IoT SDK الاحتفاظ بالحياة في الفاصل الزمني المحدد في الجدول التالي:

اللغة	الفاصل الزمني الافتراضي لاتصال مستمر	قابل للتكوين
Node.js	180 ثانية	لا
Java	230 ثانية	نعم
C	240 ثانية	نعم
C#‎	300 ثانية*	نعم
Python	60 ثانية	نعم

*يحدد C# SDK القيمة الافتراضية للخاصية MQTT KeepAliveInSeconds على أنها 300 ثانية. في الواقع، يرسل SDK طلب اختبار اتصال أربع مرات لكل مجموعة مدة البقاء على قيد الحياة. بمعنى آخر، يرسل SDK اتصالا دائما مرة واحدة كل 75 ثانية.

بعد مواصفات MQTT v3.1.1، يبلغ الفاصل الزمني ل ping الخاص ب IoT Hub 1.5 مرة قيمة استمرار بقاء العميل؛ ومع ذلك، يحد IoT Hub من الحد الأقصى للمهلة من جانب الخادم إلى 29.45 دقيقة (1767 ثانية). هذا الحد موجود لأن جميع خدمات Azure مرتبطة بمهلة الخمول TCP لموازن تحميل Azure، وهي 29.45 دقيقة.

يرسل، على سبيل المثال، جهاز يستخدم Java SDK اختبار اتصال مستمر، ثم يفقد الاتصال بالشبكة. يفقد الجهاز، بعد مرور 230 ثانية، استمرار الاتصال لأنه غير متصل. إلا أنه لا يغلق مركز IoT الاتصال على الفور بل ينتظر (230 * 1.5) - 230 = 115ثواني أخرى قبل قطع اتصال الجهاز بسبب الخطأ 404104 DeviceConnectionClosedRemotely.

الحد الأقصى لقيمة استمرار اتصال العميل التي يمكنك تعيينها هي 1767 / 1.5 = 1177 ثوان. أي حركة مرور يعيد تعيين البقاء على قيد الحياة. على سبيل المثال، يقوم تحديث الرمز المميز الناجح لتوقيع الوصول المشترك (SAS) بإعادة تعيين البقاء على قيد الحياة.

ترحيل تطبيق جهاز من AMQP إلى MQTT

إذا كنت تستخدم SDKs للجهاز، فيتطلب التبديل من استخدام AMQP إلى MQTT تغيير معلمة البروتوكول في تهيئة العميل، كما هو مذكور سابقًا.

تأكد من التحقق من العناصر التالية عند تنفيذ ذلك:

يبدأ AMQP بإرجاع أخطاء للعديد من الشروط بينما يقوم MQTT بإنهاء الاتصال. قد يتطلب منطق معالجة الاستثناء بعض التغييرات نتيجة لذلك.
لا يدعم MQTT عمليات الرفض عند استلام رسائل سحابة-إلى-جهاز. إذا تطلب التطبيق الخلفي استلام استجابة من تطبيق الجهاز، يوصى بمراعاة استخدام أساليب مباشرة.
AMQP غير مدعوم في Python SDK.

استخدام بروتوكول MQTT مباشرة (كجهاز)

إذا تعذر على الجهاز استخدام SDKs للجهاز، فلا يزال بإمكانه الاتصال بنقاط نهاية الجهاز العام باستخدام بروتوكول MQTT على المنفذ 8883.

في حزمة CONNECT، يجب أن يستخدم الجهاز القيم التالية:

بالنسبة لحقل ClientId، استخدم deviceId.
بالنسبة لحقل Username ، استخدم {iotHub-hostname}/{device-id}/?api-version=2021-04-12، حيث {iotHub-hostname} هو الكامل CName لمركز IoT.

إذا كان اسم مركز IoT contoso.azure-devices.net وكان اسم جهازك MyDevice01 على سبيل المثال، يجب أن يحتوي حقل اسم المستخدم الكامل على:

contoso.azure-devices.net/MyDevice01/?api-version=2021-04-12

يوصى بتضمين api-version في الحقل. وإلا قد يتسبب هذا في سلوكيات غير متوقعة.
بالنسبة إلى حقل كلمة المرور، استخدم رمز SAS المميز. تنسيق رمز SAS المميز هو نفسه لكل بروتوكولات HTTPS وAMQP:

SharedAccessSignature sig={signature-string}&se={expiry}&sr={URL-encoded-resourceURI}

إشعار

إذا كنت تستخدم مصادقة شهادة X.509، فلن تكون كلمات مرور رمز SAS المميز مطلوبة. لمزيد من المعلومات، راجع البرنامج التعليمي: إنشاء وتحميل الشهادات للاختبار واتبع إرشادات التعليمات البرمجية في قسم تكوين TLS/SSL.

لمزيد من المعلومات حول كيفية إنشاء رموز SAS المميزة، راجع قسم استخدام رموز SAS المميزة كجهاز من التحكم في الوصول إلى IoT Hub باستخدام توقيعات الوصول المشترك.

يمكنك أيضا استخدام ملحق Azure IoT Hub عبر النظام الأساسي ل Visual Studio Code أو أمر ملحق CLI az iot hub generate-sas-token لإنشاء رمز SAS المميز بسرعة. يمكنك بعد ذلك نسخ ولصق رمز SAS المميز في التعليمات البرمجية الخاصة بك لأغراض الاختبار.

للحصول على برنامج تعليمي حول استخدام MQTT مباشرة، راجع استخدام MQTT لتطوير عميل جهاز IoT دون استخدام SDK للجهاز.

استخدام ملحق Azure IoT Hub ل Visual Studio Code

في الشريط الجانبي، قم بتوسيع عقدة الأجهزة ضمن قسم Azure IoT Hub .
انقر بزر الماوس الأيمن فوق جهاز IoT وحدد Generate SAS Token for Device من قائمة السياق.
أدخل وقت انتهاء الصلاحية، بالساعات، للرمز المميز SAS في مربع الإدخال، ثم حدد مفتاح الإدخال.
يتم إنشاء رمز SAS المميز ونسخه إلى الحافظة.

يحتوي رمز SAS المميز الذي تم إنشاؤه على البنية التالية:

HostName={iotHub-hostname};DeviceId=javadevice;SharedAccessSignature=SharedAccessSignature sr={iotHub-hostname}%2Fdevices%2FMyDevice01%2Fapi-version%3D2016-11-14&sig=vSgHBMUG.....Ntg%3d&se=1456481802

الجزء من هذا الرمز المميز لاستخدامه كحقل Password للاتصال باستخدام MQTT هو:

SharedAccessSignature sr={iotHub-hostname}%2Fdevices%2FMyDevice01%2Fapi-version%3D2016-11-14&sig=vSgHBMUG.....Ntg%3d&se=1456481802

يمكن لتطبيق الجهاز تحديد رسالة Will في حزمة CONNECT. يجب أن يستخدم تطبيق الجهاز devices/{device-id}/messages/events/ أو devices/{device-id}/messages/events/{property-bag} كاسم موضوع Will لتحديد رسائل Will التي سيتم إعادة إرسالها كرسالة بيانات تتبع الاستخدام. يتم، في هذه الحالة، إغلاق اتصال الشبكة لكن لم يتم استلام حزمة DISCONNECT مسبقًا من الجهاز، فسيرسل مركز إنترنت الأشياء رسالة Will المتوفرة في حزمة CONNECT إلى قناة بيانات تتبع الاستخدام. يمكن أن تكون قناة بيانات تتبع الاستخدام إما نقطة نهاية «الأحداث» الافتراضية أو نقطة نهاية مخصصة يحددها توجيه مركز IoT. تحتوي الرسالة على خاصية iothub-MessageType بقيمة Will المعينة لها.

استخدام بروتوكول MQTT مباشرة (كوحدة نمطية)

يمكنك الاتصال ب IoT Hub عبر MQTT باستخدام هوية وحدة نمطية، على غرار الاتصال ب IoT Hub كجهاز. لمزيد من المعلومات حول الاتصال ب IoT Hub عبر MQTT كجهاز، راجع استخدام بروتوكول MQTT مباشرة (كجهاز) . ومع ذلك، تحتاج إلى استخدام القيم التالية:

عيّن معرّف العميل إلى {device-id}/{module-id}.
إذا كانت المصادقة باستخدام اسم المستخدم وكلمة المرور، يوصى بتعيين اسم المستخدم إلى <hubname>.azure-devices.net/{device_id}/{module_id}/?api-version=2021-04-12 واستخدام رمز SAS المميز المقترن بهوية الوحدة النمطية ككلمة مرور.
استخدم devices/{device-id}/modules/{module-id}/messages/events/ كموضوع لنشر بيانات تتبع الاستخدام.
استخدم devices/{device-id}/modules/{module-id}/messages/events/ كموضوع WILL.
استخدم devices/{device-id}/modules/{module-id}/# كموضوع لاستلام الرسائل.
مواضيع GET و PATCH المزدوجة متطابقة للوحدات النمطية والأجهزة.
موضوع الحالة المزدوجة مطابق للوحدات النمطية والأجهزة.

لمزيد من المعلومات حول استخدام MQTT مع الوحدات النمطية، راجع النشر والاشتراك باستخدام IoT Edge ومعرفة المزيد حول نقطة نهاية IoT Edge hub MQTT.

عينات تستخدم MQTT بدون Azure IoT SDK

يحتوي مستودع نموذج IoT MQTT على نماذج C/C++، وPython، وCLI توضح لك كيفية إرسال رسائل القياس عن بعد، وتلقي رسائل من السحابة إلى الجهاز، واستخدام توائم الجهاز دون استخدام حزم SDK لجهاز Azure.

تستخدم نماذج C/C++ مكتبة Eclipse Mosquitto ، وتستخدم عينة Python Eclipse Paho، وتستخدم mosquitto_pubنماذج CLI .

لمعرفة المزيد، راجع البرنامج التعليمي - استخدام MQTT لتطوير عميل جهاز IoT.

تكوين TLS/SSL

لاستخدام بروتوكول MQTT مباشرة، يجب على العميل الاتصال عبر TLS/SSL. تفشل محاولات تخطي هذه الخطوة بأخطاء في الاتصال.

لإنشاء اتصال TLS، قد تحتاج إلى تنزيل شهادة جذر DigiCert التي يستخدمها Azure والإشارة إليها. بين 15 فبراير و15 أكتوبر 2023، يقوم Azure IoT Hub بترحيل شهادة جذر TLS الخاصة به من شهادة DigiCert Baltimore الجذر إلى DigiCert Global Root G2. أثناء فترة الترحيل، يجب أن يكون لديك كلتا الشهادتين على أجهزتك لضمان الاتصال. لمزيد من المعلومات حول الترحيل، راجع ترحيل موارد IoT إلى جذر شهادة TLS جديد لمزيد من المعلومات حول هذه الشهادات، راجع موقع Digicert على الويب.

يوضح المثال التالي كيفية تنفيذ هذا التكوين، باستخدام إصدار Python من مكتبة Paho MQTT بواسطة Eclipse Foundation.

يوصى أولاً بتثبيت مكتبة Paho من بيئة سطر الأوامر:

pip install paho-mqtt

ونفذ العميل في برنامج نصي بلغة Python. استبدل هذه العناصر النائبة في القصاصة البرمجية التالية:

<local path to digicert.cer> هو المسار إلى ملف محلي يحتوي على شهادة جذر DigiCert. يمكنك إنشاء هذا الملف بنسخ معلومات الشهادة من certs.c في Azure IoT SDK لـ C. يوصى بتضمين الأسطر -----BEGIN CERTIFICATE----- و-----END CERTIFICATE-----، وإزالة العلامات " الموجودة في بداية ونهاية كل سطر وإزالة الأحرف \r\n في نهاية كل سطر.
<device id from device registry> هو معرف الجهاز الذي أضفته إلى مركز IoT لديك.
<generated SAS token> هو رمز SAS المميز للجهاز الذي تم إنشاؤه كما هو موضح سابقا في هذه المقالة.
<iot hub name> اسم مركز IoT الخاص بك.

from paho.mqtt import client as mqtt
import ssl

path_to_root_cert = "<local path to digicert.cer file>"
device_id = "<device id from device registry>"
sas_token = "<generated SAS token>"
iot_hub_name = "<iot hub name>"


def on_connect(client, userdata, flags, rc):
    print("Device connected with result code: " + str(rc))


def on_disconnect(client, userdata, rc):
    print("Device disconnected with result code: " + str(rc))


def on_publish(client, userdata, mid):
    print("Device sent message")


client = mqtt.Client(client_id=device_id, protocol=mqtt.MQTTv311)

client.on_connect = on_connect
client.on_disconnect = on_disconnect
client.on_publish = on_publish

client.username_pw_set(username=iot_hub_name+".azure-devices.net/" +
                       device_id + "/?api-version=2021-04-12", password=sas_token)

client.tls_set(ca_certs=path_to_root_cert, certfile=None, keyfile=None,
               cert_reqs=ssl.CERT_REQUIRED, tls_version=ssl.PROTOCOL_TLSv1_2, ciphers=None)
client.tls_insecure_set(False)

client.connect(iot_hub_name+".azure-devices.net", port=8883)

client.publish("devices/" + device_id + "/messages/events/", '{"id":123}', qos=1)
client.loop_forever()

للمصادقة باستخدام شهادة جهاز، قم بتحديث القصاصة البرمجية السابقة بالتغييرات المحددة في قصاصة التعليمات البرمجية التالية. لمزيد من المعلومات حول كيفية التحضير للمصادقة المستندة إلى الشهادة، راجع قسم الحصول على شهادة المرجع المصدق X.509 من أجهزة المصادقة باستخدام شهادات المرجع المصدق X.509.

# Create the client as before
# ...

# Set the username but not the password on your client
client.username_pw_set(username=iot_hub_name+".azure-devices.net/" +
                       device_id + "/?api-version=2021-04-12", password=None)

# Set the certificate and key paths on your client
cert_file = "<local path to your certificate file>"
key_file = "<local path to your device key file>"
client.tls_set(ca_certs=path_to_root_cert, certfile=cert_file, keyfile=key_file,
               cert_reqs=ssl.CERT_REQUIRED, tls_version=ssl.PROTOCOL_TLSv1_2, ciphers=None)

# Connect as before
client.connect(iot_hub_name+".azure-devices.net", port=8883)

إرسال رسائل جهاز-إلى-سحابة

بعد توصيل جهاز، يمكنه إرسال رسائل إلى IoT Hub باستخدام devices/{device-id}/messages/events/ أو devices/{device-id}/messages/events/{property-bag} كاسم موضوع. {property-bag} يمكن العنصر الجهاز من إرسال رسائل مع خصائص أخرى بتنسيق ترميز URL. على سبيل المثال:

RFC 2396-encoded(<PropertyName1>)=RFC 2396-encoded(<PropertyValue1>)&RFC 2396-encoded(<PropertyName2>)=RFC 2396-encoded(<PropertyValue2>)…

إشعار

يستخدم هذا العنصر {property_bag} نفس الترميز مثل سلاسل الاستعلام في بروتوكول HTTPS.

إشعار

إذا كنت تقوم لتوجيه رسائل D2C إلى حساب Azure Storage وتريد الاستفادة من ترميز JSON، يجب تحديد معلومات نوع المحتوى وترميز المحتوى، بما في ذلك $.ct=application%2Fjson&$.ce=utf-8، كجزء من {property_bag} المذكورة في الملاحظة السابقة.

تنسيق هذه السمات خاص بالبروتوكول. يترجم IoT Hub هذه السمات إلى خصائص النظام المقابلة لها. لمزيد من المعلومات، راجع قسم خصائص النظام في بناء جملة استعلام توجيه رسالة IoT Hub.

تصف القائمة التالية السلوكيات الخاصة بتنفيذ IoT Hub:

لا يدعم مركز إنترنت الأشياء رسائل QoS 2. إذا نشر تطبيق جهاز رسالة باستخدام QoS 2، يغلق مركز IoT الاتصال بالشبكة.
لا يحتفظ مركز إنترنت الأشياء برسائل Retain. إذا أرسل جهاز رسالة مع تعيين علامة RETAIN إلى 1، يضيف مركز IoT خاصية تطبيق mqtt-retain إلى الرسالة. يعمل مركز IoT، في هذه الحالة وبدلاً من استمرار رسالة الاستبقاء، على تمريرها إلى التطبيق الخلفي.
يدعم مركز IoT اتصال MQTT نشطا واحدا فقط لكل جهاز. يؤدي أي اتصال MQTT جديد نيابة عن نفس معرف الجهاز إلى إسقاط IoT Hub للاتصال الحالي ويتم تسجيل 400027 ConnectionForcefullyClosedOnNewConnection في سجلات مركز IoT
لتوجيه الرسائل استنادا إلى نص الرسالة، يجب أولا إضافة الخاصية 'contentType' (ct) إلى نهاية موضوع MQTT وتعيين قيمتها لتكون application/json;charset=utf-8 كما هو موضح في المثال التالي. لمزيد من المعلومات حول توجيه الرسائل إما استنادا إلى خصائص الرسالة أو نص الرسالة، راجع وثائق بناء جملة استعلام توجيه رسالة IoT Hub.

devices/{device-id}/messages/events/$.ct=application%2Fjson%3Bcharset%3Dutf-8

لمزيد من المعلومات، راجع إرسال رسائل من جهاز إلى سحابة ومن سحابة إلى جهاز باستخدام IoT Hub.

استلام رسائل سحابة-إلى-جهاز

ينبغي، لاستلام رسائل من مركز IoT، أن يشترك الجهاز باستخدام devices/{device-id}/messages/devicebound/#«كعامل تصفية الموضوع». يتم استخدام حرف البدل # متعدد المستويات في عامل تصفية الموضوع فقط للسماح للجهاز بتلقي المزيد من الخصائص في اسم الموضوع. لا يسمح مركز إنترنت الأشياء بإمكانية استخدام حروف البدل # أو ? لتصفية المواضيع الفرعية. نظرًا لأن مركز إنترنت الأشياء ليس وسيطًا للمراسلة العامة للنشر والاشتراك، فهو يدعم فقط أسماء المواضيع الموثّقة وعوامل تصفية المواضيع. يمكن للجهاز الاشتراك في خمسة مواضيع فقط في كل مرة.

لا يتلقى الجهاز أي رسائل من IoT Hub حتى يشترك بنجاح في نقطة النهاية الخاصة بالجهاز، ممثلة devices/{device-id}/messages/devicebound/# بعامل تصفية الموضوع. يستلم الجهاز، بعد إنشاء اشتراك، رسائل سحابة-إلى-جهاز تم إرسالها إليه بعد وقت الاشتراك. في حالة اتصال الجهاز مع تعيين علامة CleanSession إلى 0، يستمر الاشتراك عبر جلسات عمل مختلفة. في هذه الحالة وفي المرة التالية التي يتصل فيها الجهاز بـ CleanSession 0 يتلقى أي رسائل معلقة يتم إرسالها إليه أثناء عدم الاتصال. إذا كان الجهاز يستخدم علامة CleanSession المعينة إلى 1 ، فإنه لا يتلقى أي رسائل من IoT Hub حتى يشترك في نقطة نهاية الجهاز الخاصة به.

يسلم IoT Hub رسائل باسم الموضوع devices/{device-id}/messages/devicebound/، أو devices/{device-id}/messages/devicebound/{property-bag} عند وجود خصائص رسالة. {property-bag} يحتوي على أزواج مفتاح/قيمة لترميز عنوان URL لخصائص الرسالة. يتم تضمين خصائص التطبيق وخصائص النظام القابلة لتعيين المستخدم فقط (مثل messageId أو correlationId) في مجموعة الخصائص. أسماء خصائص النظام لها البادئة $، تستخدم خصائص التطبيق اسم الخاصية الأصلي دون بادئة. لمزيد من المعلومات حول تنسيق حقيبة الخصائص، راجع إرسال رسائل من جهاز إلى سحابة.

يتم، في رسائل سحابة-إلى-جهاز، عرض القيم في مجموعة الخصائص كما في الجدول التالي:

قيمة الخاصية	التمثيل	‏‏الوصف
`null`	`key`	يظهر المفتاح فقط في مجموعة الخصائص
سلسلة فارغة	`key=`	المفتاح متبوعا بعلامة التساوي دون قيمة
قيمة غير خالية، قيمة غير فارغة	`key=value`	المفتاح متبوعا بعلامة التساوي والقيمة

يوضح المثال التالي مجموعة خصائص تحتوي على ثلاث خصائص لتطبيق: prop1 بقيمة null وprop2 سلسلة فارغة ("") وprop3 بقيمة "سلسلة".

/?prop1&prop2=&prop3=a%20string

عندما يشترك تطبيق جهاز في موضوع باستخدام QoS 2، يمنح مركز IoT الحد الأقصى من مستوى QoS 1 في حزمة SUBACK. يوجه مركز IoT، بعد ذلك، رسائل إلى الجهاز باستخدام QoS 1.

استرداد خصائص جهاز مزدوج

أولا، يشترك الجهاز في $iothub/twin/res/# لتلقي استجابات العملية. ثم يرسل رسالة فارغة إلى الموضوع $iothub/twin/GET/?$rid={request id} مع قيمة تم ملؤها لمعرّف الطلب. ثم ترسل الخدمة رسالة استجابة تحتوي على بيانات الجهاز المزدوج حول الموضوع $iothub/twin/res/{status}/?$rid={request-id}، باستخدام نفس معرّف الطلب مثل الطلب.

يمكن أن يكون معرف الطلب أي قيمة صالحة لقيمة خاصية رسالة، ويتم التحقق من صحة الحالة كعدد صحيح. لمزيد من المعلومات، راجع إرسال رسائل من جهاز إلى سحابة ومن سحابة إلى جهاز باستخدام IoT Hub.

يحتوي نص الاستجابة على قسم خصائص الجهاز المزدوج كما هو موضح في مثال الاستجابة التالي:

{
    "desired": {
        "telemetrySendFrequency": "5m",
        "$version": 12
    },
    "reported": {
        "telemetrySendFrequency": "5m",
        "batteryLevel": 55,
        "$version": 123
    }
}

رموز الحالة المحتملة هي:

‏الحالة	‏‏الوصف
200	نجاح
429	عدد كبير جدا من الطلبات (مقيد). لمزيد من المعلومات، راجع تقييد IoT Hub
5**	أخطاء الخادم

لمزيد من المعلومات، راجع فهم واستخدام الجهاز المزدوج في IoT Hub.

يمكنك تحديث خصائص الجهاز المزدوج المبلغ عنها

يرسل الجهاز، لتحديث الخصائص التي تم الإبلاغ عنها، طلبا إلى مركز IoT عبر منشور حول موضوع MQTT معين. بعد أن يعالج IoT Hub الطلب، يستجيب لحالة النجاح أو الفشل لعملية التحديث عبر منشور لموضوع آخر. يمكن للجهاز الاشتراك في هذا الموضوع لإعلامه بنتيجة طلب التحديث المزدوج الخاص به. يمكننا، لتنفيذ هذا النوع من تفاعل الطلب/الاستجابة في MQTT، استخدام مفهوم معرّف الطلب ($rid) الذي يوفره الجهاز في البداية في طلب التحديث لديه. يتم تضمين معرّف الطلب هذا أيضًا في الاستجابة الواردة من مركز IoT للسماح للجهاز بربط الاستجابة بطلبه السابق المحدد.

يوضح التسلسل التالي كيفية تحديث الجهاز للخصائص المبلغ عنها في الجهاز المزدوج في مركز IoT:

يجب أن يشترك الجهاز أولًا في الموضوع $iothub/twin/res/# لتلقي استجابات العملية من مركز IoT.
يرسل الجهاز رسالة تحتوي على تحديث الجهاز المزدوج للموضوع $iothub/twin/PATCH/properties/reported/?$rid={request-id}. تتضمن هذه الرسالة قيمة معرّف الطلب.
ثم ترسل الخدمة رسالة استجابة تحتوي على قيمة ETag الجديدة لمجموعة الخصائص التي تم الإبلاغ عنها حول الموضوع $iothub/twin/res/{status}/?$rid={request-id}. تستخدم رسالة الاستجابة هذه نفس معرّف الطلب مثل الطلب.

يتضمن نص رسالة الطلب على مستند JSON يحتوي على قيم جديدة للخصائص التي تم الإبلاغ عنها. يعمل كل عضو في مستند JSON على تحديث أو إضافة العضو المطابق في مستند الجهاز المزدوج. عضو معين لحذف null العضو من الكائن المضمن. على سبيل المثال:

{
    "telemetrySendFrequency": "35m",
    "batteryLevel": 60
}

رموز الحالة المحتملة هي:

‏الحالة	‏‏الوصف
204	نجاح (لم يتم إرجاع أي محتوى)
400	Bad Request. JSON تمت صياغته بشكل غير صحيح
429	عدد كبير جدًا من الطلبات (مقيدة) وفقًا لتقييد مركز IoT
5**	أخطاء الخادم

يوضح مقتطف التعليمات البرمجية Python التالي عملية تحديث الخصائص المزدوجة المبلغ عنها عبر MQTT باستخدام عميل Paho MQTT:

from paho.mqtt import client as mqtt

# authenticate the client with IoT Hub (not shown here)

client.subscribe("$iothub/twin/res/#")
rid = "1"
twin_reported_property_patch = "{\"firmware_version\": \"v1.1\"}"
client.publish("$iothub/twin/PATCH/properties/reported/?$rid=" +
               rid, twin_reported_property_patch, qos=0)

عند نجاح عملية تحديث الخصائص المزدوجة المبلغ عنها في قصاصة التعليمات البرمجية السابقة، تحتوي رسالة المنشور من IoT Hub على الموضوع التالي: $iothub/twin/res/204/?$rid=1&$version=6، حيث 204 رمز الحالة يشير إلى النجاح، $rid=1 ويتوافق مع معرف الطلب الذي يوفره الجهاز في التعليمات البرمجية، ويتوافق $version مع إصدار قسم الخصائص المبلغ عنها من الجهاز المزدوج بعد التحديث.

لمزيد من المعلومات، راجع فهم واستخدام الجهاز المزدوج في IoT Hub.

استلام إعلامات تحديث الخصائص المطلوبة

يرسل مركز IoT، عندما اتصال الجهاز، إعلامات إلى الموضوع $iothub/twin/PATCH/properties/desired/?$version={new-version}، والتي تحتوي على محتوى التحديث الذي يتم تنفيذه بواسطة خلفية للحل. على سبيل المثال:

{
    "telemetrySendFrequency": "5m",
    "route": null,
    "$version": 8
}

أما بالنسبة إلى تحديثات الخصائص، فتعني القيم null أنه يتم حذف عضو كائن JSON. أيضًا، يشير $version إلى الإصدار الجديد من قسم الخصائص المطلوبة من الجهاز المزدوج.

هام

يبدأ مركز IoT بإنشاء إعلامات تغيير فقط عند توصيل الأجهزة. تأكد من تنفيذ تدفق إعادة توصيل الجهاز للحفاظ على مزامنة الخصائص المطلوبة بين مركز IoT وتطبيق الجهاز.

لمزيد من المعلومات، راجع فهم واستخدام الجهاز المزدوج في IoT Hub.

استجابة لأسلوب مباشر

يجب أولاً أن يشترك الجهاز في $iothub/methods/POST/#. يرسل مركز IoT طلبات الأسلوب إلى الموضوع $iothub/methods/POST/{method-name}/?$rid={request-id} باستخدام إما JSON صالح أو نص فارغ.

يوجه الجهاز، للاستجابة، رسالة بها JSON صالح أو نص فارغ إلى الموضوع $iothub/methods/res/{status}/?$rid={request-id}. يجب، في هذه الرسالة، أن يتطابق معرّف الطلب مع معرف الطلب الوارد في رسالة الطلب، ويجب أن تكون الحالة عددًا صحيحًا.

لمزيد من المعلومات، راجع فهم واستدعاء الطرق المباشرة من IoT Hub .

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

لمعرفة المزيد حول استخدام MQTT، راجع:

لمعرفة المزيد حول استخدام SDKS لجهاز IoT، راجع:

Azure IoT SDKs

لمعرفة المزيد حول تخطيط توزيع IoT Hub، راجع:

مشاركة عبر

التواصل مع مركز IoT باستخدام بروتوكول MQTT

مقارنة دعم MQTT في مركز IoT وشبكة الأحداث

الاتصال بمركز IoT

استخدام حزم SDK للجهاز

مهلة افتراضية لاتصال مستمر

ترحيل تطبيق جهاز من AMQP إلى MQTT

استخدام بروتوكول MQTT مباشرة (كجهاز)

استخدام ملحق Azure IoT Hub ل Visual Studio Code

استخدام بروتوكول MQTT مباشرة (كوحدة نمطية)

عينات تستخدم MQTT بدون Azure IoT SDK

تكوين TLS/SSL

إرسال رسائل جهاز-إلى-سحابة

استلام رسائل سحابة-إلى-جهاز

استرداد خصائص جهاز مزدوج

يمكنك تحديث خصائص الجهاز المزدوج المبلغ عنها

استلام إعلامات تحديث الخصائص المطلوبة

استجابة لأسلوب مباشر

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

الملاحظات

الموارد الإضافية