دعم IoT Hub MQTT 5 (مهمل)

الإصدار: 2.0 api-version: 2020-10-01-preview

يُعرف هذا المستند واجهة برمجة تطبيقات مستوى بيانات IoT Hub عبر بروتوكول MQTT الإصدار 5.0. راجع مرجع واجهة برمجة التطبيقات للتعريفات الكاملة في واجهة برمجة التطبيقات هذه.

المتطلبات الأساسية

• إنشاء مركز IoT جديد تماما مع تمكين وضع المعاينة. يتوفر MQTT 5 فقط في وضع المعاينة، ولا يمكنك تبديل مركز IoT موجود إلى وضع المعاينة. لمزيد من المعلومات، راجع تمكين وضع المعاينة
• معرفة مسبقة بمواصفات MQTT 5.

مستوى الدعم والقيود

دعم IoT Hub لـ MQTT 5 قيد المعاينة ومحدود بالطرق التالية (يتم توصيله إلى العميل عبر CONNACK الخصائص ما لم يتم ذكر خلاف ذلك صراحة):

• لا يوجد دعم رسمي ل SDKs لجهاز Azure IoT حتى الآن.
• معرفات الاشتراك غير مدعومة.
• الاشتراكات المشتركة غير مدعومة.
• RETAIN غير مدعوم.
• Maximum QoS عبارة عن 1.
• Maximum Packet Size 256 KiB (يخضع لمزيد من القيود لكل عملية).
• معرفات العميل المعينة غير مدعومة.
• Keep Alive يقتصر على 19 min (الحد الأقصى للتأخير لفحص الفعالية – 28.5 min).
• Topic Alias Maximum عبارة عن 10.
• Response Information غير مدعوم؛ CONNACK لا يرجع الخاصية Response Information حتى لو كانت CONNECT تحتوي على خاصية Request Response Information.
• Receive Maximum (الحد الأقصى لعدد حزم البيانات المعلقة المسموح بها غير المعترف بها PUBLISH (في اتجاه من عميل إلى خادم) مع QoS: 1) هو 16.
• لا يمكن أن يكون للعميل الواحد أكثر من 50 اشتراك. إذا وصل العميل إلى حد الاشتراك، SUBACK فسترجع 0x97 رمز سبب (تجاوز الحصة النسبية) للاشتراكات.

دورة حياة الاتصال

الاتصال

لتوصيل عميل بـ IoT Hub باستخدام واجهة برمجة التطبيقات هذه، قم بإنشاء اتصال لكل مواصفات MQTT 5. يجب على العميل إرسال حزمة البيانات CONNECT في غضون 30 ثانية بعد تأكيد اتصال TLS الناجح، أو يقوم الخادم بإغلاق الاتصال. وإليك مثال على حزمة بيانات CONNECT:

-> CONNECT
    Protocol_Version: 5
    Clean_Start: 0
    Client_Id: D1
    Authentication_Method: SAS
    Authentication_Data: {SAS bytes}
    api-version: 2020-10-10
    host: abc.azure-devices.net
    sas-at: 1600987795320
    sas-expiry: 1600987195320
    client-agent: artisan;Linux

• الخاصية Authentication Method مطلوبة وتحدد أسلوب المصادقة المستخدم. لمزيد من المعلومات حول أسلوب المصادقة، راجع المصادقة.
• Authentication Data تعتمد معالجة الخصائص على Authentication Method. إذا تم تعيين Authentication Method إلى SAS، فهذا Authentication Data مطلوب ويجب أن يحتوي على توقيع صالح. لمزيد من المعلومات حول بيانات المصادقة، راجع المصادقة.
• الخاصية api-version مطلوبة ويجب تعيينها إلى قيمة إصدار واجهة برمجة التطبيقات المتوفرة في عنوان هذه المواصفات لتطبيق هذه المواصفات.
• تحدد الخاصية host اسم المضيف للمستأجر. وهو مطلوب ما لم يتم تقديم ملحق SNI في سجل Client Hello أثناء تأكيد اتصال TLS
• sas-at يحدد وقت الاتصال.
• sas-expiry يحدد وقت انتهاء الصلاحية لـ SAS المتوفر.
• client-agent يقوم بشكل اختياري بتوصيل معلومات حول العميل الذي يقوم بإنشاء الاتصال.

يستجيب IoT Hub مع حزمة بيانات CONNACK بمجرد الانتهاء من المصادقة وإحضار البيانات لدعم الاتصال. إذا تم تأسيس الاتصال بنجاح، يبدو CONNACK كما يلي:

<- CONNACK
    Session_Present: 1
    Reason_Code: 0x00
    Session_Expiry_Interval: 0xFFFFFFFF # included only if CONNECT specified value less than 0xFFFFFFFF and more than 0x00
    Receive_Maximum: 16
    Maximum_QoS: 1
    Retain_Available: 0
    Maximum_Packet_Size: 262144
    Topic_Alias_Maximum: 10
    Subscription_Identifiers_Available: 0
    Shared_Subscriptions_Available: 0
    Server_Keep_Alive: 1140 # included only if client did not specify Keep Alive or if it specified a bigger value

خصائص حزمة البيانات هذه CONNACK تتبع مواصفات MQTT 5. وهي تعكس إمكانات IoT Hub.

المصادقة

تعرف الخاصية Authentication Method على العميل CONNECT نوع المصادقة التي يستخدمها لهذا الاتصال:

• SAS - يتم توفير توقيع الوصول المشترك في خاصية CONNECT Authentication Data،
• X509 - يعتمد العميل على مصادقة شهادة العميل.

تفشل المصادقة إذا لم تتطابق طريقة المصادقة مع أسلوب العميل الذي تم تكوينه في IoT Hub.

مصادقة اسم المستخدم/كلمة المرور المستخدمة في إصدارات واجهة برمجة التطبيقات السابقة غير مدعومة.

SAS

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

يجب تشكيل سلسلة لتوقيعها على النحو التالي:

{host name}\n
{Client Id}\n
{sas-policy}\n
{sas-at}\n
{sas-expiry}\n

• host name مشتق إما من ملحق SNI (المقدم من قبل العميل في سجل Client Hello أثناء تأكيد اتصال TLS) أو خاصية المستخدم host في حزمة بيانات CONNECT.
• Client Id هو معرف العميل في حزمة بيانات CONNECT.
• sas-policy - إذا كان موجودًا، يحدد نهج الوصول إلى IoT Hub المستخدم للمصادقة. يتم ترميزه كخاصية مستخدم على حزمة بيانات CONNECT. اختياري: يعني حذف ذلك استخدام إعدادات المصادقة في سجل الجهاز بدلا من ذلك.
• sas-at - إذا كان موجودًا، يحدد وقت الاتصال - الوقت الحالي. يتم ترميزه كخاصية مستخدم من نوع time على حزمة بيانات CONNECT.
• sas-expiry يحدد وقت انتهاء الصلاحية للمصادقة. إنها خاصية مستخدم timeمكتوبة على حزمة بيانات CONNECT. هذه الخاصية مطلوبة.

بالنسبة للمعلمات الاختيارية، إذا تم حذفها، يجب استخدام سلسلة فارغة بدلاً من ذلك في السلسلة للتوقيع.

يتم استخدام HMAC-SHA256 لتجزئة السلسلة استنادًا إلى أحد المفاتيح المتماثلة للجهاز. ثم يتم تعيين قيمة التجزئة كقيمة للخاصية Authentication Data.

X509

إذا تم تعيين الخاصية Authentication Method إلى X509، يقوم IoT Hub بمصادقة الاتصال استنادًا إلى شهادة العميل المتوفرة.

Reauthentication

إذا تم استخدام المصادقة المستندة إلى SAS، نوصي باستخدام رموز المصادقة المميزة قصيرة الأجل. للحفاظ على مصادقة الاتصال ومنع قطع الاتصال بسبب انتهاء الصلاحية، يجب على العميل إعادة المصادقة عن طريق إرسال حزمة بيانات AUTH مع Reason Code: 0x19 (إعادة المصادقة):

-> AUTH
    Reason_Code: 0x19
    Authentication_Method: SAS
    Authentication_Data: {SAS bytes}
    sas-at: {current time}
    sas-expiry: {SAS expiry time}

القواعد:

• Authentication Method يجب أن يكون هو نفسه المستخدم للمصادقة الأولية
• إذا تمت مصادقة الاتصال في الأصل باستخدام SAS استنادًا إلى نهج الوصول المشترك، فيجب أن يستند التوقيع المستخدم في إعادة المصادقة إلى نفس النهج.

إذا نجحت إعادة المصادقة، يرسل IoT Hub حزمة بيانات AUTH مع Reason Code: 0x00 (نجاح). وإلا، يرسل IoT Hub حزمة بيانات DISCONNECT مع Reason Code: 0x87 (غير مصرح به) ويغلق الاتصال.

قطع الاتصال

يمكن للخادم قطع اتصال العميل لعدة أسباب، بما في ذلك:

• يسيء العميل التصرف بطريقة يستحيل الرد عليها بإقرار سلبي (أو استجابة) مباشرة،
• فشل الخادم في الحفاظ على حالة الاتصال محدثة،
• يتصل عميل آخر بنفس الهوية.

قد يقطع الخادم الاتصال بأي تعليمة برمجية لسبب من الأسباب التي تم تحديدها في مواصفات MQTT 5.0. إشارات ملحوظة:

• 135 (غير مصرح به) عند فشل إعادة المصادقة أو انتهاء صلاحية رمز SAS الحالي أو تغيير بيانات اعتماد الجهاز.
• 142 (تم السيطرة على الجلسة) عند فتح اتصال جديد بنفس هوية العميل.
• 159 (تم تجاوز معدل الاتصال) عندما يتجاوز معدل الاتصال لمركز IoT الحد.
• 131 يُستخدم (خطأ خاص بالتنفيذ) لأي أخطاء مخصصة معرفة في واجهة برمجة التطبيقات هذه. statusreason وتستخدم الخصائص لتوصيل مزيد من التفاصيل حول سبب قطع الاتصال (راجع الاستجابة للحصول على التفاصيل).

العمليات

يتم التعبير عن جميع الوظائف في واجهة برمجة التطبيقات هذه كعمليات. فيما يلي مثال على عملية "إرسال بيانات تتبع الاستخدام":

-> PUBLISH
    QoS: 1
    Packet_Id: 3
    Topic: $iothub/telemetry
    Payload: Hello

<- PUBACK
    Packet_Id: 3
    Reason_Code: 0

للحصول على مواصفات كاملة للعمليات في واجهة برمجة التطبيقات هذه، راجع مرجع MQTT 5 API لمستوى بيانات IoT Hub.

موضوعات واشتراكات الرسائل

تبدأ الموضوعات المستخدمة في رسائل العمليات في واجهة برمجة التطبيقات هذه بـ $iothub/. لا تنطبق دلالات وسيط MQTT على هذه العمليات (راجع "الموضوعات التي تبدأ بـ $" للحصول على التفاصيل). الموضوعات التي تبدأ بـ $iothub/ التي لم يتم تعريفها في واجهة برمجة التطبيقات هذه غير مدعومة:

• يؤدي إرسال رسائل إلى موضوع Not Found غير معرف إلى الاستجابة (راجع الاستجابة للحصول على التفاصيل)،
• يؤدي الاشتراك في موضوع غير معرف إلى SUBACK مع Reason Code: 0x8F (عامل تصفية غير صالح للموضوع).

أسماء الموضوعات وأسماء الخصائص حساسة لحالة الأحرف ويجب أن تكون متطابقة تمامًا. على سبيل المثال، $iothub/telemetry/ غير مدعوم، بينما $iothub/telemetry مدعوم.

أنواع التفاعل

تستند جميع العمليات في واجهة برمجة التطبيقات هذه إلى أحد نوعي التفاعل:

• رسالة مع رسالة إقرار اختيارية (MessageAck)
• طلب-رد (ReqRep)

تختلف العمليات أيضًا حسب الاتجاه (يتم تحديدها حسب اتجاه الرسالة الأولية في المقابل):

• عميل إلى خادم (c2s)
• خادم إلى عميل (s2c)

على سبيل المثال، "إرسال بيانات تتبع الاستخدام" هي عملية "من عميل إلى خادم" من نوع "رسالة مع رسالة إقرار"، بينما "معالجة الأسلوب المباشر" هي عملية من "خادم إلى عميل" من نوع "طلب-رد".

تفاعلات رسالة الإقرار

يتم التعبير عن الرسالة ذات تفاعل الإقرار الاختياري (MessageAck) كتبادل لحزم بيانات PUBLISH وPUBACK في MQTT. الإقرار اختياري ويمكن للمرسل اختيار عدم طلبه عن طريق إرسال PUBLISH الحزمة باستخدام QoS: 0.

مثال على تفاعل MessageAck البسيط

رسالة:

PUBLISH
    QoS: 1
    Packet_Id: 34
    Topic: $iothub/{request.path}
    Payload: <any>

رسالة الإقرار (نجاح):

PUBACK
    Packet_Id: 34
    Reason_Code: 0

تفاعلات طلب-رد

في تفاعلات طلب-رد (ReqRep)، يترجم كل من "الطلب" و"الاستجابة" إلى حزمة بيانات PUBLISH باستخدام QoS: 0.

يجب تعيين الخاصية Correlation Data في كليهما ويتم استخدامها لمطابقة حزمة بيانات "الاستجابة" مع حزمة بيانات "الطلب".

تستخدم واجهة برمجة التطبيقات هذه موضوع استجابة واحدًا $iothub/responses لجميع عمليات ReqRep. الاشتراك في / إلغاء الاشتراك من هذا الموضوع لعمليات عميل إلى خادم غير مطلوب - يفترض الخادم اشتراك جميع العملاء.

مثال على تفاعل ReqRep البسيط

طلب:

PUBLISH
    QoS: 0
    Topic: $iothub/{request.path}
    Correlation_Data: 0x01 0xFA
    Payload: ...

الاستجابة (نجاح):

PUBLISH
    QoS: 0
    Topic: $iothub/responses
    Correlation_Data: 0x01 0xFA
    Payload: ...

لا تدعم تفاعلات ReqRep حزم بيانات PUBLISH مع QoS: 1 كرسائل طلب أو استجابة. يؤدي إرسال الطلب PUBLISH إلى استجابة Bad Request.

الحد الأقصى للطول المدعوم في خاصية Correlation Data هو 16 بايت. إذا تم تعيين الخاصية Correlation Data على حزمة بيانات PUBLISH إلى قيمة أطول من 16 بايت، يرسل IoT Hub DISCONNECT مع نتيجة Bad Request، ويغلق الاتصال. ينطبق هذا السلوك فقط على حزم البيانات المتبادلة داخل واجهة برمجة التطبيقات هذه.

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

خصائص الرسالة

يتم التعبير عن خصائص العملية - النظام أو المستخدم المعرف - كخصائص حزمة بيانات في MQTT 5.

أسماء خصائص المستخدم حساسة لحالة الأحرف ويجب كتابتها بالضبط كما هو محدد. على سبيل المثال، Trace-ID غير مدعوم، بينما trace-id مدعوم.

تؤدي الطلبات ذات خصائص المستخدم خارج المواصفات وبدون بادئة @ إلى خطأ.

يتم ترميز خصائص النظام إما كخصائص من الدرجة الأولى (على سبيل المثال، Content Type) أو "كخصائص المستخدم". توفر المواصفات قائمة شاملة بخصائص النظام المدعومة. يتم تجاهل جميع خصائص الفئة الأولى ما لم يذكر دعمها صراحة في المواصفات.

حيث يتم السماح بالخصائص المعرفة من قبل المستخدم، يجب أن تتبع أسماءها التنسيق @{property name}. تدعم الخصائص المعرفة من قبل المستخدم قيم سلسلة UTF-8 صالحة فقط. على سبيل المثال، يجب ترميز الخاصية MyProperty1 ذات القيمة 15 "كخاصية مستخدم" بالاسم @MyProperty والقيمة 15.

إذا لم يتعرف IoT Hub على خاصية المستخدم، فإنه يعتبر خطأ، ويستجيب IoT Hub مع PUBACK Reason Code: 0x83 (خطأ خاص بالتنفيذ) و status: 0100 (طلب غير صحيح). إذا لم يتم طلب الإقرار (QoS: 0)، DISCONNECT يتم إرسال الحزمة التي لها نفس الخطأ مرة أخرى ويتم إنهاء الاتصال.

تحدد واجهة برمجة التطبيقات هذه أنواع البيانات التالية بالإضافة إلى string:

• time: عدد المللي ثانية منذ 1970-01-01T00:00:00.000Z. على سبيل المثال، 1600987195320 لـ 2020-09-24T22:39:55.320Z،
• u32: رقم عدد صحيح 32 بت غير موقع،
• u64: رقم عدد صحيح 64 بت غير موقع،
• i32: رقم عدد صحيح 32 بت مُوقع.

استجابة

يمكن أن تؤدي التفاعلات إلى نتائج مختلفة: Success وBad Request وNot Found وغيرها. يتم تمييز النتائج عن بعضها البعض بواسطة خاصية المستخدم status. Reason Code في حزم بيانات PUBACK (لتفاعلات MessageAck) يتطابق مع status في المعنى حيثما أمكن ذلك.

كل تفاعل له إعداد افتراضي (أو نجاح). يحتوي على Reason Code بخصائص 0 وstatus من "لم يتم التعيين". وإلا:

• بالنسبة لتفاعلات MessageAck، يحصل PUBACK على Reason Code غير 0x0 (نجاح). قد تكون الخاصية status موجودة لتوضيح النتيجة بشكل أكبر.
• بالنسبة لتفاعلات ReqRep، تحصل الاستجابة PUBLISH على مجموعة الخصائص status.
• نظرًا لعدم وجود طريقة للاستجابة لتفاعلات MessageAck مع QoS: 0مباشرة، يتم إرسال حزمة بيانات DISCONNECT بدلاً من ذلك بمعلومات الاستجابة، متبوعة بقطع الاتصال.

أمثلة:

طلب غير صحيح (MessageAck):

PUBACK
    Reason_Code: 131
    status: 0100
    reason: Unknown property `test`

غير مصرح به (MessageAck):

PUBACK
    Reason_Code: 135
    status: 0101

غير مصرح به (ReqRep):

PUBLISH
    QoS: 0
    Topic: $iothub/responses
    Correlation_Data: ...
    status: 0101

عند الحاجة، يقوم IoT Hub بتعيين خصائص المستخدم التالية:

• status - التعليمات البرمجية الموسعة لـ IoT Hub لحالة العملية. يمكن استخدام هذه التعليمة البرمجية للتمييز بين النتائج.
• trace-id - معرف التتبع للعملية؛ قد يحتفظ IoT Hub بمزيد من التشخيصات المتعلقة بالعملية التي يمكن استخدامها للتحقيق الداخلي.
• reason - رسالة يمكن للبشر قراءتها توفر معلومات إضافية حول سبب انتهاء العملية في حالة تشير إليها خاصية status.

كود الحالة

تحمل الخاصية status التعليمة البرمجية للحالة للعملية. تم تحسينها لكفاءة قراءة الجهاز. وهي تتكون من عدد صحيح غير موقع ثنائي البايت مرمز كسداسي عشري في سلسلة مثل 0501. بنية التعليمات البرمجية (مخطط بت):

7 6 5 4 3 2 1 0 | 7 6 5 4 3 2 1 0
0 0 0 0 0 R T T | C C C C C C C C

يتم استخدام البايت الأول للعلامات:

• تشير البتات 0 و1 إلى نوع النتائج:
  • 00 - نجاح
  • 01 - خطأ العميل
  • 10 - خطأ الخادم
• بت 2: 1 يشير إلى أن الخطأ قابل لإعادة المحاولة
• البت من 3 إلى 7 محجوزة ويجب تعيينها إلى 0

يحتوي البايت الثاني على رمز استجابة مميز فعلي. يمكن أن تحتوي رموز الخطأ ذات العلامات المختلفة على نفس قيمة البايت الثانية. على سبيل المثال، يمكن أن تكون رموز الخطأ 0001 و0101 و0201 و0301 لها معنى مميز.

على سبيل المثال، Too Many Requests هو عميل، خطأ قابل لإعادة المحاولة مع الرمز الخاص به لـ 1. القيمة هي 0000 0101 0000 0001 أو 0x0501.

قد يستخدم العملاء وحدات بت النوع لتحديد ما إذا كانت العملية قد انتهت بنجاح. قد يستخدم العملاء أيضًا بت قابل لإعادة المحاولة لتحديد ما إذا كان من المعقول إعادة محاولة العملية.

التوصيات

إدارة جلسات العمل

تحمل حزمة بيانات CONNACK خاصية Session Present للإشارة إلى ما إذا كان الخادم قد قام باستعادة جلسة العمل التي تم إنشاؤها مسبقًا. استخدم هذه الخاصية لمعرفة ما إذا كنت تريد الاشتراك في الموضوعات أو تخطي الاشتراك بما أن الاشتراك تم في وقت سابق.

للاعتماد على Session Present، يجب على العميل تعقب الاشتراكات التي تم إجراؤها (أي حزمة البيانات SUBSCRIBE المرسلة وSUBACK المستلمة بالتعليمة البرمجية لسبب ناجح)، أو التأكد من الاشتراك في جميع الموضوعات في تبادل واحدSUBSCRIBE/SUBACK. وإلا، إذا أرسل العميل حزمتين SUBSCRIBE ، وكان الخادم يعالج حزمة واحدة فقط بنجاح، يتصل Session Present: 1 الخادم أثناء CONNACK قبول جزء فقط من اشتراكات العميل.

لمنع الحالة التي لم يشترك فيها إصدار أقدم من العميل في جميع الموضوعات، من الأفضل الاشتراك دون شروط عند تغيير سلوك العميل (على سبيل المثال، كجزء من تحديث البرنامج الثابت). أيضًا، لضمان عدم ترك أي اشتراكات قديمة (أخذ من الحد الأقصى المسموح به لعدد الاشتراكات)، قم بإلغاء الاشتراك صراحة من الاشتراكات التي لم تعد قيد الاستخدام.

الدفعات

لا يوجد تنسيق خاص لإرسال دفعة من الرسائل. لتقليل النفقات العامة للعمليات كثيفة الموارد في TLS والشبكات، قم بتجميع حزم البيانات (PUBLISH وPUBACK وSUBSCRIBE، وهكذا) معًا قبل تسليمها إلى مكدس TLS/TCP الأساسي. أيضًا، يمكن للعميل تسهيل الاسم المستعار للموضوع ضمن "الدفعة":

• ضع اسم الموضوع الكامل في حزمة البيانات الأولى PUBLISH للاتصال وإقران الاسم المستعار للموضوع به،
• ضع حزمة البيانات التالية لنفس الموضوع مع اسم موضوع فارغ وخاصية اسم مستعار للموضوع فارغة.

الترحيل

يسرد هذا القسم التغييرات في واجهة برمجة التطبيقات مقارنة بدعم MQTT السابق.

• بروتوكول النقل هو MQTT 5. سابقًا - MQTT 3.1.1.
• يتم تضمين معلومات السياق لمصادقة SAS في حزمة بيانات CONNECT مباشرة بدلاً من ترميزها مع التوقيع.
• يتم استخدام "أسلوب المصادقة" للإشارة إلى أسلوب المصادقة المستخدم.
• يتم وضع "توقيع الوصول المشترك" في خاصية "بيانات المصادقة". تم استخدام حقل "كلمة المرور سابقًا".
• مواضيع العمليات مختلفة:
  • بيانات تتبع الاستخدام: $iothub/telemetry بدلاً من devices/{Client Id}/messages/events،
  • الأوامر: $iothub/commands بدلاً من devices/{Client Id}/messages/devicebound،
  • تم الإبلاغ عن توأم التصحيح: $iothub/twin/patch/reported بدلاً من $iothub/twin/PATCH/properties/reported،
  • إعلام حالة التوأم المرغوبة التي تم تغييرها: $iothub/twin/patch/desired بدلاً من $iothub/twin/PATCH/properties/desired.
