مشاركة عبر

الإدارة التلقائية لجهاز IoT والوحدة النمطية باستخدام Azure CLI

  • مقالة

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

إشعار

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

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

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

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

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

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

متطلبات CLI

إشعار

تستخدم هذه المقالة أحدث إصدار من ملحق Azure IoT، ويطلق عليه azure-iot. يسمى الإصدار القديم azure-cli-iot-ext. يجب أن يكون لديك إصدار واحد فقط مُثبت في كل مرة. يمكنك استخدام الأمر az extension list للتحقق من صحة الملحقات المثبتة حالياً.

استخدم az extension remove --name azure-cli-iot-ext لإزالة الإصدار القديم من الملحق.

استخدم az extension add --name azure-iot لإضافة الإصدار الجديد من الملحق.

لمعرفة ما هي الملحقات التي قمت بتثبيتها، استخدم az extension list.

تنفيذ التوائم

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

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

استخدام العلامات لاستهداف الأجهزة المزدوجة

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

"tags": {
	"location": {
		"state": "Washington",
		"city": "Tacoma"
    }
},

حدد المحتوى والقياسات المستهدفة

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

فيما يلي نموذج أساسي للمحتوى المستهدف للتكوين التلقائي للجهاز:

{
  "content": {
    "deviceContent": {
      "properties.desired.chillerWaterSettings": {
        "temperature": 38,
        "pressure": 78
      }
    }
}

تتصرف تكوينات الوحدة النمطية التلقائية بشكل شبيه جدًا، لكنك تستهدف moduleContent بدلاً من deviceContent.

{
  "content": {
    "moduleContent": {
      "properties.desired.chillerWaterSettings": {
        "temperature": 38,
        "pressure": 78
      }
    }
}

موضح أدناه أمثلة على استعلامات القياسات:

{
  "queries": {
    "Compliant": "select deviceId from devices where configurations.[[chillerdevicesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='current'",
    "Error": "select deviceId from devices where configurations.[[chillerdevicesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='error'",
    "Pending": "select deviceId from devices where configurations.[[chillerdevicesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='pending'"
  }
}

تشبه الاستعلامات القياسية للوحدات النمطية أيضًا الاستعلامات للأجهزة، ولكنك تحدد moduleId من devices.modules. على سبيل المثال:

{
  "queries": {
    "Compliant": "select deviceId, moduleId from devices.module where configurations.[[chillermodulesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='current'"
  }
}

إنشاء تكوين

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

يمكنك تكوين الأجهزة المستهدفة عن طريق إنشاء تكوين يتكون من المحتوى الهدف والمقاييس. استَخدم الأمر التالي لإنشاء تكوين:

   az iot hub configuration create --config-id [configuration id] \
     --labels [labels] --content [file path] --hub-name [hub name] \
     --target-condition [target query] --priority [int] \
     --metrics [metric queries]

  • --config-id - اسم التكوين الذي سيتم إنشاؤه في مركز إنترنت الأشياء. امنح التكوين اسمًا فريدًا يصل طوله إلى 128 حرفًا. يُسمح باستخدام الأحرف الصغيرة والأحرف الخاصة التالية:-+%_*!'. غير مسموح بالمسافات.

  • --التسميات أضف تسميات للمساعدة في تتبع التكوين الخاص بك. التسميات هي اسم وقيمة أزواج تصف التوزيع الخاص بك. على سبيل المثال، HostPlatform, Linux أو Version, 3.0.1

  • --المحتوى - JSON المضمن أو مسار الملف للمحتوى المستهدف الذي سيتم تعيينه كخصائص مزدوجة مرغوبة.

  • --اسم المركز اسم مركز إنترنت الأشياء الذي سيتم إنشاء التكوين فيه. يجب أن يكون المركز موجود في الاشتراك الحالي. قم بالتبديل إلى الاشتراك المطلوب باستخدام الأمر az account set -s [subscription name]

  • --الشرط المستهدف - أدخل شرطًا مستهدفًا لتحديد الأجهزة أو الوحدات النمطية التي سيتم استهدافها بهذا التكوين. للتكوين التلقائي للجهاز، تعتمد الحالة على العلامات المزدوجة للجهاز أو الخصائص المرغوبة للجهاز المزدوج ويجب أن تتطابق مع تنسيق التعبير. على سبيل المثال: tags.environment='test' أو properties.desired.devicemodel='4000x'. لتكوين الوحدة تلقائيًا، تعتمد الحالة على العلامات المزدوجة للوحدة أو الخصائص المرغوبة للوحدة المزدوجة. على سبيل المثال: from devices.modules where tags.environment='test' أو from devices.modules where properties.reported.chillerProperties.model='4000x'.

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

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

راقب التكوين

استَخدم الأمر التالي لعرض محتويات تكوين:

az iot hub configuration show --config-id [configuration id] \
  --hub-name [hub name]

  • --config-id - اسم التكوين الموجود في مركز إنترنت الأشياء.

  • --hub-name - اسم مركز إنترنت الأشياء الذي يوجد فيه التكوين. يجب أن يكون المركز موجود في الاشتراك الحالي. قم بالتبديل إلى الاشتراك المطلوب باستخدام الأمر az account set -s [subscription name]

افحص التكوين في نافذة الأمر. تسرد خاصية القياسات عددًا لكل قياس يتم تقييمه بواسطة كل مركز:

  • targetedCount - قياس نظام يحدد عدد توائم الجهاز أو توائم الوحدة في IoT Hub التي تتطابق مع حالة الاستهداف.

  • appliedCount - يحدد قياس النظام عدد الأجهزة أو الوحدات النمطية التي تم تطبيق المحتوى الهدف عليها.

  • مقياسك المخصص - أي مقاييس قمت بتعريفها هي مقاييس المستخدم.

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

az iot hub configuration show-metric --config-id [configuration id] \
   --metric-id [metric id] --hub-name [hub name] --metric-type [type]

  • --config-id - اسم التوزيع الموجود في مركز إنترنت الأشياء.

  • --metric-id - اسم القياس الذي تريد عرض قائمة معرفات الأجهزة أو معرفات الوحدة الخاصة به، على سبيل المثال appliedCount.

  • --hub-name - اسم مركز إنترنت الأشياء الذي يوجد فيه التوزيع. يجب أن يكون المركز موجود في الاشتراك الحالي. التبديل إلى الاشتراك المطلوب باستخدام الأمر az account set -s [subscription name].

  • --metric-type - يمكن لنوع القياس أن يكون system أو user. مقاييس النظام هي targetedCount و appliedCount. كافة المقاييس الأخرى هي مقاييس المستخدم.

عدّل تكوين

عند تعديل تكوين، يتم نسخ التغييرات فورًا إلى كافة الأجهزة المستهدفة.

إذا قمت بتحديث شرط الهدف، تحدث التحديثات التالية:

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

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

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

استخدم الأمر التالي لتحديث تكوين:

az iot hub configuration update --config-id [configuration id] \
   --hub-name [hub name] --set [property1.property2='value']

  • --config-id - اسم التكوين الموجود في مركز إنترنت الأشياء.

  • --hub-name - اسم مركز إنترنت الأشياء الذي يوجد فيه التكوين. يجب أن يكون المركز موجود في الاشتراك الحالي. التبديل إلى الاشتراك المطلوب باستخدام الأمر az account set -s [subscription name].

  • --set - تحديث خاصية في التكوين. احرص على تحديث قيم الخصائص التالية:

    • شرط الهدف - على سبيل المثالtargetCondition=tags.location.state='Oregon'

    • التسميات

    • أولوية

حذف تكوين

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

استخدم الأمر التالي لحَذف تكوين:

az iot hub configuration delete --config-id [configuration id] \
   --hub-name [hub name]

  • --config-id - اسم التكوين الموجود في مركز إنترنت الأشياء.

  • --hub-name - اسم مركز إنترنت الأشياء الذي يوجد فيه التكوين. يجب أن يكون المركز موجود في الاشتراك الحالي. التبديل إلى الاشتراك المطلوب باستخدام الأمر az account set -s [subscription name].

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

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

لمعرفة كيفية إدارة هويات جهاز IoT Hub بشكل مجمع، راجع استيراد هويات جهاز IoT Hub وتصديرها بشكل مجمع