بدء استخدام توائم الجهاز (Azure CLI)

مقالة
03/17/2023

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

إشعار

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

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

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

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

تخزن مراكز IoT توائم الجهاز، والتي تحتوي على العناصر التالية:

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

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

يوضح الرسم التوضيحي التالي تنظيم توأم الجهاز:

لقطة شاشة لمخطط مفهوم توأم الجهاز.

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

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

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

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

توضح هذه المقالة كيفية إنشاء جلستي Azure CLI:

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

المتطلبات الأساسية

Azure CLI يمكنك أيضا تشغيل الأوامر في هذه المقالة باستخدام Azure Cloud Shell، وهي واجهة CLI تفاعلية تعمل في المستعرض أو في تطبيق مثل وحدة طرفية لـ Windows. إذا كنت تستخدم Cloud Shell، فلن تحتاج إلى تثبيت أي شيء. إذا كنت تفضل استخدام CLI محليا، تتطلب هذه المقالة الإصدار 2.36 من Azure CLI أو أحدث. قم بتشغيل az --version للعثور على الإصدار. لتثبيت Azure CLI أو ترقيته محليا، راجع تثبيت Azure CLI.
IoT Hub. أنشئ واحدا باستخدام CLI أو مدخل Microsoft Azure.
تأكد من أن المنفذ 8883 مفتوح في جدار الحماية. تستخدم العينات في هذه المقالة بروتوكول MQTT، الذي يتصل عبر المنفذ 8883. يمكن حظر هذا المنفذ في بعض بيئات الشبكة التعليمية والشركات. لمزيد من المعلومات وطرق التغلب على هذه المشكلة، راجع الاتصال بمركز IoT (MQTT).

إعداد Cloud Shell

إذا كنت ترغب في استخدام Azure Cloud Shell، يجب أولا تشغيله وتكوينه. إذا كنت تستخدم CLI محليا، فانتقل إلى قسم Prepare two CLI sessions .

حدد أيقونة Cloud Shell من رأس الصفحة في مدخل Microsoft Azure.

إشعار

إذا كانت هذه المرة الأولى لاستخدامك Cloud Shell، فسيوجهك إلى إنشاء مخزن، وهو مطلوب لاستخدام Cloud Shell. حدد اشتراكاً لإنشاء حساب تخزين ومشاركة ملفات Microsoft Azure.
استخدم محدد البيئة في شريط أدوات Cloud Shell لتحديد بيئة CLI المفضلة لديك. تستخدم هذه المقالة بيئة Bash . يمكنك أيضا استخدام بيئة PowerShell .

إشعار

تتطلب بعض الأوامر بناء جملة أو تنسيقا مختلفا في بيئات Bash وPowerShell. لمزيد من المعلومات، راجع تلميحات لاستخدام Azure CLI بنجاح.

إعداد جلستي CLI

بعد ذلك، يجب إعداد جلستي Azure CLI. إذا كنت تستخدم Cloud Shell، يمكنك تشغيل هذه الجلسات في علامات تبويب Cloud Shell منفصلة. إذا كنت تستخدم عميل CLI محلي، يمكنك تشغيل مثيلات CLI منفصلة. استخدم جلسات CLI المنفصلة للمهام التالية:

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

إذا كنت تستخدم Cloud Shell، فانتقل إلى الخطوة التالية. وإلا، قم بتشغيل الأمر az login في جلسة CLI الأولى لتسجيل الدخول إلى حساب Azure الخاص بك.

إذا كنت تستخدم Cloud Shell، يتم تسجيل دخولك تلقائيا إلى حساب Azure الخاص بك. تتم مصادقة جميع الاتصالات بين جلسة Azure CLI ومركز IoT وتشفيرها. ونتيجة لذلك، لا تحتاج هذه المقالة إلى مصادقة إضافية تستخدمها مع جهاز حقيقي، مثل سلسلة الاتصال. لمزيد من المعلومات حول تسجيل الدخول باستخدام Azure CLI، راجع تسجيل الدخول باستخدام Azure CLI.
```
az login
```
في جلسة CLI الأولى، قم بتشغيل الأمر az extension add. يضيف الأمر Microsoft Azure IoT Extension لـ Azure CLI إلى CLI shell الخاص بك. يضيف الملحق أوامر محددة ل IoT Hub وIoT Edge وخدمة توفير جهاز IoT (DPS) إلى Azure CLI. بعد تثبيت الملحق، لن تحتاج إلى تثبيته مرة أخرى في أي جلسة عمل Cloud Shell.
```
az extension add --name azure-iot
```
إشعار

تستخدم هذه المقالة أحدث إصدار من ملحق 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.
افتح جلسة CLI الثانية. إذا كنت تستخدم Cloud Shell في مستعرض، فحدد أيقونة فتح جلسة عمل جديدة على شريط أدوات جلسة CLI الأولى. إذا كنت تستخدم CLI محلياً، فافتح مثيل CLI ثانياً.

إنشاء جهاز ومحاكاته

في هذا القسم، يمكنك إنشاء هوية جهاز لمركز IoT في جلسة CLI الأولى، ثم محاكاة جهاز باستخدام هوية الجهاز هذه. يستجيب جهاز المحاكاة للوظائف التي تقوم بجدولتها في جلسة CLI الثانية.

لإنشاء جهاز محاكاة وبدء تشغيله:

في جلسة CLI الأولى، قم بتشغيل الأمر az iot hub device-identity create ، واستبدل العناصر النائبة التالية بالقيم المقابلة لها. ينشئ هذا الأمر هوية الجهاز لجهاز المحاكاة الخاص بك.

{DeviceName}. اسم جهازك الذي تمت محاكاته.

{HubName}. اسم مركز IoT.
```
az iot hub device-identity create --device-id {DeviceName} --hub-name {HubName} 
```
في جلسة CLI الأولى، قم بتشغيل الأمر az iot device simulate ، واستبدل العناصر النائبة التالية بالقيم المقابلة لها. يحاكي هذا الأمر الجهاز الذي أنشأته في الخطوة السابقة. يقوم الأمر أيضا بتكوين الجهاز المحاكي للإبلاغ عن قناة الاتصال الخاصة به كخاصية تم الإبلاغ عنها على الجهاز المزدوج المقابل للجهاز عند تهيئته.

{DeviceName}. اسم جهازك الذي تمت محاكاته.

{HubName}. اسم مركز IoT.
```
az iot device simulate --device-id {DeviceName} --hub-name {HubName} \
                       --init-reported-properties '{"connectivity":{"type": "cellular"}}'
```
تلميح

بشكل افتراضي، يرسل الأمر az iot device simulate 100 رسالة من جهاز إلى سحابة بفاصل زمني مدته 3 ثوان بين الرسائل. تنتهي المحاكاة بعد إرسال جميع الرسائل. إذا كنت تريد تشغيل المحاكاة لفترة أطول، يمكنك استخدام المعلمة --msg-count لتحديد المزيد من الرسائل أو المعلمة --msg-interval لتحديد فاصل زمني أطول بين الرسائل. يمكنك أيضا تشغيل الأمر مرة أخرى لإعادة تشغيل جهاز المحاكاة.

تحديث الجهاز المزدوج

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

تأكد من تشغيل جهاز المحاكاة في جلسة CLI الأولى. إذا لم يكن الأمر كذلك، فعد تشغيله عن طريق تشغيل الأمر az iot device simulate مرة أخرى من إنشاء جهاز ومحاكاته.
في جلسة CLI الثانية، قم بتشغيل الأمر az iot hub device-twin update ، واستبدل العناصر النائبة التالية بالقيم المقابلة لها. في هذا المثال، نقوم بتحديث علامات متعددة على توأم الجهاز لهوية الجهاز التي أنشأناها في القسم السابق.

{DeviceName}. اسم جهازك.

{HubName}. اسم مركز IoT.
```
az iot hub device-twin update --device-id {DeviceName} --hub-name {HubName} \
                              --tags '{"location":{"region":"US","plant":"Redmond43"}}'
```

في جلسة CLI الثانية، تأكد من أن استجابة JSON تعرض نتائج عملية التحديث. في مثال استجابة JSON التالي، استخدمنا SampleDevice العنصر {DeviceName} النائب في az iot hub device-twin update أمر CLI.

{
  "authenticationType": "sas",
  "capabilities": {
    "iotEdge": false
  },
  "cloudToDeviceMessageCount": 0,
  "connectionState": "Connected",
  "deviceEtag": "MTA2NTU1MDM2Mw==",
  "deviceId": "SampleDevice",
  "deviceScope": null,
  "etag": "AAAAAAAAAAI=",
  "lastActivityTime": "0001-01-01T00:00:00+00:00",
  "modelId": "",
  "moduleId": null,
  "parentScopes": null,
  "properties": {
    "desired": {
      "$metadata": {
        "$lastUpdated": "2023-02-21T10:40:10.5062402Z"
      },
      "$version": 1
    },
    "reported": {
      "$metadata": {
        "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
        "connectivity": {
          "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
          "type": {
            "$lastUpdated": "2023-02-21T10:40:43.8539917Z"
          }
        }
      },
      "$version": 2,
      "connectivity": {
        "type": "cellular"
      }
    }
  },
  "status": "enabled",
  "statusReason": null,
  "statusUpdateTime": "0001-01-01T00:00:00+00:00",
  "tags": {
    "location": {
      "plant": "Redmond43",
      "region": "US"
    }
  },
  "version": 4,
  "x509Thumbprint": {
    "primaryThumbprint": null,
    "secondaryThumbprint": null
  }
}

الاستعلام عن مركز IoT الخاص بك لتوائم الجهاز

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

تأكد من تشغيل جهاز المحاكاة في جلسة CLI الأولى. إذا لم يكن الأمر كذلك، فعد تشغيله عن طريق تشغيل الأمر az iot device simulate مرة أخرى من إنشاء جهاز ومحاكاته.
في جلسة CLI الثانية، قم بتشغيل الأمر az iot hub query ، واستبدل العناصر النائبة التالية بالقيم المقابلة لها. في هذا المثال، نقوم بتصفية الاستعلام لإرجاع توائم الجهاز فقط للأجهزة الموجودة في مصنع Redmond43 .

{HubName}. اسم مركز IoT.
```
az iot hub query --hub-name {HubName} \
                 --query-command "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'" \
                 --top 100
```

في جلسة CLI الثانية، تأكد من أن استجابة JSON تعرض نتائج الاستعلام.

{
  "authenticationType": "sas",
  "capabilities": {
    "iotEdge": false
  },
  "cloudToDeviceMessageCount": 0,
  "connectionState": "Connected",
  "deviceEtag": "MTA2NTU1MDM2Mw==",
  "deviceId": "SampleDevice",
  "deviceScope": null,
  "etag": "AAAAAAAAAAI=",
  "lastActivityTime": "0001-01-01T00:00:00+00:00",
  "modelId": "",
  "moduleId": null,
  "parentScopes": null,
  "properties": {
    "desired": {
      "$metadata": {
        "$lastUpdated": "2023-02-21T10:40:10.5062402Z"
      },
      "$version": 1
    },
    "reported": {
      "$metadata": {
        "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
        "connectivity": {
          "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
          "type": {
            "$lastUpdated": "2023-02-21T10:40:43.8539917Z"
          }
        }
      },
      "$version": 2,
      "connectivity": {
        "type": "cellular"
      }
    }
  },
  "status": "enabled",
  "statusReason": null,
  "statusUpdateTime": "0001-01-01T00:00:00+00:00",
  "tags": {
    "location": {
      "plant": "Redmond43",
      "region": "US"
    }
  },
  "version": 4,
  "x509Thumbprint": {
    "primaryThumbprint": null,
    "secondaryThumbprint": null
  }
}

في جلسة CLI الثانية، قم بتشغيل الأمر az iot hub query ، واستبدل العناصر النائبة التالية بالقيم المقابلة لها. في هذا المثال، نقوم بتصفية الاستعلام لإرجاع توأم الجهاز فقط للأجهزة الموجودة في مصنع Redmond43 المتصل أيضا من خلال شبكة الجوال.

{HubName}. اسم مركز IoT.
```
az iot hub query --hub-name {HubName} \
                 --query-command "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' \
                                  AND properties.reported.connectivity.type = 'cellular'" \
                 --top 100
```
في جلسة CLI الثانية، تأكد من أن استجابة JSON تعرض نتائج الاستعلام. يجب أن تتطابق نتائج هذا الاستعلام مع نتائج الاستعلام السابق في هذا القسم.

في هذه المقالة، ستتمكن من:

تمت إضافة بيانات تعريف الجهاز كعلامات من جلسة عمل Azure CLI
محاكاة جهاز أبلغ عن معلومات اتصال الجهاز في الجهاز المزدوج
الاستعلام عن معلومات الجهاز المزدوجة، باستخدام لغة استعلام IoT Hub تشبه SQL في جلسة عمل Azure CLI

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

‏‫تعّرف على كيفية:

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

Share via