إنشاء رسائل IoT Hub وقراءتها

  • مقالة

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

إشعار

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

يقوم IoT Hub بتنفيذ المراسلة من جهاز إلى سحابة باستخدام نمط مراسلة دفق. تشبه رسائل IoT Hub من جهاز إلى شبكة سحابية أحداث مراكز الأحداث أكثر من رسائل ناقل خدمة Microsoft Azure حيث يوجد عدد كبير من الأحداث التي تمر عبر الخدمة والتي يمكن قراءتها من قبل العديد من القراء.

تتكون رسالة IoT Hub من:

  • مجموعة محددة مسبقًا من خصائص النظام كما هو موضح أدناه.

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

  • نص الرسالة، والذي يمكن أن يكون أي نوع من البيانات.

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

يمكن أن تحتوي أسماء وقيم الخصائص على أحرف أبجدية رقمية ASCII فقط، بالإضافة إلى {'!', '#', '$', '%, '&', ''', '*', '+', '-', '.', '^', '_', '`', '|', '~'} عند إرسال رسائل من جهاز إلى السحابة باستخدام بروتوكول HTTPS أو إرسال رسائل من السحابة إلى جهاز.

تتميز المراسلة من جهاز إلى سحابة باستخدام IoT Hub بالخصائص التالية:

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

  • يمكن أن تصل الرسائل من الجهاز إلى السحابة إلى 256 كيلوبايت كحد أقصى، ويمكن تجميعها على دفعات لتحسين عمليات إرسال. يمكن أن تكون الدُفعات 256 كيلوبايت بحد أقصى.

  • لا يسمح IoT Hub بالتقسيم التحكمي. يتم تقسيم الرسائل من جهاز إلى سحابة استنادًا إلى deviceIdالأصلي.

  • كما هو موضح في Control access to IoT Hub، يتيح IoT Hub المصادقة لكل جهاز والتحكم في الوصول.

  • يمكنك وضع طابع على الرسائل بمعلومات تنتقل إلى خصائص التطبيق. لمزيد من المعلومات، يرجى الاطلاع على تحسينات الرسائل.

لمزيد من المعلومات بشأن كيفية ترميز وفك ترميز الرسائل المرسلة باستخدام بروتوكولات مختلفة، راجع Azure IoT SDKs.

إشعار

يوفر كل بروتوكول IoT Hub خاصية نوع محتوى الرسالة التي يتم احترامها عند توجيه البيانات إلى نقاط نهاية مخصصة. لكي تتم معالجة بياناتك بشكل صحيح في الوجهة (على سبيل المثال، يتم التعامل مع JSON كسلسلة قابلة للتحليل بدلاً من البيانات الثنائية المشفرة Base64)، يجب توفير نوع المحتوى المناسب ومجموعة الأحرف المناسبة للرسالة.

لاستخدام نص رسالتك في استعلام توجيه IoT Hub، يجب تقديم عنصر JSON صالح للرسالة وتعيين خاصية نوع المحتوى للرسالة على application/json;charset=utf-8.

قد يبدو نص الرسالة الصالح والقابل للتوجيه كما يلي:

{
    "timestamp": "2022-02-08T20:10:46Z",
    "tag_name": "spindle_speed",
    "tag_value": 100
}

خصائص النظام لرسائل D2C IoT Hub

الخاصية ‏‏الوصف User Settable? الكلمة الرئيسية لاستعلام التوجيه
message-id معرّف يمكن للمستخدم تعيينه للرسالة المستخدمة لأنماط الرد على الطلب. التنسيق: سلسلة حساسة لحالة الأحرف (يصل طولها إلى 128 حرفاً) تتكون من 7 بتات من الأحرف الأبجدية الرقمية ASCII + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. ‏‏نعم‬ messageId
iothub-enqueuedtime تاريخ ووقت تلقي IoT Hub لرسالة Device-to-Cloud. لا enqueuedTime
user-id معرف يستخدم لتحديد أصل الرسائل. عندما يتم إنشاء رسائل بواسطة IoT Hub، يتم تعيينها على {iot hub name}. ‏‏نعم‬ userId
iothub-connection-device-id معرّف تم تعيينه بواسطة IoT Hub على رسائل من جهاز إلى سحابة. يحتوي على deviceId الجهاز الذي أرسل الرسالة. لا connectionDeviceId
iothub-connection-module-id معرّف تم تعيينه بواسطة IoT Hub على رسائل من جهاز إلى سحابة. يحتوي على moduleId الجهاز الذي أرسل الرسالة. لا connectionModuleId
iothub-connection-auth-generation-id معرّف تم تعيينه بواسطة IoT Hub على رسائل من جهاز إلى سحابة. يحتوي على connectionDeviceGenerationId (وفقاً لـ خصائص هوية الجهاز) للجهاز الذي أرسل الرسالة. لا connectionDeviceGenerationId
iothub-connection-auth-method أسلوب مصادقة تم تعيينه بواسطة IoT Hub على رسائل من جهاز إلى سحابة. تحتوي هذه الخاصية على معلومات حول أسلوب المصادقة المستخدم لمصادقة الجهاز الذي يرسل الرسالة. لا connectionAuthMethod
iothub-app-iothub-creation-time-utc يسمح للجهاز بإرسال وقت إنشاء الحدث عند إرسال البيانات دفعة واحدة. ‏‏نعم‬ creation-time-utc
iothub-creation-time-utc يسمح للجهاز بإرسال وقت إنشاء الحدث عند إرسال رسالة واحدة في كل مرة. ‏‏نعم‬ creation-time-utc
dt-dataschema يتم تعيين هذه القيمة بواسطة IoT hub على الرسائل من جهاز إلى سحابة. تحتوي على معرّف طراز الجهاز الذي تم تعيينه في اتصال الجهاز. لا $dt-dataschema
dt-subject اسم المكوّن الذي يقوم بإرسال رسائل من جهاز إلى سحابة. ‏‏نعم‬ $dt-subject

