فهم واستخدام توائم الوحدة النمطية في IoT Hub

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

تفترض هذه المقالة أنك قرأت فهم توائم الجهاز واستخدامها في 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 المزدوج للوحدة النمطية على خصائص للقراءة فقط من هوية الوحدة النمطية المقابلة المخزنة في سجل الهوية.

Architectural representation of device twin

يوضح المثال التالي مستند 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": {
        "$etag": "123",
        "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، $etagو $version) الموضحة في قسمي بيانات التعريف المزدوجة للوحدة النمطيةوالتزامن المتفائل .

مثال على الممتلكات المبلغ عنها

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

ملاحظة

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

مثال على الخاصية المرغوبة

في المثال السابق ، يتم استخدام الخصائص المزدوجة للوحدة telemetryConfig النمطية المطلوبة والمبلغ عنها بواسطة الواجهة الخلفية للحل وتطبيق الوحدة النمطية لمزامنة تكوين القياس عن بعد لهذه الوحدة. على سبيل المثال:

  1. تحدد النهاية الخلفية للحل الخاصية المطلوبة بقيمة التكوين المطلوبة. فيما يلي جزء المستند مع مجموعة الخصائص المطلوبة:

    ...
"desired": {
    "telemetryConfig": {
        "sendFrequency": "5m"
    },
    ...
},
...

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

    "reported": {
    "telemetryConfig": {
        "sendFrequency": "5m",
        "status": "success"
    }
    ...
}

  3. يمكن للنهاية الخلفية للحل تتبع نتائج عملية التكوين عبر العديد من الوحدات النمطية ، عن طريق الاستعلام عن توائم الوحدة.

ملاحظة

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

هام

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

عمليات النهاية الخلفية

تعمل النهاية الخلفية للحل على توأم الوحدة باستخدام العمليات الذرية التالية ، المكشوفة من خلال HTTPS:

  • استرداد وحدة التوأم بواسطة ID. ترجع هذه العملية المستند المزدوج للوحدة النمطية، بما في ذلك العلامات وخصائص النظام المطلوبة والمبلغ عنها.

  • تحديث جزئي للوحدة التوأم. تمكن هذه العملية الواجهة الخلفية للحل من تحديث العلامات أو الخصائص المطلوبة جزئيا في توأم الوحدة النمطية. يتم التعبير عن التحديث الجزئي كمستند JSON يقوم بإضافة أو تحديث أي خاصية. يتم إزالة الخصائص التي تم تعيينها على null. يقوم المثال التالي بإنشاء خاصية مرغوبة جديدة ذات قيمة {"newProperty": "newValue"}، واستبدال القيمة الحالية لـ existingProperty بـ "otherNewValue"، وإزالة otherOldProperty. لم يتم إجراء أي تغييرات أخرى على الخصائص أو العلامات المرغوبة الحالية:

    {
    "properties": {
        "desired": {
            "newProperty": {
                "nestedProperty": "newValue"
            },
            "existingProperty": "otherNewValue",
            "otherOldProperty": null
        }
    }
}

  • استبدال الخصائص المطلوبة. تتيح هذه العملية للطرف الخلفي للحل إمكانية الكتابة فوق جميع الخصائص المرغوبة الحالية واستبدال مستند JSON جديد بـ properties/desired.

  • استبدال العلامات. تتيح هذه العملية للواجهة الخلفية للحل إمكانية الكتابة فوق جميع العلامات الموجودة واستبدال مستند JSON جديد بـ tags.

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

    • الخصائص

      الاسم القيمة
      $content-type تطبيق/json
      $iothub-enqueuedtime الوقت الذي تم فيه إرسال الإشعار
      $iothub-message-source twinChangeEvents
      $content-encoding utf-8
      معرف الجهاز معرّف الجهاز
      معرّف الوحدة النمطية معرّف الوحدة النمطية
      hubName اسم مركز IoT
      operationTimestamp ISO8601 الطابع الزمني للتشغيل
      iothub-message-schema twinChangeNotification
      opType "replaceTwin" أو "updateTwin"

      خصائص نظام الرسائل مسبوقة بالرمز $ .

    • النص الأساسي

      يتضمن هذا القسم جميع التغييرات المزدوجة بتنسيق JSON. يستخدم نفس تنسيق التصحيح، مع اختلاف أنه يمكن أن يحتوي على جميع الأقسام المزدوجة: العلامات، وخصائص التقرير، وخصائصه المرغوب فيه، وأنه يحتوي على عناصر "$metadata". على سبيل المثال،

      {
  "properties": {
      "desired": {
          "$metadata": {
              "$lastUpdated": "2016-02-30T16:24:48.789Z"
          },
          "$version": 1
      },
      "reported": {
          "$metadata": {
              "$lastUpdated": "2016-02-30T16:24:48.789Z"
          },
          "$version": 1
      }
  }
}

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

بالإضافة إلى هذه العمليات ، يمكن للنهاية الخلفية للحل الاستعلام عن توائم الوحدة النمطية باستخدام لغة استعلام IoT Hub الشبيهة SQL.

عمليات الوحدة

يعمل تطبيق الوحدة النمطية على توأم الوحدة باستخدام العمليات الذرية التالية:

  • استرداد وحدة التوأم. ترجع هذه العملية المستند المزدوج للوحدة النمطية (بما في ذلك خصائص النظام المطلوبة والمبلغ عنها) للوحدة النمطية المتصلة حاليا.

  • تحديث جزئي للخصائص التي تم الإبلاغ عنها. تتيح هذه العملية التحديث الجزئي للخصائص المبلغ عنها للوحدة النمطية المتصلة حاليا. تستخدم هذه العملية نفس تنسيق تحديث JSON الذي تستخدمه الواجهة الخلفية للحل لتحديث جزئي للخصائص المرغوبة.

  • مراقبة الخصائص المطلوبة. يمكن للوحدة النمطية المتصلة حاليا اختيار أن يتم إعلامها بالتحديثات على الخصائص المطلوبة عند حدوثها. تتلقى الوحدة النمطية نفس شكل التحديث (الاستبدال الجزئي أو الكامل) الذي يتم تنفيذه بواسطة الواجهة الخلفية للحل.

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

تسهل مجموعات 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 كيلوبايت على قيمة ، وحد حجم 32 كيلوبايت لكل منهما على قيمة tagsproperties/desired و properties/reported. هذه المجاميع حصرية للعناصر للقراءة فقط مثل $etag، و $version$metadata/$lastUpdated.

يتم حساب حجم التوأم على النحو التالي:

  • لكل خاصية في مستند JSON، يقوم IoT Hub بحساب وإضافة طول مفتاح الخاصية وقيمتها بشكل تراكمي.

  • تعتبر مفاتيح الخصائص سلاسل مشفرة UTF8.

  • تعتبر قيم الخصائص البسيطة سلاسل مشفرة UTF8 أو قيم رقمية (8 بايت) أو قيم منطقية (4 بايت).

  • يتم حساب حجم السلاسل المشفرة UTF8 عن طريق حساب جميع الأحرف، باستثناء أحرف تحكم UNICODE (المقاطع C0 وC1).

  • يتم حساب قيم الخصائص المعقدة (الكائنات المتداخلة) استنادا إلى الحجم الإجمالي لمفاتيح الخصائص وقيم الخصائص التي تحتوي عليها.

يرفض IoT Hub بخطأ جميع العمليات التي من شأنها زيادة حجم تلك المستندات فوق الحد.

البيانات الوصفية المزدوجة للوحدة النمطية

يحتفظ IoT Hub بالطابع الزمني لآخر تحديث لكل كائن JSON في خصائص الوحدة النمطية التوأم المطلوبة والمبلغ عنها. الطوابع الزمنية بالتوقيت العالمي المنسق ومشفرة بتنسيق YYYY-MM-DDTHH:MM:SS.mmmZISO8601 . على سبيل المثال:

{
    ...
    "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 ، وفقا ل RFC7232 ، يمثل تمثيل JSON للعلامة. يمكنك استخدام ETag في عمليات التحديث الشرطي من النهاية الخلفية للحل لضمان الاتساق.

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

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

تدفق إعادة توصيل الوحدة النمطية

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

  1. يتصل تطبيق الوحدة النمطية بمركز إنترنت الأشياء.
  2. يشترك تطبيق الوحدة النمطية في إشعارات تحديث الخصائص المطلوبة.
  3. يقوم تطبيق الوحدة النمطية باسترداد المستند الكامل للخصائص المطلوبة.

يمكن لتطبيق الوحدة النمطية تجاهل جميع الإشعارات التي تحتوي $version على إصدار أقل أو مساو من إصدار المستند الذي تم استرداده بالكامل. هذا النهج ممكن لأن IoT Hub يضمن زيادة الإصدارات دائمًا.

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

لتجربة بعض المفاهيم الموضحة في هذه المقالة، راجع البرامج التعليمية التالية ل IoT Hub: