إدارة إنترنت الأشياء أجهزة التوصيل و التشغيل التوائم الرقمية
يدعم IoT أجهزة التوصيل و التشغيل الحصول على التوأم الرقمي وتحديث عمليات التوأم الرقمي لإدارة التوائم الرقمية. يمكنك استخدام واجهات برمجة تطبيقات REST أو إحدى مجموعات SDK للخدمة.
في وقت كتابة هذا التقرير ، إصدار واجهة برمجة التطبيقات الرقمية التوأم هو 2020-09-30.
تحديث التوأم الرقمي
يقوم جهاز أجهزة التوصيل و التشغيل إنترنت الأشياء بتنفيذ نموذج موصوف بواسطة لغة تعريف التوائم الرقمية v2 (DTDL). يمكن لمطوري الحلول استخدام واجهة برمجة تطبيقات Update Digital Twin لتحديث حالة المكون وخصائص التوأم الرقمي.
يقوم جهاز IoT أجهزة التوصيل و التشغيل المستخدم كمثال في هذه المقالة بتنفيذ نموذج وحدة التحكم في درجة الحرارة مع مكونات Thermostat.
يعرض المقتطف التالي الاستجابة لطلب الحصول على توأم رقمي منسق ككائن JSON. لمعرفة المزيد حول تنسيق التوأم الرقمي، راجع فهم إنترنت الأشياء أجهزة التوصيل و التشغيل التوائم الرقمية:
{
"$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.
على سبيل المثال، يمكنك تحديث الخاصية 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 التالي كيفية إضافة مكون أو استبداله أو إزالته:
[
{
"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 التالي كيفية إضافة خاصية أو استبدالها أو إزالتها داخل مكون:
[
{
"op": "add",
"path": "/thermostat1/targetTemperature",
"value": 21.4
},
{
"op": "replace",
"path": "/thermostat1/anotherWritableProperty",
"value": 42
},
{
"op": "remove",
"path": "/thermostat2/targetTemperature",
}
]
قواعد لتحديد القيمة المطلوبة لخاصية التوأم الرقمي
الاسم
يجب أن يكون اسم المكون أو الخاصية اسم DTDL v2 صالحا.
الأحرف المسموح بها هي a-z و A-Z و 0-9 (وليس كالحرف الأول) ، وتسطير سفلي (وليس كالحرف الأول أو الأخير).
يمكن أن يتراوح طول الاسم بين 1 و 64 حرفا.
قيمة العقار
يجب أن تكون القيمة خاصية DTDL v2 صالحة.
يتم دعم جميع الأنواع البدائية. ضمن الأنواع المعقدة ، يتم دعم التعداد والخرائط والكائنات. لمعرفة المزيد، راجع مخططات DTDL v2.
لا تدعم الخصائص الصفيف أو أي مخطط معقد مع صفيف.
يتم دعم أقصى عمق لخمسة مستويات لكائن معقد.
يجب أن تكون كافة أسماء الحقول داخل الكائن المعقد أسماء DTDL v2 صالحة.
يجب أن تكون جميع مفاتيح الخريطة أسماء DTDL v2 صالحة.
استكشاف أخطاء واجهة برمجة تطبيقات التوأم الرقمي للتحديث وإصلاحها
واجهة برمجة التطبيقات الرقمية التوأم يلقي رسالة الخطأ العامة التالية:
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 العلامة .
يمكن أن تفشل التحديثات إذا كانت القيم التي تم الإبلاغ عنها للجهاز لا تتوافق مع اتفاقيات التوصيل والتشغيل الخاصة بإنترنت الأشياء.
الخطوات التالية
الآن بعد أن تعرفت على التوائم الرقمية ، إليك بعض الموارد الإضافية: