فهم واستخدام توائم الجهاز في IoT Hub

هل هذه الصفحة مفيدة؟

هل لديك ملاحظات إضافية؟

سيتم إرسال الملاحظات إلى Microsoft: بالضغط على الزر «إرسال»، سيتم استخدام ملاحظاتك لتحسين منتجات Microsoft وخدماتها. نهج الخصوصية.

توائم الجهاز هي مستندات JSON التي تخزن معلومات حالة الجهاز بما في ذلك بيانات التعريف والتكوينات والشروط. يحتفظ Azure IoT Hub بـ Device twin لكل جهاز تقوم بتوصيله بـ IoT Hub.

ملاحظة

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

توضح هذه المقالة ما يلي:

• بنية الجهاز المزدوج: العلاماتوالخصائص المطلوبة والمبلغ عنها.
• العمليات التي يمكن لتطبيقات الجهاز والأطراف الخلفية تنفيذها على توائم الجهاز.

استخدم توائم الجهاز من أجل ما يلي:

• تخزين بيانات التعريف الخاصة بالجهاز على السحابة. على سبيل المثال، موقع نشر آلة البيع.

• الإبلاغ عن معلومات الحالة الحالية مثل الإمكانات والشروط المتاحة من تطبيق جهازك. على سبيل المثال، ما إذا كان الجهاز متصلا بمركز IoT عبر شبكة الجوال أو WiFi.

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

• الاستعلام عن بيانات التعريف للجهاز، أو التكوين، أو الحالة.

راجع إرشادات الاتصال من جهاز إلى سحابة للحصول على إرشادات حول استخدام الخصائص المبلغ عنها أو الرسائل من جهاز إلى سحابة أو تحميل الملف.

راجع إرشادات الاتصال من السحابة إلى الجهاز للحصول على إرشادات حول استخدام الخصائص المطلوبة أو الأساليب المباشرة أو الرسائل من السحابة إلى الجهاز.

لمعرفة كيفية ارتباط توائم الجهاز بنموذج الجهاز المستخدم من قبل جهاز أجهزة التوصيل و التشغيل Azure IoT، راجع فهم IoT أجهزة التوصيل و التشغيل digital twins.

توائم الجهاز

تعمل توائم الجهاز على تخزين المعلومات المتعلقة بالجهاز والتي:

• يمكن استخدام الجهاز والأطراف الخلفية لمزامنة شروط الجهاز وتكوينه.

• يمكن استخدام النهاية الخلفية للحل للاستعلام عن العمليات طويلة الأمد واستهدافها.

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

تعد توائم الجهاز عبارة عن مستند JSON يتضمن ما يلي:

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

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

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

• خصائص هوية الجهاز. يحتوي جذر مستند JSON المزدوج للجهاز على خصائص القراءة فقط من هوية الجهاز المقابلة المخزنة في سجل الهوية. generationId الخصائص connectionStateUpdatedTime ولن يتم تضمينها.

يعرض المثال التالي مستند JSON لتوائم الجهاز:

