فهم واستخدام المستندات معلومات حالة النمطية في IoT Hub
تفترض هذه المقالة أنك قرأت فهم واستخدام مستندات معلومات حالة الجهاز في IoT Hub أولاً. في IoT Hub، تحت كل هوية جهاز، يمكنك إنشاء ما يصل إلى 50 هوية وحدة. تنشئ كل هوية وحدة نمطية ضمنياً وحدة مزدوجة. على غرار توائم الجهاز، تعد توائم الوحدة عبارة عن مستندات JSON تخزن معلومات حالة الوحدة، بما في ذلك بيانات التعريف والتكوينات والشروط. يحتفظ Azure IoT Hub بتوأم وحدة لكل وحدة تقوم بتوصيلها بـ IoT Hub.
من جانب الجهاز، تتيح لك أدوات تطوير البرامج (SDK) الخاصة بجهاز IoT Hub إنشاء وحدات حيث يفتح كل منها اتصالاً مستقلاً بـ IoT Hub. تتيح لك هذه الوظيفة استخدام مساحات أسماء منفصلة لمكونات مختلفة على جهازك. على سبيل المثال، لديك آلة بيع بها ثلاثة أجهزة استشعار مختلفة. ويتم التحكم في كل جهاز استشعار من قبل أقسام مختلفة في شركتك. يمكنك إنشاء وحدة لكل جهاز استشعار. بهذه الطريقة، يكون كل قسم قادراً فقط على إرسال الوظائف أو الطرق المباشرة إلى أداة الاستشعار الذي يتحكم فيه، وتجنب التعارضات وأخطاء المستخدم.
توفر هوية الوحدة وتوأم الوحدة نفس الإمكانات مثل هوية الجهاز وتوأم الجهاز ولكن بتحكم متعدد المستويات بدقة أكثر. يمكّن هذا التحكم متعدد المستويات الدقيق الأجهزة الممكنة، مثل الأجهزة المستندة إلى نظام التشغيل أو أجهزة البرامج الثابتة التي تدير مكونات متعددة، من عزل التكوين والشروط لكل من هذه المكونات. توفر هوية الوحدة وتوائم الوحدة فصلاً إدارياً عن الأمور المقلقة عند العمل مع أجهزة إنترنت الأشياء التي تحتوي على مكونات برامج ذات وحدات. نحن نهدف إلى دعم جميع وظائف الجهاز المزدوجة على مستوى الوحدة المزدوجة من خلال التوافر العام للوحدة المزدوجة.
إشعار
تتوفر الميزات الموضحة في هذه المقالة فقط في المستوى القياسي لمركز إنترنت الأشياء. لمزيد من المعلومات حول مستويات IoT Hub الأساسية والقياسية/المجانية، راجع اختيار طبقة IoT Hub المناسبة للحل الخاص بك.
توضح هذه المقالة ما يلي:
- هيكل الوحدة المزدوجة: العلامات، المرغوبة والخصائص المبلغ عنها.
- العمليات التي يمكن للوحدات والنهايات الخلفية إجراؤها على المستندات معلومات حالة النمطية.
راجع إرشادات الاتصال من جهاز إلى سحابة للحصول على إرشادات حول استخدام الخصائص المبلغ عنها أو الرسائل من جهاز إلى سحابة أو تحميل الملف.
راجع إرشادات الاتصال من السحابة إلى الجهاز للحصول على إرشادات حول استخدام الخصائص المطلوبة أو الأساليب المباشرة أو الرسائل من السحابة إلى الجهاز.
الوحدة النمطية المزدوجة
مستندات معلومات حالة الوحدة النمطية تخزن المعلومات المتعلقة بالوحدة النمطية والتي:
يمكن استخدام الوحدات النمطية الموجودة على الجهاز وIoT Hub لمزامنة ظروف الوحدة النمطية وتكوينها.
يمكن استخدام النهاية الخلفية للحل للاستعلام عن العمليات طويلة الأمد واستهدافها.
ترتبط دورة حياة الوحدة المزدوجة بهوية الوحدة النمطيةالمقابلة. يتم إنشاء وحدات المستندات معلومات حالة بشكل ضمني وحذفها عند إنشاء هوية وحدة نمطية أو حذفها في IoT Hub.
الوحدة المزدوجة هي مستند JSON يتضمن:
العلامات. قسم من مستند JSON يمكن لخلفية الحل القراءة منه والكتابة إليه. العلامات غير مرئية للوحدات النمطية على الجهاز. يتم تعيين العلامات لغرض الاستعلام.
الخصائص المرغوبة. تُستخدم جنباً إلى جنب مع الخصائص المبلغ عنها لمزامنة تكوين الوحدة أو شروطها. يمكن أن تحدد النهاية الخلفية للحل الخصائص المطلوبة، ويمكن لتطبيق الوحدة قراءتها. يمكن لتطبيق الوحدة النمطية أيضاً تلقي إخطارات بالتغييرات في الخصائص المطلوبة.
الخصائص المبلغ عنها. تُستخدم جنباً إلى جنب مع الخصائص المرغوبة لمزامنة تكوين الوحدة أو شروطها. يمكن لتطبيق الوحدة النمطية تعيين الخصائص التي تم الإبلاغ عنها، ويمكن للواجهة الخلفية للحل قراءتها والاستعلام عنها.
خصائص هوية الوحدة. يحتوي جذر مستند JSON للوحدة النمطية المزدوجة على خصائص للقراءة فقط من هوية الوحدة النمطية المقابلة المخزنة في سجل الهوية.
يوضح المثال التالي مستند JSON للوحدة النمطية المزدوجة:
{
"deviceId": "devA",
"moduleId": "moduleA",
"etag": "AAAAAAAAAAc=",
"status": "enabled",
"statusReason": "provisioned",
"statusUpdateTime": "0001-01-01T00:00:00",
"connectionState": "connected",
"lastActivityTime": "2015-02-30T16:24:48.789Z",
"cloudToDeviceMessageCount": 0,
"authenticationType": "sas",
"x509Thumbprint": {
"primaryThumbprint": null,
"secondaryThumbprint": null
},
"version": 2,
"tags": {
"deploymentLocation": {
"building": "43",
"floor": "1"
}
},
"properties": {
"desired": {
"telemetryConfig": {
"sendFrequency": "5m"
},
"$metadata" : {...},
"$version": 1
},
"reported": {
"telemetryConfig": {
"sendFrequency": "5m",
"status": "success"
},
"batteryLevel": 55,
"$metadata" : {...},
"$version": 4
}
}
}
في العنصر الجذر توجد خصائص هوية الوحدة النمطية وعناصر الحاوية لـ tags وخصائص كل من reported وdesired. تحتوي الحاوية properties على بعض عناصر القراءة فقط ($metadata و$version) الموضحة في قسمي بيانات التعريف للوحدة النمطية المزدوجة والتزامن الأمثل.
مثال الخاصية المبلغ عنها
في المثال السابق، تحتوي الوحدة النمطية المزدوجة على خاصية batteryLevel التي تم الإبلاغ عنها بواسطة تطبيق الوحدة النمطية. تتيح هذه الخاصية إمكانية الاستعلام عن الوحدات النمطية وتشغيلها بناءً على آخر مستوى للبطارية تم الإبلاغ عنه. تتضمن الأمثلة الأخرى إمكانيات الوحدة النمطية للإبلاغ عن التطبيقات أو خيارات الاتصال.
إشعار
تعمل الخصائص التي تم الإبلاغ عنها على تبسيط السيناريوهات التي تهتم فيها النهاية الخلفية للحل بآخر قيمة معروفة لخاصية. استخدم رسائل من جهاز إلى شبكة سحابية إذا كانت النهاية الخلفية للحل تحتاج إلى معالجة وحدة القياس عن بعد في شكل تسلسلات من الأحداث ذات الطابع الزمني، مثل التسلسل الزمني.
مثال على الممتلكات المرغوبة
في المثال السابق، يتم استخدام الخصائص المزدوجة للوحدة النمطية telemetryConfig المرغوبة والمبلغ عنها بواسطة النهاية الخلفية للحل وتطبيق الوحدة النمطية لمزامنة تكوين القياس عن بُعد لهذه الوحدة. على سبيل المثال:
تحدد النهاية الخلفية للحل الخاصية المطلوبة بقيمة التكوين المطلوبة. فيما يلي جزء المستند الذي يحتوي على مجموعة الخصائص المطلوبة:
... "desired": { "telemetryConfig": { "sendFrequency": "5m" }, ... }, ...يتم إخطار تطبيق الوحدة بالتغيير على الفور إذا تم توصيل الوحدة. إذا لم يكن متصلاً، فإن تطبيق الوحدة يتبع تدفق إعادة توصيل الوحدة عند الاتصال. يقوم تطبيق الوحدة النمطية بعد ذلك بالإبلاغ عن التكوين المحدث (أو حالة خطأ باستخدام خاصية
status). فيما يلي جزء من الخصائص التي تم الإبلاغ عنها:"reported": { "telemetryConfig": { "sendFrequency": "5m", "status": "success" } ... }يمكن للنهاية الخلفية للحل تتبع نتائج عملية التكوين عبر العديد من الوحدات، عن طريق الاستعلام عن مستندات معلومات حالة الوحدة.
إشعار
القصاصة البرمجية السابقة هي أمثلة، محسّنة لسهولة القراءة، لترميز تكوين الوحدة وحالتها بطريقة واحدة. لا يفرض IoT Hub مخططاً محدداً للوحدة النمطية المزدوجة المطلوبة والخصائص المبلغ عنها في مستندات معلومات حالة الوحدة النمطية.
هام
يعرّف IoT Plug and Play مخططاً يستخدم العديد من الخصائص الإضافية لمزامنة التغييرات مع الخصائص المرغوبة والمبلغ عنها. إذا كان الحل الخاص بك يستخدم IoT Plug and Play، يجب عليك اتباع اصطلاحات Plug and Play عند تحديث الخصائص المزدوجة. لمزيد من المعلومات ومثال، راجع الخصائص القابلة للكتابة في IoT Plug and Play.
عمليات النهاية الخلفية
تعمل الواجهة الخلفية للحل على الوحدة المزدوجة باستخدام العمليات الذرية التالية، والتي يتم عرضها من خلال HTTPS:
استرداد الوحدة المزدوجة بواسطة المعرف. تقوم هذه العملية بإرجاع مستند الوحدة النمطية المزدوجة، بما في ذلك العلامات وخصائص النظام المطلوبة والمبلغ عنها.
تحديث الوحدة المزدوجة جزئياً. تتيح هذه العملية للطرف الخلفي للحل تحديث العلامات أو الخصائص المطلوبة جزئياً في الوحدة النمطية المزدوجة. يتم التعبير عن التحديث الجزئي كمستند JSON يقوم بإضافة أو تحديث أي خاصية. يتم إزالة الخصائص التي تم تعيينها على
null. يقوم المثال التالي بإنشاء خاصية مرغوبة جديدة ذات قيمة{"newProperty": "newValue"}، واستبدال القيمة الحالية لـexistingPropertyبـ"otherNewValue"، وإزالةotherOldProperty. لم يتم إجراء أي تغييرات أخرى على الخصائص أو العلامات المرغوبة الحالية:{ "properties": { "desired": { "newProperty": { "nestedProperty": "newValue" }, "existingProperty": "otherNewValue", "otherOldProperty": null } } }استبدل الخصائص المطلوبة. تتيح هذه العملية للطرف الخلفي للحل إمكانية الكتابة فوق جميع الخصائص المرغوبة الحالية واستبدال مستند JSON جديد بـ
properties/desired.استبدل العلامات. تتيح هذه العملية للواجهة الخلفية للحل إمكانية الكتابة فوق جميع العلامات الموجودة واستبدال مستند JSON جديد بـ
tags.تلقي إشعارات مزدوجة. تسمح هذه العملية النهاية الخلفية الحل إعلام عند تعديل الجهاز المزدوج. للقيام بذلك، يحتاج حل إنترنت الأشياء الخاص بك إلى إنشاء مسار وتعيين مصدر البيانات مساويًا لـ twinChangeEvents. بشكل افتراضي، لا يوجد مثل هذا المسار، لذلك لا يتم إرسال إخطارات مزدوجة. إذا كان معدل التغيير مرتفعًا جدًا، أو لأسباب أخرى مثل الإخفاقات الداخلية، فقد يرسل IoT Hub إشعارًا واحدًا فقط يحتوي على جميع التغييرات. لذلك، إذا كان تطبيقك يحتاج إلى تدقيق وتسجيل موثوق به لجميع الحالات الوسيطة، فيجب عليك استخدام الرسائل من جهاز إلى شبكة سحابية. لمعرفة المزيد حول الخصائص والنص الأساسي الذي يتم إرجاعه في رسالة الإخطار المزدوجة، راجع مخططات الأحداث بدون تعقب عن بُعد.
تدعم جميع العمليات السابقة التزامن الأمثل وتتطلب إذن ServiceConnect، كما هو محدد في مقالة التحكم في الوصول إلى IoT Hub.
بالإضافة إلى هذه العمليات، يمكن للواجهة الخلفية للحل الاستعلام عن مستندات معلومات حالة الوحدة باستخدام لغة استعلام IoT Hubمثل SQL.
عمليات الوحدة النمطية
يعمل تطبيق الوحدة النمطية على الوحدة المزدوجة باستخدام العمليات الذرية التالية:
استرداد الوحدة المزدوجة. تقوم هذه العملية بإرجاع مستند الوحدة النمطية المزدوجة (بما في ذلك خصائص النظام المرغوبة والمبلغ عنها) للوحدة النمطية المتصلة حالياً.
تحديث الخصائص التي تم الإبلاغ عنها جزئياً. تتيح هذه العملية التحديث الجزئي للخصائص المبلغ عنها للوحدة النمطية المتصلة حالياً. تستخدم هذه العملية نفس تنسيق تحديث JSON الذي تستخدمه الواجهة الخلفية للحل لتحديث جزئي للخصائص المرغوبة.
لاحظ الخصائص المطلوبة. يمكن للوحدة المتصلة حالياً اختيار أن يتم إخطارها بالتحديثات التي تطرأ على الخصائص المطلوبة عند حدوثها. تتلقى الوحدة نفس شكل التحديث (الاستبدال الجزئي أو الكامل) الذي يتم تنفيذه بواسطة النهاية الخلفية للحل.
تتطلب جميع العمليات السابقة إذن DeviceConnect، كما هو محدد في مقالة Control Access to IoT Hub.
تسهل حزم SDK لجهاز Azure IoT استخدام العمليات السابقة من العديد من اللغات والأنظمة الأساسية.
تنسيق العلامات والخصائص
العلامات والخصائص المطلوبة والخصائص التي تم الإبلاغ عنها هي عناصر JSON مع القيود التالية:
المفاتيح: جميع المفاتيح في عناصر JSON مشفرة بترميز UTF-8، وتتأثر بحالة الأحرف، ويصل طولها إلى 1 كيلوبايت. تستبعد الأحرف المسموح بها أحرف التحكم UNICODE (المقطعان C0 وC1) و
.،$و SP.القيم: يمكن أن تكون جميع القيم في عناصر JSON من أنواع JSON التالية: منطقية، رقم، سلسلة، عنصر. المصفوفات مدعومة أيضاً.
يمكن أن يكون الحد الأدنى لقيمة الأعداد الصحيحة هو -4503599627370496 وقيمة قصوى 4503599627370495.
قيم السلسلة مشفرة UTF-8 ويمكن أن يبلغ الحد الأقصى للطول 4 كيلوبايت.
العمق: الحد الأقصى لعمق عناصر JSON في العلامات والخصائص المرغوبة والخصائص التي تم الإبلاغ عنها هو 10. على سبيل المثال، العنصر التالي صالح:
{ ... "tags": { "one": { "two": { "three": { "four": { "five": { "six": { "seven": { "eight": { "nine": { "ten": { "property": "value" } } } } } } } } } } }, ... }
حجم الوحدة المزدوجة
يفرض IoT Hub حد حجم 8 كيلوبايت على قيمة tags، وحدود حجم 32 كيلوبايت لكل منهما على قيمة properties/desired و properties/reported. لا تشمل هذه الإجماليات عناصر للقراءة فقط مثل $version و$metadata/$lastUpdated.
يتم حساب الحجم المستند معلومات حالة على النحو التالي:
لكل خاصية في مستند JSON، يحسب IoT Hub ويضيف طول مفتاح الخاصية وقيمتها بشكل تراكمي.
تعد مفاتيح الخصائص بمثابة سلاسل بترميز UTF8.
تعد قيم الخصائص البسيطة كسلاسل تعليمة برمجية UTF8 أو قيم رقمية (8 بايت) أو قيم منطقية (4 بايت).
يتم حساب حجم السلاسل المشفرة بـ UTF8 عن طريق حساب جميع الأحرف، باستثناء أحرف تحكم UNICODE (المقاطع C0 وC1).
يتم حساب قيم الخصائص المعقدة (العناصر المتداخلة) بناءً على الحجم الكلي لمفاتيح الخصائص وقيم الخصائص التي تحتوي عليها.
يرفض IoT Hub بخطأ جميع العمليات التي من شأنها زيادة حجم تلك المستندات فوق الحد.
وحدة بيانات التعريف المستند معلومات حالة
يحتفظ IoT Hub بالطابع الزمني لآخر تحديث لكل عنصر JSON في الوحدة النمطية المزدوجة المطلوبة والخصائص المبلغ عنها. الطوابع الزمنية بالتوقيت العالمي المنسق ومشفرة بـ تنسيق ISO8601 YYYY-MM-DDTHH:MM:SS.mmmZ.
على سبيل المثال:
{
...
"properties": {
"desired": {
"telemetryConfig": {
"sendFrequency": "5m"
},
"$metadata": {
"telemetryConfig": {
"sendFrequency": {
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$version": 23
},
"reported": {
"telemetryConfig": {
"sendFrequency": "5m",
"status": "success"
},
"batteryLevel": "55%",
"$metadata": {
"telemetryConfig": {
"sendFrequency": "5m",
"status": {
"$lastUpdated": "2016-03-31T16:35:48.789Z"
},
"$lastUpdated": "2016-03-31T16:35:48.789Z"
},
"batteryLevel": {
"$lastUpdated": "2016-04-01T16:35:48.789Z"
},
"$lastUpdated": "2016-04-01T16:24:48.789Z"
},
"$version": 123
}
}
...
}
يتم الاحتفاظ بهذه المعلومات في كل مستوى (وليس فقط أوراق بنية JSON) للحفاظ على التحديثات التي تزيل مفاتيح الكائنات.
التزامن الأمثل
تدعم العلامات والخصائص المرغوبة والخصائص التي تم الإبلاغ عنها التزامن المتفائل. إذا كنت بحاجة إلى ضمان ترتيب تحديثات الخاصية المزدوجة، ففكر في تنفيذ المزامنة على مستوى التطبيق من خلال انتظار رد الاتصال بالخصائص المبلغ عنها قبل إرسال التحديث التالي.
المستندات معلومات حالة النمطية لها ETag (خاصيةetag )، وفقاً لـ RFC7232، والتي تمثل تمثيل JSON المستند معلومات حالة. يمكنك استخدام الخاصية etag في عمليات التحديث الشرطي من النهاية الخلفية للحل لضمان التناسق. هذا هو الخيار الوحيد لضمان التناسق في العمليات التي تتضمن الحاوية tags.
تحتوي خصائص الوحدة المزدوجة المرغوبة والمبلغ عنها أيضاً على قيمة $version مضمونة لتكون تدريجية. على غرار ETag، يمكن استخدام الإصدار من قبل الطرف المحدث لفرض اتساق التحديثات. على سبيل المثال، تطبيق وحدة لخاصية تم الإبلاغ عنها أو النهاية الخلفية للحل لخاصية مرغوبة.
تكون الإصدارات مفيدة أيضاً عندما يجب على عامل المراقبة (مثل تطبيق الوحدة النمطية الذي يراقب الخصائص المطلوبة) التوفيق بين نتيجة عملية الاسترداد وإخطار التحديث. يوفر القسم تدفق إعادة توصيل الوحدة النمطية مزيداً من المعلومات.
تدفق إعادة توصيل الوحدة النمطية
لا يحتفظ IoT Hub بالخصائص المطلوبة بإخطارات تحديث الوحدات النمطية غير المتصلة. ويترتب على ذلك أن الوحدة النمطية التي يتم الاتصال بها يجب أن تسترد مستند الخصائص المطلوبة بالكامل، بالإضافة إلى الاشتراك في إشعارات التحديث. نظرًا لإمكانية حدوث سباقات بين إشعارات التحديث والاسترداد الكامل، يجب ضمان التدفق التالي:
- تطبيق الوحدة النمطية يتصل بـ IoT Hub.
- يشترك تطبيق الوحدة النمطية للحصول على إخطارات تحديث الخصائص المطلوبة.
- يسترد تطبيق الوحدة المستند الكامل للخصائص المطلوبة.
يمكن لتطبيق الوحدة النمطية تجاهل جميع الإشعارات التي لها $version أقل من أو يساوي إصدار المستند المسترد بالكامل. هذا النهج ممكن لأن IoT Hub يضمن زيادة الإصدارات دائمًا.
الخطوات التالية
لتجربة بعض المفاهيم الموضحة في هذه المقالة، راجع البرامج التعليمية التالية لـ IoT Hub: