إنشاء رسائل 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"
}
الخطوات التالية
- للحصول على معلومات بشأن حدود حجم الرسالة في IoT Hub، راجع حصص IoT Hub والتقييد.
- لمعرفة كيفية إنشاء وقراءة رسائل IoT Hub بلغات برمجة مختلفة، راجع التشغيل السريعs.
- للتعرف على بنية الأحداث غير المتعلقة بالتتبع التي تم إنشاؤها بواسطة مركز IoT، راجع مخططات أحداث مركز IoT غير بيانات تتبع الاستخدام.