مشاركة عبر

إدارة توائم IoT أجهزة التوصيل و التشغيل الرقمية

  • مقالة

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

تحديث التوأم الرقمي

يقوم جهاز IoT أجهزة التوصيل و التشغيل بتنفيذ نموذج موصوف بواسطة Digital Twins Definition Language (DTDL). يمكن لمطوري الحلول استخدام واجهة برمجة تطبيقات Update Digital Twin لتحديث حالة المكون وخصائص التوأم الرقمي.

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

تظهر القصاصة البرمجية التالية الاستجابة لطلب Get digital twin منسق ككائن JSON. لمعرفة المزيد حول تنسيق التوأم الرقمي، راجع فهم IoT أجهزة التوصيل و التشغيل digital Twins:

{
    "$dtId": "sample-device",
    "serialNumber": "alwinexlepaho8329",
    "thermostat1": {
        "maxTempSinceLastReboot": 25.3,
        "targetTemperature": 20.4,
        "$metadata": {
            "targetTemperature": {
                "desiredValue": 20.4,
                "desiredVersion": 4,
                "ackVersion": 4,
                "ackCode": 200,
                "ackDescription": "Successfully executed patch",
                "lastUpdateTime": "2020-07-17T06:11:04.9309159Z"
            },
            "maxTempSinceLastReboot": {
                "lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
            }
        }
    },
    "$metadata": {
        "$model": "dtmi:com:example:TemperatureController;1",
        "serialNumber": {
            "lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
        }
    }
}

تتيح لك التوائم الرقمية تحديث مكون أو خاصية كاملة باستخدام JSON Patch.

على سبيل المثال، يمكنك تحديث الخاصية targetTemperature كما يلي:

[
    {
        "op": "add",
        "path": "/thermostat1/targetTemperature",
        "value": 21.4
    }
]

يعين التحديث السابق القيمة المطلوبة لخاصية في مستوى $metadata المكون المقابل كما هو موضح في القصاصة البرمجية التالية. يقوم IoT Hub بتحديث الإصدار المطلوب من الخاصية:

"thermostat1": {
    "targetTemperature": 20.4,
    "$metadata": {
        "targetTemperature": {
            "desiredValue": 21.4,
            "desiredVersion": 5,
            "ackVersion": 4,
            "ackCode": 200,
            "ackDescription": "Successfully executed patch",
            "lastUpdateTime": "2020-07-17T06:11:04.9309159Z"
        }
    }
}

إضافة مكون أو استبداله أو إزالته

تتطلب عمليات مستوى المكون علامة كائن $metadata فارغة داخل القيمة.

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

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

يوضح نموذج JSON Patch التالي كيفية إضافة مكون أو استبداله أو إزالته:

[
    {
        "op": "add",
        "path": "/thermostat1",
        "value": {
            "targetTemperature": 21.4,
            "anotherWritableProperty": 42,
            "$metadata": {}
        }
    },
    {
        "op": "replace",
        "path": "/thermostat1",
        "value": {
            "targetTemperature": 21.4,
            "$metadata": {}
        }
    },
    {
        "op": "remove",
        "path": "/thermostat2"
    }
]

إضافة خاصية أو استبدالها أو إزالتها

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

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

يوضح نموذج JSON Patch التالي كيفية إضافة خاصية أو استبدالها أو إزالتها داخل مكون:

[
    {
        "op": "add",
        "path": "/thermostat1/targetTemperature",
        "value": 21.4
    },
    {
        "op": "replace",
        "path": "/thermostat1/anotherWritableProperty",
        "value": 42
    },
    {
        "op": "remove",
        "path": "/thermostat2/targetTemperature",
    }
]

قواعد لتعيين القيمة المطلوبة لخاصية التوأم الرقمي

الاسم

يجب أن يكون اسم المكون أو الخاصية اسم DTDL صالحا.

الأحرف المسموح بها هي a-z، A-Z، 0-9 (وليس كالحرف الأول)، والتسطير السفلي (وليس كالحرف الأول أو الأخير).

يمكن أن يتراوح طول الاسم من 1 إلى 64 حرفا.

قيمة الخاصية

يجب أن تكون القيمة خاصية DTDL صالحة.

يتم دعم جميع الأنواع الأولية. ضمن الأنواع المعقدة، يتم دعم التعدادات والخرائط والكائنات. لمعرفة المزيد، راجع مخططات DTDL.

لا تدعم الخصائص الصفيف أو أي مخطط معقد مع صفيف.

يتم دعم الحد الأقصى لعمق خمسة مستويات لكائن معقد.

يجب أن تكون كافة أسماء الحقول داخل الكائن المعقد أسماء DTDL صالحة.

يجب أن تكون جميع مفاتيح الخريطة أسماء DTDL صالحة.

استكشاف أخطاء واجهة برمجة تطبيقات التوأم الرقمي وإصلاحها

تطرح واجهة برمجة تطبيقات التوأم الرقمي رسالة الخطأ العامة التالية:

ErrorCode:ArgumentInvalid;'{propertyName}' exists within the device twin and is not digital twin conformant property. Please refer to aka.ms/dtpatch to update this to be conformant.

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

عند تحديث مكون، تأكد من تعيين الكائن الفارغ $metadata العلامة .

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

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

الآن بعد أن تعرفت على التوائم الرقمية، إليك بعض الموارد التالية: