البرنامج التعليمي: تطوير وحدات IoT Edge باستخدام Visual Studio Code

  • مقالة

ينطبق على:IoT Edge 1.4 checkmark IoT Edge 1.4

هام

IoT Edge 1.4 هو الإصدار المدعوم. إذا كنت تستخدم إصدارا سابقا، فشاهد تحديث IoT Edge.

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

تتضمن هذه المقالة خطوات لأدوتي تطوير IoT Edge.

  • سطر أوامر Azure IoT Edge Dev Tool (CLI). هذه الأداة مفضلة للتطوير.
  • أدوات Azure IoT Edge لملحق Visual Studio Code . الملحق في وضع الصيانة.

استخدم زر محدد الأداة في بداية هذه المقالة لتحديد إصدار الأداة.

في هذا البرنامج التعليمي، تتعلم كيفية:

  • إعداد جهاز التطوير الخاص بك.
  • استخدم أدوات IoT Edge لإنشاء مشروع جديد.
  • أنشئ مشروعك كحاوية Docker وقم بتخزينه في سجل حاوية Azure.
  • نشر التعليمات البرمجية إلى جهاز IoT Edge.

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

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

آلة التطوير:

  • استخدم الكمبيوتر الخاص بك أو جهاز ظاهري.
  • يجب أن يدعم جهاز التطوير الظاهرية المتداخلة لتشغيل محرك حاوية.
  • يمكن استخدام معظم أنظمة التشغيل التي يمكنها تشغيل محرك حاوية لتطوير وحدات IoT Edge لأجهزة Linux. يستخدم هذا البرنامج التعليمي جهاز كمبيوتر Windows، ولكنه يشير إلى الاختلافات المعروفة على macOS أو Linux.
  • تثبيت التعليمات البرمجية لتطبيق Visual Studio
  • قم بتثبيت Azure CLI.

جهاز An Azure IoT Edge:

موارد السحابة:

  • مركز IoTمجاني أو قياسي المستوى في Azure.

إذا لم يكن لديك اشتراك في Azure، فأنشئ حساب Azure مجاني قبل أن تبدأ.

تلميح

للحصول على إرشادات حول التصحيح التفاعلي في Visual Studio Code أو Visual Studio 2022:

هذا البرنامج التعليمي يعلم خطوات تطوير Visual Studio Code.

المفاهيم الرئيسية

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

عند تطوير وحدات IoT Edge، من المهم فهم الفرق بين جهاز التطوير وجهاز IoT Edge الهدف حيث يتم نشر الوحدة النمطية. يجب أن تتطابق الحاوية التي تقوم ببنائها للاحتفاظ برمز الوحدة النمطية مع نظام التشغيل (OS) الخاص بالجهاز الهدف. على سبيل المثال، السيناريو الأكثر شيوعًا هو شخص ما يقوم بتطوير وحدة نمطية على جهاز كمبيوتر Windows ينوي استهداف جهاز Linux يقوم بتشغيل IoT Edge. في هذه الحالة، فإن نظام تشغيل الحاويات يكون Linux. خلال هذا البرنامج التعليمي، نضع في اعتبارنا الفرق بين نظام التشغيل جهاز التطوير ونظام التشغيل الحاوية.

تلميح

إذا كنت تستخدم IoT Edge لنظام Linux على Windows، فإن الجهاز المستهدف في السيناريو الخاص بك هو الجهاز الظاهري Linux، وليس المضيف Windows.

يستهدف هذا البرنامج التعليمي الأجهزة التي تعمل على IoT Edge باستخدام حاويات Linux. يمكنك استخدام نظام التشغيل المفضل لديك طالما أن جهاز التطوير الخاص بك يعمل بحاويات Linux. نوصي باستخدام Visual Studio Code للتطوير باستخدام حاويات Linux، لذلك هذا ما يستخدمه هذا البرنامج التعليمي. يمكنك استخدام Visual Studio أيضًا، على الرغم من وجود اختلافات في الدعم بين الأداتين.

يسرد الجدول التالي سيناريوهات التطوير المعتمدة لحاويات Linux في Visual Studio وVisual Studio.

تعليمة Visual Studio برمجية Visual Studio 2019/2022
هندسة جهاز Linux Linux AMD64
Linux ARM32v7
Linux ARM64		 Linux AMD64
Linux ARM32
Linux ARM64
خدمات Azure Azure Functions
Azure Stream Analytics
التعلم الآلي من Azure
اللغات ج
C#‎
Java
Node.js
Python		 ج
C#‎
مزيد من المعلومات Azure IoT Edge لأجل Visual Studio Code Azure IoT Edge Tools لأجل Visual Studio 2019
أدوات Azure IoT Edge ل Visual Studio 2022

تثبيت محرك حاوية

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

