كيفية استخدام الأوامر في حل Azure IoT Central

  • مقالة

يوضح لك دليل الكيفية هذا كيفية استخدام الأوامر المحددة في قالب الجهاز.

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

يمكن للجهاز:

  • الاستجابة لأمر على الفور.
  • الاستجابة إلى IoT Central عندما يتلقى الأمر ثم إعلام IoT Central لاحقا عند اكتمال الأمر طويل الأمد.

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

للتعرف على اصطلاحات أوامر IoT Pug وPlay، راجع اصطلاحات أجهزة التوصيل و التشغيل IoT.

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

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

لمعرفة كيفية تنفيذ الأوامر في جهاز دون استخدام حزم SDK للجهاز، راجع الاتصال بمركز IoT باستخدام بروتوكول MQTT.

تعريف الأوامر الخاصة بك

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

يتم تعريف الأوامر كجزء من قالب الجهاز. تظهر لقطة الشاشة التالية تعريف أمر Get Max-Min report في قالب جهاز Thermostat . يحتوي هذا الأمر على معلمات الطلب والاستجابة:

Screenshot showing Get Max Min Report command in Thermostat device template.

يوضّح الجدول التالي إعدادات التكوين لإمكانية أمر:

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

للتعرف على لغة تعريف التوأم الرقمي (DTDL) التي يستخدمها Azure IoT Central لتعريف الأوامر في قالب جهاز، راجع أوامر اصطلاحات >IoT أجهزة التوصيل و التشغيل.

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

الأوامر القياسية

لمعالجة أمر قياسي، يرسل الجهاز قيمة استجابة بمجرد أن يتلقى الأمر من IoT Central. يمكنك استخدام SDK لجهاز Azure IoT للتعامل مع الأوامر القياسية التي يستدعيها تطبيق IoT Central.

على سبيل المثال التطبيقات بلغات متعددة، راجع إنشاء تطبيق عميل وتوصيله بتطبيق Azure IoT Central.

توضح لقطة الشاشة التالية كيفية عرض استجابة الأوامر الناجحة في واجهة مستخدم IoT Central:

Screenshot showing how to view command payload for a standard command.

إشعار

بالنسبة للأوامر القياسية، هناك مهلة 30 ثانية. إذا لم يستجب الجهاز في غضون 30 ثانية، يفترض IoT Central أن الأمر فشل. فترة المهلة هذه غير قابلة للتكوين.

أوامر طويلة الأمد

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

إشعار

الأوامر طويلة الأمد ليست جزءا من اصطلاحات IoT أجهزة التوصيل و التشغيل. لدى IoT Central اصطلاحه الخاص لتنفيذ الأوامر طويلة الأمد.

يوضح لك هذا القسم كيف يمكن للجهاز تأخير إرسال تأكيد بإكمال الأمر.

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

إشعار

تستخدم هذه المقالة Node.js للتبسيط.

client.onDeviceMethod('rundiagnostics', commandHandler);

// ...

const commandHandler = async (request, response) => {
  switch (request.methodName) {
  case 'rundiagnostics': {
    console.log('Starting long-running diagnostics run ' + request.payload);
    await sendCommandResponse(request, response, 202, 'Diagnostics run started');

    // Long-running operation here
    // ...

    const patch = {
      rundiagnostics: {
        value: 'Diagnostics run complete at ' + new Date().toLocaleString()
      }
    };

    deviceTwin.properties.reported.update(patch, function (err) {
      if (err) throw err;
      console.log('Properties have been reported for component');
    });
    break;
  }
  default:
    await sendCommandResponse(request, response, 404, 'unknown method');
    break;
  }
};

الاستدعاء لإعداد onDeviceMethodcommandHandler الأسلوب . معالج الأوامر هذا:

  1. التحقق من اسم الأمر.
  2. استدعاءات sendCommandResponse لإرسال الاستجابة مرة أخرى إلى IoT Central. تتضمن هذه الاستجابة رمز الاستجابة 202 للإشارة إلى النتائج المعلقة.
  3. إكمال العملية طويلة الأمد.
  4. يستخدم خاصية تم الإبلاغ عنها بنفس اسم الأمر لإخبار IoT Central أن الأمر قد اكتمل.

تظهر لقطة الشاشة التالية واجهة مستخدم IoT Central عندما تتلقى تحديث الخاصية الذي يشير إلى اكتمال الأمر:

Screenshot that shows long-running command finished.

الأوامر غير المتصلة

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

إشعار

الأوامر غير المتصلة ليست جزءا من اصطلاحات أجهزة التوصيل و التشغيل IoT. لدى IoT Central اصطلاحه الخاص لتنفيذ الأوامر دون اتصال.

إشعار

تستخدم هذه المقالة Node.js للتبسيط.

تظهر لقطة الشاشة التالية أمر غير متصل يسمى GenerateDiagnostics. معلمة الطلب هي كائن بخاصية datetime تسمى StartTime وخاصية تعداد عدد صحيح تسمى Bank:

Screenshot that shows the UI for an offline command.

توضح القصاصة البرمجية التالية كيف يمكن للعميل الاستماع إلى الأوامر دون اتصال وعرض محتويات الرسالة:

client.on('message', function (msg) {
  console.log('Body: ' + msg.data);
  console.log('Properties: ' + JSON.stringify(msg.properties));
  client.complete(msg, function (err) {
    if (err) {
      console.error('complete error: ' + err.toString());
    } else {
      console.log('complete sent');
    }
  });
});

يظهر الإخراج من القصاصة البرمجية السابقة الحمولة مع قيم StartTime و Bank . تتضمن قائمة الخصائص اسم الأمر في عنصر قائمة اسم الأسلوب:

Body: {"StartTime":"2021-01-06T06:00:00.000Z","Bank":2}
Properties: {"propertyList":[{"key":"iothub-ack","value":"none"},{"key":"method-name","value":"GenerateDiagnostics"}]}

إشعار

مدة البقاء الافتراضية للأوامر غير المتصلة هي 24 ساعة، تنتهي بعدها صلاحية الرسالة.

الأوامر على الأجهزة غير المعينة

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

Screenshot that shows an example of calling a command on an unassigned device.

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

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