خصائص التطبيق لرسائل D2C IoT Hub

الاستخدام الشائع لخصائص التطبيق هو إرسال طابع زمني من الجهاز باستخدام الخاصية iothub-creation-time-utc لتسجيل وقت إرسال الرسالة بواسطة الجهاز. يجب أن يكون تنسيق هذا الطابع الزمني بالتوقيت العالمي المتفق عليه دون معلومات عن المنطقة الزمنية. على سبيل المثال، 2021-04-21T11:30:16Z صالح، 2021-04-21T11:30:16-07:00 غير صالح:

{
  "applicationId":"5782ed70-b703-4f13-bda3-1f5f0f5c678e",
  "messageSource":"telemetry",
  "deviceId":"sample-device-01",
  "schema":"default@v1",
  "templateId":"urn:modelDefinition:mkuyqxzgea:e14m1ukpn",
  "enqueuedTime":"2021-01-29T16:45:39.143Z",
  "telemetry":{
    "temperature":8.341033560421833
  },
  "messageProperties":{
    "iothub-creation-time-utc":"2021-01-29T16:45:39.021Z"
  },
  "enrichments":{}
}

خصائص النظام لرسائل C2D IoT Hub

الخاصية ‏‏الوصف User Settable?
message-id معرّف يمكن للمستخدم تعيينه للرسالة المستخدمة لأنماط الرد على الطلب. التنسيق: سلسلة حساسة لحالة الأحرف (يصل طولها إلى 128 حرفاً) تتكون من 7 بتات من الأحرف الأبجدية الرقمية ASCII + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. ‏‏نعم‬
sequence-number رقم (فريد لكل قائمة انتظار أجهزة) تم تعيينه بواسطة IoT Hub لكل رسالة من سحابة إلى جهاز. لا
to وجهة محددة في رسائل Cloud-to-Device. لا
absolute-expiry-time تاريخ ووقت انتهاء صلاحية الرسالة. ‏‏نعم‬
correlation-id خاصية سلسلة في رسالة استجابة تحتوي عادة على MessageId الطلب في أنماط الرد على الطلب. ‏‏نعم‬
user-id معرف يستخدم لتحديد أصل الرسائل. عندما يتم إنشاء رسائل بواسطة IoT Hub، يتم تعيينها على {iot hub name}. ‏‏نعم‬
iothub-ack مُنشئ رسالة ملاحظات. يتم استخدام هذه الخاصية في رسائل سحابة إلى جهاز لطلب IoT Hub لإنشاء رسائل ملاحظات كنتيجة لاستهلاك الرسالة من قبل الجهاز. القيم المحتملة: none (افتراضية): لم يتم إنشاء رسالة ملاحظات، positive: تلقي رسالة ملاحظات إذا تم إكمال الرسالة، negative: تلقي رسالة ملاحظات إذا انتهت مدة صلاحية الرسالة (أو تم الوصول إلى الحد الأقصى لعدد التسليم) دون إكمالها من قبل الجهاز، أو full: positive وnegative في نفس الوقت. ‏‏نعم‬

أسماء خصائص النظام

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

اسم خاصية النظام مراكز الأحداث تخزين Azure ناقل الخدمة Event Grid
معرّف الرسالة message-id messageId MessageId message-id
معرف المستخدم user-id userId معرف المستخدم user-id
معرف جهاز الاتصال iothub-connection-device-id connectionDeviceId iothub-connection-device-id iothub-connection-device-id
معرف وحدة الاتصال iothub-connection-module-id connectionModuleId iothub-connection-module-id iothub-connection-module-id
معرّف إنشاء مصادقة الاتصال iothub-connection-auth-generation-id connectionDeviceGenerationId iothub-connection-auth-generation-id iothub-connection-auth-generation-id
طريقة مصادقة الاتصال iothub-connection-auth-method connectionAuthMethod iothub-connection-auth-method iothub-connection-auth-method
نوع المحتوى content-type نوع المحتوى ContentType iothub-content-type
contentEncoding ترميز المحتوى contentEncoding ContentEncoding iothub-content-encoding
iothub-enqueuedtime iothub-enqueuedtime enqueuedTime ‏‫غير متوفر‬ iothub-enqueuedtime
CorrelationId correlation-id correlationId CorrelationId correlation-id
dt-dataschema dt-dataschema dt-dataschema dt-dataschema dt-dataschema
dt-subject dt-subject dt-subject dt-subject dt-subject

حجم الرسالة

يقيس IoT Hub حجم الرسالة بطريقة غير محددة البروتوكول، مع الأخذ في الاعتبار البيانات الأساسية الفعلية فقط. يتم حساب الحجم بالبايت كمجموع القيم التالية:

  • حجم النص بالبايت.
  • الحجم بالبايت لكافة قيم خصائص نظام الرسائل.
  • الحجم بالبايت لكافة أسماء خصائص المستخدم وقيمها.

تقتصر أسماء الخصائص وقيمها على أحرف ASCII، بحيث يساوي طول السلاسل الحجم بالبايت.

خصائص مكافحة تزييف الهوية

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

  • iothub-connection-device-id
  • iothub-connection-auth-generation-id
  • iothub-connection-auth-method

يحتوي النوعان الأولان على deviceId وgenerationId للجهاز الأصلي، وفقاً لخصائص هوية الجهاز.

تحتوي الخاصية iothub-connection-auth-method على كائن متسلسل في JSON، مع الخصائص التالية:

{
  "scope": "{ hub | device | module }",
  "type": "{ symkey | sas | x509 }",
  "issuer": "iothub"
}

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