استخدم وثائق Docker لتثبيتها على جهاز التطوير:

إعداد الأدوات

قم بتثبيت أداة تطوير Azure IoT Edge المستندة إلى Python لإنشاء حل IoT Edge. يوجد خياران:

هام

أدوات Azure IoT Edge لملحق Visual Studio Code في وضع الصيانة. أداة التطوير المفضلة هي سطر الأوامر (CLI) Azure IoT Edge Dev Tool.

استخدم ملحقات IoT للتعليمات البرمجية Visual Studio لتطوير وحدات IoT Edge. توفر هذه الملحقات قوالب المشروع، وتأتمتة إنشاء بيان التوزيع، وتسمح لك بمراقبة أجهزة IoT Edge وإدارتها. في هذا القسم، يمكنك تثبيت رمز Visual Studio وملحق IoT، ثم قم بإعداد حساب Azure الخاص بك لإدارة موارد IoT Hub من داخل Visual Studio Code.

  1. تثبيت ملحق Azure IoT Edge .

  2. تثبيت ملحق Azure IoT Hub .

  3. بعد تثبيت الملحقات، افتح لوحة الأوامر عن طريق تحديد View>Command Palette.

  4. في لوحة الأوامر مرة أخرى، ابحث عن وحدد مركز Azure IoT: حدد مركز IoT. اتبع المطالبات لتحديد اشتراك Azure وIoT Hub.

  5. افتح قسم مستكشف Visual Studio Code إما بتحديد الرمز في شريط النشاط على اليسار، أو بتحديد عرض>المستكشف.

  6. في الجزء السفلي من قسم المستكشف، قم بتوسيع القائمة المخفية مركز / أجهزة Azure IoT. يجب أن تشاهد الأجهزة وأجهزة IoT Edge المقترنة ب IoT Hub التي حددتها من خلال لوحة الأوامر.

تثبيت أدوات خاصة باللغة

تثبيت أدوات خاصة باللغة التي تقوم بتطويرها:

إنشاء سجل حاويات

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

هام

ملحق Azure IoT Edge Visual Studio Code في وضع الصيانة.

يمكنك استخدام أي تسجيل متوافق مع Docker للاحتفاظ بصور الحاوية. خدمتان شائعتان لسجل Docker هما Azure Container Registry وDocker Hub. يستخدم هذا البرنامج التعليمي Azure Container Registry.

إذا لم يكن لديك سجل حاويات بالفعل، فاتبع الخطوات التالية لإنشاء سجل جديد في Azure:

  1. في مدخل Microsoft Azure، حدد Create a resource>Containers>Container Registry.

  2. قم بتوفير القيم المطلوبة التالية لإنشاء سجل الحاوية الخاص بك:

    الحقل القيمة
    الاشتراك حدد اشتراكك من القائمة المنسدلة.
    مجموعة الموارد استخدم نفس مجموعة الموارد لجميع موارد الاختبار التي تقوم بإنشائها أثناء التشغيل السريع والبرامج التعليمية ل IoT Edge. على سبيل المثال، IoTEdgeResources.
    اسم السجل قم بتوفير اسم مميز.
    الموقع حدد موقعًا قريبًا منك.
    وحدة حفظ المخزون SKU حدد أساسي.

  3. حدد Review + create، ثم Create.

  4. حدد سجل الحاوية الجديد من قسم الموارد في الصفحة الرئيسية لمدخل Azure لفتحه.

  5. في الجزء الأيمن من سجل الحاوية، حدد Access keys من القائمة الموجودة ضمن الإعدادات.

    Screenshot of the Access Keys menu location.

  6. تمكين مسؤول المستخدم باستخدام زر التبديل وعرض اسم المستخدم وكلمة المرور لسجل الحاوية.

  7. انسخ قيم خادم تسجيل الدخول واسم المستخدم وكلمة المرور واحفظها في مكان مناسب. يمكنك استخدام هذه القيم خلال هذا البرنامج التعليمي لتوفير الوصول إلى تسجيل الحاوية.

إنشاء مشروع وحدة

يوفر ملحق Azure IoT Edge قوالب المشروع لجميع لغات وحدة IoT Edge المدعومة في Visual Studio Code. تحتوي هذه القوالب على كافة الملفات والتعليمات البرمجية التي تحتاجها لنشر وحدة عمل لاختبار IoT Edge، أو تمنحك نقطة بداية لتخصيص القالب بمنطق العمل الخاص بك.

إنشاء قالب مشروع