{
    "deviceId": "devA",
    "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 يتم استخدام الخصائص المزدوجة للجهاز المطلوبة والمبلغ عنها من قبل النهاية الخلفية للحل والتطبيق لمزامنة تكوين بيانات تتبع الاستخدام لهذا الجهاز. على سبيل المثال:

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

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

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

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

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

ملاحظة

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

هام

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

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

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

تعمل الواجهة الخلفية للحل على الجهاز المزدوج باستخدام العمليات الذرية التالية، والتي يتم عرضها من خلال HTTPS:

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

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

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

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

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

• تلقي إعلامات مزدوجة. تسمح هذه العملية النهاية الخلفية الحل إعلام عند تعديل الجهاز المزدوج. للقيام بذلك، يحتاج حل IoT الخاص بك إلى إنشاء مسار وتعيين مصدر البيانات يساوي 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. يستخدم نفس التنسيق مثل التصحيح، مع اختلاف أنه يمكن أن يحتوي على جميع الأقسام المزدوجة: العلامات، الخصائص.المبلغ عنها، properties.desired، وأنه يحتوي على عناصر "$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.

بالإضافة إلى هذه العمليات، يمكن للنهاية الخلفية للحل:

• الاستعلام عن توائم الجهاز باستخدام لغة استعلام IoT Hub التي تشبه SQL.

• تنفيذ عمليات على مجموعات كبيرة من توائم الجهاز باستخدام الوظائف.

عمليات الجهاز

يعمل تطبيق الجهاز على الجهاز المزدوج باستخدام العمليات الذرية التالية:

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

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

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

تتطلب جميع العمليات السابقة إذن DeviceConnect ، كما هو محدد في Control Access to IoT Hub.

تسهل حزم SDK لجهاز Azure IoT استخدام العمليات السابقة من العديد من اللغات والأنظمة الأساسية. لمزيد من المعلومات حول تفاصيل بدائيات IoT Hub لمزامنة الخصائص المطلوبة، راجع تدفق إعادة توصيل الجهاز.

تنسيق العلامات والخصائص

العلامات والخصائص المطلوبة والخصائص المبلغ عنها هي كائنات JSON مع القيود التالية:

• المفاتيح: جميع المفاتيح في كائنات JSON مرمزة ب UTF-8 وحساسة لحالة الأحرف وطولها يصل إلى 1 كيلوبايت. تستبعد الأحرف المسموح بها أحرف التحكم UNICODE (المقطعان C0 وC1) و و .$و SP.

  ملاحظة

  لا تدعم استعلامات IoT Hub المستخدمة في توجيه الرسائل المسافة البيضاء أو أي من الأحرف التالية كجزء من اسم المفتاح: ()<>@,;:\"/?={}.

• القيم: يمكن أن تكون جميع القيم في كائنات 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 مع حدوث خطأ جميع العمليات التي من شأنها زيادة حجم tagsproperties/desiredالمستندات أو properties/reported فوق الحد.

بيانات التعريف المزدوجة للجهاز

يحتفظ IoT Hub بالطابع الزمني لآخر تحديث لكل كائن JSON في الخصائص المرغوبة والمبلغ عنها في الجهاز المزدوج. الطوابع الزمنية بتنسيق UTC ويتم ترميزها بتنسيق 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": {
                        "$lastUpdated": "2016-03-31T16:35:48.789Z"
                    },
                    "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 في عمليات التحديث الشرطي من النهاية الخلفية للحل لضمان الاتساق.

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

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

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

تدفق إعادة توصيل الجهاز

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

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

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

مواد مرجعية إضافية

تتضمن الموضوعات المرجعية الأخرى في دليل مطور IoT Hub ما يلي:

• تصف مقالة نقاط نهاية IoT Hub نقاط النهاية المختلفة التي يعرضها كل مركز IoT لوقت التشغيل وعمليات الإدارة.

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

• تسرد مقالة Azure IoT device and service SDKs العديد من حزم SDK للغة التي يمكنك استخدامها عند تطوير تطبيقات الجهاز والخدمة التي تتفاعل مع IoT Hub.

• تصف لغة استعلام IoT Hub لتوائم الجهاز والمهام وتوجيه الرسائل لغة استعلام IoT Hub التي يمكنك استخدامها لاسترداد المعلومات من IoT Hub حول توائم الجهاز ومهامه.

• توفر مقالة دعم IoT Hub MQTT المزيد من المعلومات حول دعم IoT Hub لبروتوكول MQTT.

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

الآن لقد تعرفت على توائم الجهاز، قد تكون مهتما بمواضيع دليل مطور IoT Hub التالية:

• فهم واستخدام توائم الوحدة النمطية في IoT Hub
• استدعاء أسلوب مباشر على جهاز
• جدولة المهام على أجهزة متعددة

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

• كيفية استخدام توأم الجهاز
• كيفية استخدام خصائص الجهاز المزدوج
• إدارة الأجهزة باستخدام أدوات Azure IoT لـ VS Code