مخططات أحداث غير بيانات تتبع الاستخدام في Azure IoT Hub

  • مقالة

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

يمكنك توجيه أحداث غير بيانات تتبع الاستخدام باستخدام توجيه الرسائل، أو الوصول إلى أحداث غير بيانات تتبع الاستخدام باستخدام Azure Event Grid. لمعرفة المزيد حول توجيه رسائل IoT Hub، راجع توجيه رسالة IoT Hub وأحداث React to IoT Hub باستخدام Event Grid.

تم التقاط أمثلة الأحداث في هذه المقالة باستخدام az iot hub monitor-events الأمر Azure CLI. قد ترى مجموعة فرعية من الخصائص المضمنة في الأحداث التي تصل إلى نقطة نهاية توجيه رسالة.

أنواع الأحداث المتاحة

يصدر Azure IoT Hub الأحداث غير المتعلقة بالتتبع في الفئات التالية:

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

خصائص الحدث الشائعة

تشترك الأحداث غير المتعلقة بالتتبع في العديد من الخصائص الشائعة.

خصائص النظام

يتم تعيين خصائص النظام التالية بواسطة IoT Hub على كل حدث.

الخاصية نوع ‏‏الوصف الكلمة الرئيسية لاستعلام التوجيه
ترميز المحتوى سلسلة utf-8 $contentEncoding
content-type سلسلة تطبيق/json $contentType
correlation-id سلسلة معرف فريد يعرف الحدث. $correlationId
user-id سلسلة اسم IoT Hub الذي أنشأ الحدث. $userId
iothub-connection-device-id سلسلة معرف الجهاز $connectionDeviceId
iothub-connection-module-id سلسلة معرف الوحدة النمطية. هذه الخاصية هي الإخراج فقط لدورة حياة الوحدة النمطية والأحداث المزدوجة. $connectionModuleId
iothub-enqueuedtime رقم الوقت الذي تم فيه إرسال الإشعار. في توجيه الاستعلامات، استخدم طابعًا زمنيًا ISO8601؛ على سبيل المثال$enqueuedTime > "2022-06-06T22:56:06Z" $enqueuedTime
iothub-message-source سلسلة فئة الحدث التي تعرف مصدر الرسالة. على سبيل المثال، deviceLifecycleEvents. ‏‫غير متوفر‬

خصائص التطبيق

يتم تعيين خصائص التطبيق التالية بواسطة IoT Hub على كل حدث.

الخاصية نوع ‏‏الوصف
deviceId سلسلة معرف الجهاز
hubName سلسلة اسم مركز IoT الذي أنشأ الحدث.
iothub-message-schema سلسلة مخطط الرسالة المقترن بفئة الحدث؛ على سبيل المثال، deviceLifecycleNotification.
معرّف الوحدة النمطية سلسلة معرف الوحدة النمطية. هذه الخاصية هي الإخراج فقط لدورة حياة الوحدة النمطية وأحداث التغيير المزدوج.
operationTimestamp سلسلة الطابع الزمني ISO8601 لآخر نشاط.
نوع العملية سلسلة معرف العملية التي أنشأت الحدث. على سبيل المثال createDeviceIdentity أو deleteDeviceIdentity

في استعلامات التوجيه، استخدم اسم الخاصية. على سبيل المثال، deviceId = "my-device"

أحداث حالة الاتصال

يتم إصدار أحداث حالة الاتصال كلما اتصل جهاز أو وحدة نمطية أو قطع الاتصال بمركز IoT.

خصائص التطبيق: يوضح الجدول التالي كيفية تعيين خصائص التطبيق لأحداث حالة الاتصال:

الخاصية القيمة
iothub-message-schema deviceConnectionStateNotification
نوع العملية إحدى القيم التالية: deviceConnected أو deviceDisconnected أو moduleConnected أو moduleDisconnected.

خصائص النظام: يوضح الجدول التالي كيفية تعيين خصائص النظام لأحداث حالة الاتصال:

الخاصية القيمة
iothub-message-source deviceConnectionStateEvents

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

مثال

يظهر JSON التالي حدث حالة اتصال الجهاز المنبعثة عند قطع اتصال جهاز.

{
    "event": {
        "origin": "contoso-device-1",
        "module": "",
        "interface": "",
        "component": "",
        "properties": {
            "system": {
                "content_encoding": "utf-8",
                "content_type": "application/json",
                "correlation_id": "98dcbcf6-3398-c488-c62c-06330e65ea98",
                "user_id": "contoso-routing-hub"
            },
            "application": {
                "hubName": "contoso-routing-hub",
                "deviceId": "contoso-device-1",
                "opType": "deviceDisconnected",
                "iothub-message-schema": "deviceConnectionStateNotification",
                "operationTimestamp": "2022-06-01T18:43:04.5561024Z"
            }
        },
        "annotations": {
            "iothub-connection-device-id": "contoso-device-1",
            "iothub-enqueuedtime": 1654109018051,
            "iothub-message-source": "deviceConnectionStateEvents",
            "x-opt-sequence-number": 72,
            "x-opt-offset": "37344",
            "x-opt-enqueued-time": 1654109018176
        },
        "payload": {
            "sequenceNumber": "000000000000000001D8713FF7E0851400000002000000000000000000000007"
        }
    }
}

أحداث دورة حياة الجهاز

يتم إصدار أحداث دورة حياة الجهاز كلما تم إنشاء جهاز أو وحدة نمطية أو حذفها من سجل الهوية. لمزيد من التفاصيل حول وقت إنشاء أحداث دورة حياة الجهاز، راجع إعلامات دورة حياة الجهاز والوحدة النمطية.

خصائص التطبيق: يوضح الجدول التالي كيفية تعيين خصائص التطبيق لأحداث دورة حياة الجهاز:

الخاصية القيمة
iothub-message-schema deviceLifecycleNotification
نوع العملية إحدى القيم التالية: createDeviceIdentity أو deleteDeviceIdentity أو createModuleIdentity أو deleteModuleIdentity.

خصائص النظام: يوضح الجدول التالي كيفية تعيين خصائص النظام لأحداث دورة حياة الجهاز:

الخاصية القيمة
iothub-message-source أحداث دورة حياة الجهاز

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

مثال

يعرض JSON التالي حدث دورة حياة الجهاز المنبعث عند إنشاء وحدة نمطية. يتم التقاط الحدث باستخدام az iot hub monitor-events الأمر Azure CLI.

{
    "event": {
        "origin": "contoso-device-2",
        "module": "module-1",
        "interface": "",
        "component": "",
        "properties": {
            "system": {
                "content_encoding": "utf-8",
                "content_type": "application/json",
                "correlation_id": "c5a4e6986c",
                "user_id": "contoso-routing-hub"
            },
            "application": {
                "hubName": "contoso-routing-hub",
                "deviceId": "contoso-device-2",
                "operationTimestamp": "2022-05-27T18:49:38.4904785Z",
                "moduleId": "module-1",
                "opType": "createModuleIdentity",
                "iothub-message-schema": "moduleLifecycleNotification"
            }
        },
        "annotations": {
            "iothub-connection-device-id": "contoso-device-2",
            "iothub-connection-module-id": "module-1",
            "iothub-enqueuedtime": 1653677378534,
            "iothub-message-source": "deviceLifecycleEvents",
            "x-opt-sequence-number": 62,
            "x-opt-offset": "31768",
            "x-opt-enqueued-time": 1653677378643
        },
        "payload": {
            "deviceId": "contoso-device-2",
            "moduleId": "module-1",
            "etag": "AAAAAAAAAAE=",
            "version": 2,
            "properties": {
                "desired": {
                    "$metadata": {
                        "$lastUpdated": "0001-01-01T00:00:00Z"
                    },
                    "$version": 1
                },
                "reported": {
                    "$metadata": {
                        "$lastUpdated": "0001-01-01T00:00:00Z"
                    },
                    "$version": 1
                }
            }
        }
    }
}

أحداث تغيير الجهاز المزدوج

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

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

الخاصية القيمة
iothub-message-schema twinChangeNotification
نوع العملية إحدى القيم التالية: replaceTwin أو updateTwin.

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

الخاصية القيمة
iothub-message-source twinChangeEvents

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

مثال

يظهر JSON التالي حدث تغيير مزدوج منبعثة لتحديث خاصية مطلوبة وعلامة على وحدة نمطية مزدوجة. يتم التقاط الحدث باستخدام az iot hub monitor-events الأمر Azure CLI.

{
    "event": {
        "origin": "contoso-device-3",
        "module": "module-1",
        "interface": "",
        "component": "",
        "properties": {
            "system": {
                "content_encoding": "utf-8",
                "content_type": "application/json",
                "correlation_id": "4d1f1e2e74f",
                "user_id": "contoso-routing-hub"
            },
            "application": {
                "hubName": "contoso-routing-hub",
                "deviceId": "contoso-device-3",
                "operationTimestamp": "2022-06-01T22:27:50.2612586Z",
                "moduleId": "module-1",
                "iothub-message-schema": "twinChangeNotification",
                "opType": "updateTwin"
            }
        },
        "annotations": {
            "iothub-connection-device-id": "contoso-device-3",
            "iothub-connection-module-id": "module-1",
            "iothub-enqueuedtime": 1654122470282,
            "iothub-message-source": "twinChangeEvents",
            "x-opt-sequence-number": 17,
            "x-opt-offset": "12352",
            "x-opt-enqueued-time": 1654122470329
        },
        "payload": {
            "version": 7,
            "tags": {
                "tag1": "new value"
            },
            "properties": {
                "desired": {
                    "property1": "new value",
                    "$metadata": {
                        "$lastUpdated": "2022-06-01T22:27:50.2612586Z",
                        "$lastUpdatedVersion": 6,
                        "property1": {
                            "$lastUpdated": "2022-06-01T22:27:50.2612586Z",
                            "$lastUpdatedVersion": 6
                        }
                    },
                    "$version": 6
                }
            }
        }
    }
}

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