تعمل أداة تطوير IoT Edge على تبسيط تطوير Azure IoT Edge إلى الأوامر التي تحركها متغيرات البيئة. فهو يرشدك إلى البدء في تطوير IoT Edge باستخدام حاوية تطوير IoT Edge وسقالة حل IoT Edge التي تحتوي على وحدة نمطية افتراضية وجميع ملفات التكوين المطلوبة.

  1. إنشاء دليل للحل الخاص بك مع المسار الذي تختاره. قم بالتغيير إلى الدليل الخاص بك iotedgesolution .

    mkdir c:\dev\iotedgesolution
cd c:\dev\iotedgesolution

  2. استخدم الأمر iotedgedev solution init لإنشاء حل وإعداد Azure IoT Hub بلغة التطوير التي تختارها.

    iotedgedev solution init --template csharp

يطالبك البرنامج النصي iotedgedev solution init بإكمال عدة خطوات بما في ذلك:

  • مصادقة Azure
  • اختيار اشتراك Azure
  • اختيار مجموعة موارد أو إنشائها
  • اختر أو أنشئ Azure IoT Hub
  • اختيار جهاز Azure IoT Edge أو إنشائه

استخدم Visual Studio Code وملحق Azure IoT Edge . تبدأ بإنشاء حل، ثم إنشاء الوحدة النمطية الأولى في هذا الحل. يمكن أن يحتوي كل حل على وحدات نمطية متعددة.

  1. حدد View>Command Palette.
  2. في لوحة الأوامر، أدخل الأمر Azure IoT Edge: New IoT Edge Solution وقم بتشغيله.
  3. استعرض وصولا إلى المجلد الذي تريد إنشاء الحل الجديد فيه، ثم حدد تحديد مجلد.
  4. أدخل اسما للحل الخاص بك.
  5. حدد قالب وحدة نمطية للغة التطوير المفضلة لتكون الوحدة النمطية الأولى في الحل.
  6. أدخل اسما للوحدة النمطية. اختر اسما فريدا في سجل الحاويات.
  7. توفير اسم مستودع الصور للوحدة النمطية. يقوم Visual Studio Code بملء اسم الوحدة النمطية تلقائيا باسم localhost:5000/<your module name>. استبدله بمعلومات التسجيل الخاصة بك. استخدم localhost إذا كنت تستخدم سجل Docker محليا للاختبار. إذا كنت تستخدم Azure Container Registry، فاستخدم خادم تسجيل الدخول من إعدادات السجل. يبدو خادم تسجيل الدخول مثل <اسم> السجل.azurecr.io. استبدل فقط جزء localhost:5000 من السلسلة بحيث تبدو النتيجة النهائية مثل< اسم> السجل.azurecr.io/< اسم> الوحدة النمطية.

تقوم Visual Studio التعليمات البرمجية بأخذ المعلومات التي قدمتها، وتنشئ حل IoT Edge، ثم تقوم بتحميله في نافذة جديدة.

بعد إنشاء الحل، تكون هذه الملفات الرئيسية في الحل:

  • يحتوي مجلد .vscode على ملف تكوين launch.json.

  • مجلد وحدات يحتوي على مجلدات فرعية لكل وحدة نمطية. داخل المجلد الفرعي لكل وحدة نمطية، يتحكم ملف module.json في كيفية إنشاء الوحدات النمطية ونشرها.

  • يسرد ملف .env متغيرات البيئة الخاصة بك. متغير البيئة لسجل الحاوية هو localhost:5000 بشكل افتراضي.

  • يسرد ملفا توزيع الوحدة النمطية المسميان deployment.template.json deployment.debug.template.json الوحدات النمطية لنشرها على جهازك. بشكل افتراضي، تتضمن القائمة وحدات نظام IoT Edge (edgeAgent وedgeHub) ونماذج الوحدات النمطية مثل:

    إشعار

    قد تعتمد الوحدات النمطية الدقيقة المثبتة على اللغة التي تختارها.

تعيين إصدار وقت تشغيل IoT Edge