• الاشتراك لموضوع استجابة عمليات طلب-رد من عميل إلى خادم غير مطلوب.
• يتم استخدام خصائص المستخدم بدلاً من ترميز الخصائص في مقطع اسم الموضوع.
• يتم كتابة أسماء الخصائص في إصلاح التسمية "حالة شرطة" بدلاً من الاختصارات ذات البادئة الخاصة. تتطلب الخصائص المعرفة من قبل المستخدم الآن بادئة بدلاً من ذلك. على سبيل المثال، $.mid هو الآن message-id، بينما myProperty1 يصبح @myProperty1.
• يتم استخدام خاصية "بيانات الارتباط" لربط رسائل الطلب والاستجابة لعمليات طلب-رد بدلاً من الخاصية $rid المرمزة في الموضوع.
• لم يعد يتم إضافة طابع على الخاصية iothub-connection-auth-method على أحداث بيانات تتبع الاستخدام.
• لا يتم إزالة أوامر C2D في غياب الاشتراك من الجهاز. تظل في قائمة الانتظار حتى يشترك الجهاز أو تنتهي صلاحيتها.

الأمثلة

إرسال بيانات تتبع الاستخدام

رسالة:

-> PUBLISH
    QoS: 1
    Packet_Id: 31
    Topic: $iothub/telemetry
    @myProperty1: My String Value # optional
    creation-time: 1600987195320 # optional
    @ No_Rules-ForUser-PROPERTIES: Any UTF-8 string value # optional
    Payload: <data>

رسالة الإقرار:

<- PUBACK
    Packet_Id: 31
    Reason_Code: 0

رسالة الإقرار البديل (مقيدة):

<- PUBACK
    Packet_Id: 31
    Reason_Code: 151
    status: 0501

---

إرسال حالة الحصول على التوأم

طلب:

-> PUBLISH
    QoS: 0
    Topic: $iothub/twin/get
    Correlation_Data: 0x01 0xFA
    Payload: <empty>

الاستجابة (نجاح):

<- PUBLISH
    QoS: 0
    Topic: $iothub/responses
    Correlation_Data: 0x01 0xFA
    Payload: <twin/desired state>

الاستجابة (غير مسموح بها):

<- PUBLISH
    QoS: 0
    Topic: $iothub/responses
    Correlation_Data: 0x01 0xFA
    status: 0102
    reason: Operation not allowed for `B2` SKU
    Payload: <empty>

---

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

طلب:

<- PUBLISH
    QoS: 0
    Topic: $iothub/methods/abc
    Correlation_Data: 0x0A 0x10
    Payload: <data>

الاستجابة (نجاح):

-> PUBLISH
    QoS: 0
    Topic: $iothub/responses
    Correlation_Data: 0x0A 0x10
    response-code: 200 # user defined response code
    Payload: <data>

استجابة الجهاز غير المتوفرة:

-> PUBLISH
    QoS: 0
    Topic: $iothub/responses
    Correlation_Data: 0x0A 0x10
    status: 0603

---

خطأ أثناء استخدام QoS 0، الجزء 1

طلب:

-> PUBLISH
    QoS: 0
    Topic: $iothub/twin/gett # misspelled topic name - server won't recognize it as Request-Response interaction
    Correlation_Data: 0x0A 0x10
    Payload: <data>

الاستجابة:

<- DISCONNECT
    Reason_Code: 144
    reason: "Unsupported topic: `$iothub/twin/gett`"

---

خطأ أثناء استخدام QoS 0، الجزء 2

طلب:

-> PUBLISH # missing Correlation Data
    QoS: 0
    Topic: $iothub/twin/get
    Payload: <data>

الاستجابة:

<- DISCONNECT
    Reason_Code: 131
    status: 0100
    reason: "`Correlation Data` property is missing"

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

• لمراجعة مرجع MQTT 5 preview API، راجع مرجع MQTT 5 API لمستوى بيانات IoT Hub (معاينة).
• لمتابعة نموذج C#، راجع مستودع نموذج GitHub.