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

  • مقالة
  • قراءة خلال 5 دقائق

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

ملاحظة

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

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

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

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

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

  • نص ثنائي مبهم.

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

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

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

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

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

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

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

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

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

الخاصية الوصف User Settable? الكلمة الرئيسية لاستعلام
التوجيه
message-id معرّف يمكن للمستخدم تعيينه للرسالة المستخدمة لأنماط الرد على الطلب. التنسيق: سلسلة حساسة لحالة الأحرف (يصل طولها إلى 128 حرفا) من الأحرف الأبجدية الرقمية ASCII 7 بت + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. نعم messageId
iothub-enqueuedtime تاريخ ووقت استلام رسالة " من جهاز إلى سحابة" بواسطة IoT Hub. لا enqueuedTime
user-id معرف يستخدم لتحديد أصل الرسائل. عندما يتم إنشاء الرسائل بواسطة IoT Hub ، يتم تعيينها إلى {iot hub name}. نعم معرّف المستخدم
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 يسمح للجهاز بإرسال وقت إنشاء الحدث عند إرسال البيانات دفعة واحدة. نعم إنشاء-وقت-UTC
iothub-creation-time-utc يسمح للجهاز بإرسال وقت إنشاء الحدث عند إرسال رسالة واحدة في كل مرة. نعم إنشاء-وقت-UTC
dt-dataschema يتم تعيين هذه القيمة بواسطة IoT hub على الرسائل من جهاز إلى سحابة. تحتوي على معرّف طراز الجهاز الذي تم تعيينه في اتصال الجهاز. لا $dt-dataschema
dt-الموضوع اسم المكوّن الذي يقوم بإرسال رسائل من جهاز إلى سحابة. نعم $dt-الموضوع

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

الاستخدام الشائع لخصائص التطبيق هو إرسال طابع زمني من الجهاز باستخدام iothub-creation-time-utc الخاصية لتسجيل وقت إرسال الرسالة بواسطة الجهاز. يجب أن يكون تنسيق هذا الطابع الزمني UTC بدون معلومات المنطقة الزمنية. على سبيل المثال، صالح، 2021-04-21T11:30:16Z2021-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 حرفا) من الأحرف الأبجدية الرقمية ASCII 7 بت + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. نعم
sequence-number رقم (فريد لكل قائمة انتظار أجهزة) تم تعيينه بواسطة IoT Hub لكل رسالة من سحابة إلى جهاز. لا
إلى وجهة محددة في رسائل السحابة إلى الجهاز . لا
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 معرف الرسالة message-id
معرف المستخدم user-id معرّف المستخدم معرّف المستخدم 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
نوع المحتوى نوع المحتوى نوع المحتوى نوع المحتوى iothub-content-type
المحتوىترميز ترميز المحتوى المحتوىترميز ترميز المحتوى 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-الموضوع dt-الموضوع dt-الموضوع dt-الموضوع dt-الموضوع

حجم الرسالة

يقيس 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 }",
  "type": "{ symkey | sas | x509 }",
  "issuer": "iothub"
}

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