أحدث إصدار وحدة نمطية مستقرة لنظام IoT Edge هو 1.4. قم بتعيين وحدات النظام النمطية إلى الإصدار 1.4.

  1. في Visual Studio Code، افتح ملف بيان توزيع deployment.template.json . بيان النشر هو مستند JSON يصف الوحدات النمطية التي سيتم تكوينها على جهاز IoT Edge المستهدف.

  2. تغيير إصدار وقت التشغيل لصور وحدة وقت تشغيل النظام edgeAgent وedgeHub. على سبيل المثال، إذا كنت تريد استخدام الإصدار 1.4 من وقت تشغيل IoT Edge، فقم بتغيير الأسطر التالية في ملف بيان التوزيع:

    "systemModules": {
    "edgeAgent": {

        "image": "mcr.microsoft.com/azureiotedge-agent:1.4",

    "edgeHub": {

        "image": "mcr.microsoft.com/azureiotedge-hub:1.4",

توفير بيانات اعتماد التسجيل إلى عامل IoT Edge

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

يحاول ملحق IoT Edge سحب بيانات اعتماد تسجيل الحاوية من Azure وملأها في ملف البيئة.

إشعار

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

تحقق لمعرفة ما إذا كانت بيانات الاعتماد موجودة. إذا لم يكن كذلك، فأضفها الآن:

  1. إذا كان Azure Container Registry هو السجل الخاص بك، فقم بتعيين اسم مستخدم وكلمة مرور Azure Container Registry. احصل على هذه القيم من قائمة مفاتيح الإعدادات> Access الخاصة بسجل الحاوية في مدخل Microsoft Azure.

  2. افتح ملف .env في حل الوحدة النمطية الخاصة بك.

  3. أضف قيمUsername وPassword من سجل حاوية Azure الخاص بك. على سبيل المثال:

    CONTAINER_REGISTRY_SERVER="myacr.azurecr.io"
CONTAINER_REGISTRY_USERNAME="myacr"
CONTAINER_REGISTRY_PASSWORD="<registry_password>"

  4. احفظ التغييرات التي أجريتها على ملف .env .

إشعار

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

البنية المستهدفة

تحتاج إلى تحديد البنية التي تستهدفها مع كل حل، لأن ذلك يؤثر على كيفية إنشاء الحاوية وتشغيلها. الافتراضي هو Linux AMD64. في هذا البرنامج التعليمي، نستخدم جهاز Ubuntu ظاهريا كجهاز IoT Edge ونحتفظ ب amd64 الافتراضي.

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

  1. افتح لوحة الأوامر وابحث عن Azure IoT Edge: Set Default Target Platform for Edge Solution، أو حدد رمز الاختصار في الشريط الجانبي أسفل النافذة.

  2. في لوحة الأوامر، حدد بنية الهدف من قائمة الخيارات.

يتم تعيين البنية الهدف عند إنشاء صورة الحاوية في خطوة لاحقة.

تحديث الوحدة النمطية باستخدام التعليمات البرمجية المخصصة

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

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

نموذج التعليمات البرمجية C# التي تأتي مع قالب المشروع يستخدم فئة ModuleClient من مركز SDK IoT لأجل .NET.

  1. في مستكشف Visual Studio Code، افتح الوحدات النمطية>filtermodule>ModuleBackgroundService.cs.

  2. قبل مساحة اسم filtermodule، أضف ثلاث عبارات باستخدام الأنواع التي يتم استخدامها لاحقا:

    using System.Collections.Generic;     // For KeyValuePair<>
using Microsoft.Azure.Devices.Shared; // For TwinCollection
using Newtonsoft.Json;                // For JsonConvert

  3. أضف متغير temperatureThreshold إلى فئة ModuleBackgroundService. يضبط هذا المتغير القيمة التي يجب أن تتجاوزها درجة الحرارة المقاسة للبيانات التي سيتم إرسالها إلى مركز IoT.

    static int temperatureThreshold { get; set; } = 25;

  4. أضف فئات MessageBody وM machine وAmbient. تعمل هذه الفئات على تعريف المخطط المتوقع للنص الأساسي الرسائل الواردة.

    class MessageBody
{
    public Machine machine {get;set;}
    public Ambient ambient {get; set;}
    public string timeCreated {get; set;}
}
class Machine
{
    public double temperature {get; set;}
    public double pressure {get; set;}
}
class Ambient
{
    public double temperature {get; set;}
    public int humidity {get; set;}
}

  5. ابحث عن الدالة ExecuteAsync . تقوم هذه الدالة بإنشاء وتكوين كائن ModuleClient الذي يسمح للوحدة النمطية بالاتصال بوقت تشغيل Azure IoT Edge المحلي لإرسال الرسائل وتلقيها. بعد إنشاء ModuleClient، تقرأ التعليمات البرمجية قيمة temperatureThreshold من الخصائص المطلوبة للوحدة النمطية المزدوجة. تسجل التعليمات البرمجية رد اتصال لتلقي رسائل من مركز IoT Edge عبر نقطة نهاية تسمى input1.

    استبدل الاستدعاء إلى الأسلوب ProcessMessageAsync بأسلوب جديد يقوم بتحديث اسم نقطة النهاية والأسلوب الذي يتم استدعاؤه عند وصول الإدخال. أضف أيضا طريقة SetDesiredPropertyUpdateCallbackAsync للتحديثات إلى الخصائص المطلوبة. لإجراء هذا التغيير، استبدل السطر الأخير من أسلوب ExecuteAsync بالتعليمات البرمجية التالية:

    // Register a callback for messages that are received by the module.
// await _moduleClient.SetInputMessageHandlerAsync("input1", PipeMessage, cancellationToken);

// Read the TemperatureThreshold value from the module twin's desired properties
var moduleTwin = await _moduleClient.GetTwinAsync();
await OnDesiredPropertiesUpdate(moduleTwin.Properties.Desired, _moduleClient);

// Attach a callback for updates to the module twin's desired properties.
await _moduleClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertiesUpdate, null);

// Register a callback for messages that are received by the module. Messages received on the inputFromSensor endpoint are sent to the FilterMessages method.
await _moduleClient.SetInputMessageHandlerAsync("inputFromSensor", FilterMessages, _moduleClient);

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

    static Task OnDesiredPropertiesUpdate(TwinCollection desiredProperties, object userContext)
{
    try
    {
        Console.WriteLine("Desired property change:");
        Console.WriteLine(JsonConvert.SerializeObject(desiredProperties));

        if (desiredProperties["TemperatureThreshold"]!=null)
            temperatureThreshold = desiredProperties["TemperatureThreshold"];

    }
    catch (AggregateException ex)
    {
        foreach (Exception exception in ex.InnerExceptions)
        {
            Console.WriteLine();
            Console.WriteLine("Error when receiving desired property: {0}", exception);
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error when receiving desired property: {0}", ex.Message);
    }
    return Task.CompletedTask;
}

  7. أضف أسلوب FilterMessages. يتم استدعاء هذه الطريقة عندما تتلقى الوحدة النمطية رسالة من مركز IoT Edge. فهو يعمل على تصفية الرسائل التي تبلغ عن درجات حرارة أقل من الحد الأدنى لدرجة الحرارة التي تم ضبطها عبر الوحدة المزدوجة. كما يضيف خاصية MessageType إلى الرسالة مع تعيين القيمة إلى Alert.

    async Task<MessageResponse> FilterMessages(Message message, object userContext)
{
    var counterValue = Interlocked.Increment(ref _counter);
    try
    {
        ModuleClient moduleClient = (ModuleClient)userContext;
        var messageBytes = message.GetBytes();
        var messageString = Encoding.UTF8.GetString(messageBytes);
        Console.WriteLine($"Received message {counterValue}: [{messageString}]");

        // Get the message body.
        var messageBody = JsonConvert.DeserializeObject<MessageBody>(messageString);

        if (messageBody != null && messageBody.machine.temperature > temperatureThreshold)
        {
            Console.WriteLine($"Machine temperature {messageBody.machine.temperature} " +
                $"exceeds threshold {temperatureThreshold}");
            using (var filteredMessage = new Message(messageBytes))
            {
                foreach (KeyValuePair<string, string> prop in message.Properties)
                {
                    filteredMessage.Properties.Add(prop.Key, prop.Value);
                }

                filteredMessage.Properties.Add("MessageType", "Alert");
                await moduleClient.SendEventAsync("output1", filteredMessage);
            }
        }

        // Indicate that the message treatment is completed.
        return MessageResponse.Completed;
    }
    catch (AggregateException ex)
    {
        foreach (Exception exception in ex.InnerExceptions)
        {
            Console.WriteLine();
            Console.WriteLine("Error in sample: {0}", exception);
        }
        // Indicate that the message treatment is not completed.
        var moduleClient = (ModuleClient)userContext;
        return MessageResponse.Abandoned;
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
        // Indicate that the message treatment is not completed.
        ModuleClient moduleClient = (ModuleClient)userContext;
        return MessageResponse.Abandoned;
    }
}

  8. احفظ ملف ModuleBackgroundService.cs.

  9. في مستكشف Visual Studio Code، افتح ملف deployment.template.json في مساحة عمل حل IoT Edge.

  10. نظرا لأننا قمنا بتغيير اسم نقطة النهاية التي تستمع إليها الوحدة النمطية، نحتاج أيضا إلى تحديث المسارات في بيان النشر بحيث يرسل edgeHub رسائل إلى نقطة النهاية الجديدة.

    ابحث عن قسم المسارات في الوحدة النمطية المزدوجة $edgeHub . تحديث مسار sensorTofiltermodule لاستبدال input1 ب inputFromSensor:

    "sensorTofiltermodule": "FROM /messages/modules/tempSensor/outputs/temperatureOutput INTO BrokeredEndpoint(\"/modules/filtermodule/inputs/inputFromSensor\")"

  11. أضف الوحدة النمطية filtermodule المزدوجة إلى بيان التوزيع. إدراج محتوى JSON التالي في أسفل قسم modulesContent، بعد $edgeHub الوحدة النمطية المزدوجة:

       "filtermodule": {
       "properties.desired":{
           "TemperatureThreshold":25
       }
   }

  12. احفظ ملف deployment.template.js.

بناء ودفع الحل الخاص بك

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

في Visual Studio Code، افتح ملف بيان توزيع deployment.template.json . يصف بيان التوزيع الوحدات النمطية التي سيتم تكوينها على جهاز IoT Edge المستهدف. قبل النشر، تحتاج إلى تحديث بيانات اعتماد Azure Container Registry وصور الوحدة النمطية بالقيم المناسبة createOptions . لمزيد من المعلومات حول قيم createOption، راجع كيفية تكوين خيارات إنشاء الحاوية لوحدات IoT Edge النمطية.

إذا كنت تستخدم Azure Container Registry لتخزين صورة الوحدة النمطية الخاصة بك، فأضف بيانات الاعتماد الخاصة بك إلى قسم modulesContent>edgeAgent>settings>registryCredentials في deployment.template.json. استبدل myacr باسم السجل الخاص بك وقدم كلمة المرور وعنوان خادم تسجيل الدخول. على سبيل المثال:

"registryCredentials": {
    "myacr": {
        "username": "myacr",
        "password": "<your_acr_password>",
        "address": "myacr.azurecr.io"
    }
}

أضف المحتوى المتسلسل التالي أو استبدله بقيمة createOptions لكل نظام (edgeHub وedgeAgent) والوحدة النمطية المخصصة (filtermodule و tempSensor) المدرجة. قم بتغيير القيم إذا لزم الأمر.

"createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"

على سبيل المثال، يجب أن يكون تكوين عامل التصفية مشابها لما يلي:

"filtermodule": {
"version": "1.0",
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
   "image": "myacr.azurecr.io/filtermodule:0.0.1-amd64",
   "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"
}

إنشاء صورة Docker للوحدة النمطية

افتح المحطة الطرفية المتكاملة ل Visual Studio Code عن طريق تحديد Terminal>New Terminal.

dotnet publish استخدم الأمر لإنشاء صورة الحاوية لبنية Linux وamd64. قم بتغيير الدليل إلى دليل filtermodule في مشروعك وقم بتشغيل الأمر dotnet publish .

dotnet publish --os linux --arch x64 /t:PublishContainer

حاليا، يستهدف قالب أداة iotedgedev .NET 7.0. إذا كنت تريد استهداف إصدار مختلف من .NET، يمكنك تحرير ملف filtermodule.csproj وتغيير قيم TargetFramework و PackageReference . على سبيل المثال لاستهداف .NET 8.0، يجب أن يبدو ملف filtermodule.csproj كما يلي:

<Project Sdk="Microsoft.NET.Sdk.Worker">
    <PropertyGroup>
        <TargetFramework>net8.0</TargetFramework>
        <Nullable>enable</Nullable>
        <ImplicitUsings>enable</ImplicitUsings>
    </PropertyGroup>
    <ItemGroup>
        <PackageReference Include="Microsoft.Azure.Devices.Client" Version="1.42.0" />
        <PackageReference Include="Microsoft.Extensions.Hosting" Version="8.0.0" />
    </ItemGroup>
</Project>

ضع علامة على صورة docker بمعلومات سجل الحاوية والإصدار والهندسة. استبدل myacr باسم السجل الخاص بك.

docker tag filtermodule myacr.azurecr.io/filtermodule:0.0.1-amd64

صورة Docker لوحدة الدفع

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

  1. سجل الدخول إلى Docker باستخدام بيانات اعتماد Azure Container Registry (ACR).

    docker login -u <ACR username> -p <ACR password> <ACR login server>

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

  2. سجّل الدخول إلى Azure Container Registry. تحتاج إلى تثبيت Azure CLI لاستخدام az الأمر . يطلب هذا الأمر العثور على اسم المستخدم وكلمة المرور في سجل الحاوية في مفاتيح الإعدادات> Access.

    az acr login -n <ACR registry name>

    تلميح

    إذا قمت بتسجيل الخروج في أي وقت في هذا البرنامج التعليمي، كرر خطوات تسجيل الدخول Docker وAzure Container Registry للمتابعة.

  3. ادفع صورة الوحدة النمطية إلى السجل المحلي أو سجل الحاوية.

    docker push <ImageName>

    على سبيل المثال:

    # Push the Docker image to the local registry

docker push localhost:5000/filtermodule:0.0.1-amd64

# Or push the Docker image to an Azure Container Registry. Replace myacr with your Azure Container Registry name.

az acr login --name myacr
docker push myacr.azurecr.io/filtermodule:0.0.1-amd64

تحديث قالب التوزيع

تحديث قالب التوزيع deployment.template.json مع موقع صورة سجل الحاوية. على سبيل المثال، إذا كنت تستخدم Azure Container Registry myacr.azurecr.io وصورتك filtermodule :0.0.1-amd64، فقم بتحديث تكوين filtermodule إلى:

"filtermodule": {
    "version": "1.0",
    "type": "docker",
    "status": "running",
    "restartPolicy": "always",
    "settings": {
        "image": "myacr.azurecr.io/filtermodule:0.0.1-amd64",
        "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"
    }
}

في مستكشف VS Code، انقر بزر الماوس الأيمن فوق ملف publish.template.json وحدد إنشاء ودفع حل IoT Edge.

يبدأ أمر الإنشاء والدفع ثلاث عمليات. أولاً، يقوم بإنشاء مجلد جديد في الحل يسمى config والذي يحتوي على بيان النشر الكامل، والذي تم إنشاؤه بناءً على المعلومات الموجودة في قالب النشر وملفات الحل الأخرى. ثانيًا، يقوم بتشغيل docker build لإنشاء صورة الحاوية بناءً على dockerfile المناسب للبنية المستهدفة. بعد ذلك، يتم تشغيل docker push لدفع مستودع الصور إلى سجل الحاوية الخاص بك.

قد تستغرق هذه العملية عدة دقائق في المرة الأولى ولكن أسرع في المرة التالية التي تقوم بتشغيل الأوامر.

اختياري: تحديث الوحدة النمطية والصورة

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

افتح الملف deployment.amd64.json في مجلد التكوين الذي تم إنشاؤه حديثًا. يعكس اسم الملف البنية الهدف، لذلك يكون مختلفا إذا اخترت بنية مختلفة.

لاحظ أن المعلمتين اللتين تحتويان على عناصر نائبة تحتويان الآن على قيمهما المناسبة. يحتوي قسم registryCredentials على اسم مستخدم السجل وكلمة المرور التي تم سحبها من ملف .env . يحتوي filtermodule على مستودع الصور الكامل مع الاسم والإصدار وعلامة البنية من ملف module.json.

  1. افتح ملف module.json في مجلد filtermodule.

  2. تغيير رقم الإصدار لصورة الوحدة النمطية. على سبيل المثال، قم بزيادة رقم إصدار التصحيح إلى "version": "0.0.2" كما لو قمت بإجراء إصلاح صغير في التعليمات البرمجية للوحدة النمطية.

    تلميح

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

  3. احفظ التغييرات التي أجريتها على ملف module.json .

أنشئ الصورة المحدثة وادفعها باستخدام علامة إصدار 0.0.2 . على سبيل المثال، لإنشاء الصورة ودفعها للسجل المحلي أو سجل حاوية Azure، استخدم الأوامر التالية:


# Build the container image for Linux and amd64 architecture.

dotnet publish --os linux --arch x64

# For local registry:
# Tag the image with version 0.0.2, x64 architecture, and the local registry.

docker tag filtermodule localhost:5000/filtermodule:0.0.2-amd64

# For Azure Container Registry:
# Tag the image with version 0.0.2, x64 architecture, and your container registry information. Replace **myacr** with your own registry name.

docker tag filtermodule myacr.azurecr.io/filtermodule:0.0.2-amd64

انقر بزر الماوس الأيمن فوق الملف deployment.template.json مرة أخرى، ثم حدد مرة أخرى إنشاء ودفع حل IoT Edge.

افتح ملف deployment.amd64.json مرة أخرى. لاحظ أن نظام الإنشاء لا ينشئ ملفا جديدا عند تشغيل أمر الإنشاء والدفع مرة أخرى. بدلا من ذلك، يتم تحديث الملف نفسه ليعكس التغييرات. تشير صورة filtermodule الآن إلى الإصدار 0.0.2 من الحاوية.

للتحقق مما فعله الأمر إنشاء ودفع، انتقل إلى مدخل Azure وانتقل إلى سجل الحاوية.

في سجل الحاوية، حدد Repositories ثم filtermodule. تحقق من دفع كلا الإصدارين من الصورة إلى السجل.

Screenshot of where to view both image versions in your container registry.

استكشاف الأخطاء وإصلاحها

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

  • هل قمت بتشغيل الأمر docker login باستخدام بيانات الاعتماد التي قمت بنسخها من سجل الحاوية؟ تختلف بيانات الاعتماد هذه عن تلك التي تستخدمها لتسجيل الدخول إلى Azure.
  • هل مستودع الحاويات الخاص بك صحيح؟ هل له اسم تسجيل حاوية صحيح واسم وحدة صحيح؟ افتح ملف module.json في مجلد filtermodule للتحقق. يجب أن تبدو قيمة المستودع مثل <اسم> السجل.azurecr.io/filtermodule.
  • إذا استخدمت اسما مختلفا عن filtermodule للوحدة النمطية الخاصة بك، هل هذا الاسم متناسق في جميع أنحاء الحل؟
  • هل يعمل جهازك بنفس نوع الحاويات التي تقوم ببنائها؟ هذا البرنامج التعليمي هو لأجهزة لينكس IoT الحافة، لذلك Visual Studio Code يجب أن يظهر فيه amd64 أو arm32v7 في الشريط الجانبي، وينبغي أن يقوم Docker Desktop بتشغيل حاويات Linux.

نشر الوحدات النمطية على الجهاز

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

استخدم الأمر IoT Edge Azure CLI set-modules لنشر الوحدات النمطية إلى Azure IoT Hub. على سبيل المثال، لنشر الوحدات النمطية المحددة في ملف deployment.template.json إلى IoT Hub my-iot-hub لجهاز IoT Edge لجهازي، استخدم الأمر التالي. استبدل قيم اسم المركز ومعرف الجهاز وتسجيل الدخول سلسلة الاتصال IoT Hub بخاصيتك.

az iot edge set-modules --hub-name my-iot-hub --device-id my-device --content ./deployment.template.json --login "HostName=my-iot-hub.azure-devices.net;SharedAccessKeyName=iothubowner;SharedAccessKey=<SharedAccessKey>"

تلميح

يمكنك العثور على سلسلة الاتصال IoT Hub بما في ذلك مفتاح الوصول المشترك في مدخل Microsoft Azure. انتقل إلى إعدادات>أمان مركز IoT> نهج الوصول>المشترك iothubowner.

  1. في مستكشف Visual Studio Code، ضمن قسم Azure IoT Hub، قم بتوسيع Devices لمشاهدة قائمة أجهزة IoT الخاصة بك.

  2. انقر بزر الماوس الأيمن فوق جهاز IoT Edge الذي تريد النشر إليه،‏ ثم حدد إنشاء نشر لجهاز واحد.

  3. في مستكشف الملفات، انتقل إلى مجلد التكوين ثم حدد الملف deployment.amd64.json.

    لا تستخدم ملف deployment.template.json، الذي لا يحتوي على بيانات اعتماد سجل الحاوية أو قيم صورة الوحدة النمطية فيه. إذا كنت تستهدف جهاز Linux ARM32، يتم deployment.arm32v7.json اسم بيان التوزيع.

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

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

عرض الرسائل من الجهاز

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

  1. في مستكشف Visual Studio Code، انقر بزر الماوس الأيمن فوق اسم جهاز IoT Edge وحدد ⁧⁩بدء مراقبة نقطة نهاية الحدث المضمنة⁩.

  2. شاهد نافذة الإخراج في Visual Studio Code لمشاهدة الرسائل التي تصل إلى مركز IoT.

    Screenshot showing where to view incoming device to cloud messages.

عرض التغييرات على الجهاز

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

الأوامر الموجودة في هذا القسم هي لجهاز IoT Edge، وليس لجهاز التطوير الخاص بك. إذا كنت تستخدم جهازًا افتراضيًا لجهاز IoT Edge، فاتصل به الآن. في Azure، انتقل إلى صفحة نظرة عامة على الجهاز الظاهري وحدد الاتصال للوصول إلى اتصال shell الآمن.

  • عرض جميع الوحدات النمطية المنشورة على جهازك، والتحقق من حالتها:

    iotedge list

    يجب أن تشاهد أربع وحدات نمطية: وحدتي وقت تشغيل IoT Edge، tempSensor، و filtermodule. يجب أن ترى جميع الأربعة مدرجة على أنها قيد التشغيل.

  • فحص السجلات لوحدة نمطية معينة:

    iotedge logs <module name>

    وحدات IoT Edge حساسة لحالة الأحرف.

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

تنظيف الموارد

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

غير ذلك يمكنك حذف التكوينات المحلية وموارد Azure التي استخدمتها في هذه المقالة لتجنب التكاليف.

قم بحذف موارد Azure.

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

لحذف الموارد:

  1. سجل الدخول إلى مدخل Azure، وحدد "Resource groups".

  2. حدد اسم مجموعة الموارد التي تحتوي على موارد اختبار IoT Edge.

  3. راجع قائمة الموارد الموجودة في مجموعة الموارد الخاصة بك. إذا كنت تريد حذفها جميعاً، يمكنك تحديد Delete resource group. إذا كنت تريد حذف بعضها فقط، فيمكنك النقر فوق كل مورد لحذفها بشكل فردي.

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

في هذا البرنامج التعليمي، قمت بإعداد Visual Studio Code على جهاز التطوير الخاص بك ونشر أول وحدة IoT Edge تحتوي على تعليمة برمجية لتصفية البيانات الأولية التي تم إنشاؤها بواسطة جهاز IoT Edge.

يمكنك متابعة الدروس التالية لمعرفة كيف يمكن أن تساعدك Azure IoT Edge في نشر خدمات سحابة Azure لمعالجة البيانات وتحليلها على الحافة.

تصحيح أخطاء وحدات Azure IoT Edge النمطيةوظائف Stream AnalyticsCustom Vision Service