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

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

إشعار

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

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

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

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

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

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

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

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

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

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

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

الأجهزة المتماثلة

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

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

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

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

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

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

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

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

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

يعرض المثال التالي مستند 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 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 استخدام العمليات السابقة من العديد من اللغات والأنظمة الأساسية. لمزيد من المعلومات حول تفاصيل بدائيات 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 مع حدوث خطأ جميع العمليات التي من شأنها زيادة حجم tags، properties/desiredأو properties/reported المستندات فوق الحد.

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

يحتفظ 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": {
                        "$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) للحفاظ على التحديثات التي تزيل مفاتيح الكائنات.

التزامن الأمثل

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

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

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

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

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

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

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

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

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

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

• البرنامج التعليمي: تكوين أجهزتك باستخدام خصائص الجهاز المزدوج
• كيفية استخدام توائم الجهاز