تعلم كيفية نشر الوحدات وإنشاء المسارات في IoT Edge

ينطبق على: IoT Edge 1.5

هام

IoT Edge 1.5 LTS هو الإصدار المدعوم release. وصل IoT Edge 1.4 LTS إلى نهاية صلاحيته في 12 نوفمبر 2024. إذا كنت تستخدم إصدارا أقدم، راجع Update IoT Edge.

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

بيان التوزيع هو مستند JSON يصف:

• وحدة IoT Edge التوأم ، والتي تتكون من ثلاثة مكونات:
  • صورة الحاوية لكل وحدة تعمل على الجهاز.
  • بيانات الاعتماد لاستخدام سجلات الحاويات الخاصة التي تحتوي على صور وحدات.
  • تعليمات حول كيفية إنشاء وإدارة كل وحدة.
• وحدة IoT Edge المحورية التوأم، والتي تشمل كيفية تدفق الرسائل بين الوحدات وإلى IoT Hub.
• الخصائص المرغوبة لأي توأم وحدة إضافي (اختياري).

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

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

القيام بإنشاء بيان نشر

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

يتطلب كل بيان نشر وحدتين نمطيتين: $edgeAgent و $edgeHub. هذه الوحدات جزء من وقت تشغيل IoT Edge الذي يدير جهاز IoT Edge والوحدات التي تعمل عليه. لمزيد من المعلومات حول هذه الوحدات، راجع فهم وقت تشغيل IoT Edge وبنيتها.

يمكنك إضافة ما يصل إلى 50 وحدة إضافية لتشغيلها على جهاز IoT Edge، بالإضافة إلى وحدتي التشغيل.

ملف النشر الذي يحتوي فقط على وقت تشغيل IoT Edge ($edgeAgent و $edgeHub) صالح.

تستخدم قوائم النشر هذا التنسيق:

{
  "modulesContent": {
    "$edgeAgent": { // required
      "properties.desired": {
        // desired properties of the IoT Edge agent
        // includes the image URIs of all deployed modules
        // includes container registry credentials
      }
    },
    "$edgeHub": { //required
      "properties.desired": {
        // desired properties of the IoT Edge hub
        // includes the routing information between modules and to IoT Hub
      }
    },
    "module1": {  // optional
      "properties.desired": {
        // desired properties of module1
      }
    },
    "module2": {  // optional
      "properties.desired": {
        // desired properties of module2
      }
    }
  }
}

تكوين وحدات نمطية

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

تستخدم الخصائص $edgeAgent هذا التنسيق:

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": {
          "settings":{
            "registryCredentials":{
              // let the IoT Edge agent use container images that aren't public
            }
          }
        },
        "systemModules": {
          "edgeAgent": {
            // configuration and management details
          },
          "edgeHub": {
            // configuration and management details
          }
        },
        "modules": {
          "module1": {
            // configuration and management details
          },
          "module2": {
            // configuration and management details
          }
        }
      }
    },
    "$edgeHub": { ... },
    "module1": { ... },
    "module2": { ... }
  }
}

تم إصدار مخطط وكيل IoT Edge إصدار 1.1 مع إصدار IoT Edge 1.0.10 ويتيح لك تعيين ترتيب بدء تشغيل الوحدات. استخدم الإصدار 1.1 من المخطط لأي نشر IoT Edge يعمل بالإصدار 1.0.10 أو أحدث.

تكوين الوحدة وإدارتها

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

للحصول على قائمة كاملة بالخصائص المرغوبة التي يمكنك أو يجب تضمينها، راجع خصائص وكيل IoT Edge ومركز IoT Edge.

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

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": { ... },
        "systemModules": {
          "edgeAgent": { ... },
          "edgeHub": { ... }
        },
        "modules": {
          "module1": {
            "version": "1.0",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 2,
            "settings": {
              "image": "myacr.azurecr.io/module1:latest",
              "createOptions": "{}"
            }
          },
          "module2": { ... }
        }
      }
    },
    "$edgeHub": { ... },
    "module1": { ... },
    "module2": { ... }
  }
}

تحتوي كل وحدة نمطية على خاصية إعدادات مع صورة الوحدة النمطية وعنوان لصورة الحاوية في سجل حاوية وأي createOptions لإعداد الصورة عند بدء التشغيل. لمزيد من المعلومات، راجع كيفية تكوين خيارات إنشاء الحاويات ل IoT Edge module.

تحتوي وحدة edgeHub والوحدات المخصصة أيضا على ثلاث خصائص تخبر وكيل IoT Edge بكيفية إدارتها:

• الحالة: سواء تم تشغيل الوحدة النمطية أو إيقافها عند نشرها لأول مرة. مطلوب.

• RestartPolicy: متى وإذا كان وكيل IoT Edge يعيد تشغيل الوحدة إذا توقفت. إذا توقفت الوحدة دون أي أخطاء، فلن تعيد التشغيل تلقائيا. لمزيد من المعلومات، راجع Docker Docs - بدء تشغيل الحاويات تلقائيا. مطلوب.

• StartupOrder: تم تقديمه في الإصدار IoT Edge 1.0.10. الترتيب الذي يستخدمه وكيل IoT Edge لبدء تشغيل الوحدات عند نشرها لأول مرة. يستخدم الترتيب أعدادا صحيحة، حيث تبدأ الوحدة النمطية بقيمة بدء التشغيل 0 أولا ثم تتبعها أرقام أعلى. وحدة $edgeAgent لا تحتوي على قيمة بدء التشغيل لأنها دائما تبدأ أولا. اختياري.

  يقوم وكيل IoT Edge ببدء الوحدات حسب قيمة بدء التشغيل، لكنه لا ينتظر حتى تنتهي كل وحدة من البدء قبل أن يبدأ التالية.

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

  إشعار

  يؤدي تغيير خصائص الوحدة النمطية إلى إعادة تشغيل هذه الوحدة النمطية. على سبيل المثال، تحدث إعادة التشغيل إذا قمت بتغيير خصائص:

  • صورة الوحدة النمطية
  • خيارات إنشاء Docker
  • متغيرات البيئة
  • إعادة تشغيل النهج
  • نهج سحب الصور
  • إصدار
  • أمر بدء التشغيل

  إذا لم تغير أي خصائص للوحدة، فلن يتم تفعيل إعادة تشغيل الوحدة.

إعلان المسارات

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

قم بتعريف المسارات في $edgeHub الخصائص المطلوبة باستخدام بناء الجملة هذا:

{
  "modulesContent": {
    "$edgeAgent": { ... },
    "$edgeHub": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "routes": {
          "route1": "FROM <source> WHERE <condition> INTO <sink>",
          "route2": {
            "route": "FROM <source> WHERE <condition> INTO <sink>",
            "priority": 0,
            "timeToLiveSecs": 86400
          }
        },
        "storeAndForwardConfiguration": {
          "timeToLiveSecs": 10
        }
      }
    },
    "module1": { ... },
    "module2": { ... }
  }
}

تم إصدار مخطط مركز IoT Edge الإصدار الأول مع إصدار IoT Edge 1.0.10 ويتيح لك تعيين أولوية المسارات ووقت العيش. استخدم الإصدار 1.1 من المخطط لأي نشر IoT Edge يعمل بالإصدار 1.0.10 أو أحدث.

يحتاج كل مسار إلى مصدر للرسائل الواردة ومتلقي للرسائل الصادرة. الشرط اختياري ويسمح لك بتصفية الرسائل.

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

المصدر

يقوم المصدر بتحديد مصدر الرسائل. يمكن ل IoT Edge توجيه الرسائل من الوحدات أو الأجهزة اللاحقة.

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

يمكن للخاصية المصدر استخدام أي من هذه القيم:

المصدر	‏‏الوصف
/*	جميع رسائل الجهاز إلى السحابة أو إشعارات التغيير المزدوجة من أي وحدة أو جهاز لاحق.
/twinChangeNotifications	أي تغيير توأم (خصائص مبلغ عنها) يأتي من أي وحدة أو جهاز في المراحل النهائية.
/messages/*	أي رسالة من الجهاز إلى السحابة ترسل بواسطة وحدة عبر بعض المخرجات أو لا ترسل من خلال أي مخرجات، أو من جهاز لاحق.
/messages/modules/*	أي رسالة من الجهاز إلى السحابة ترسل بواسطة وحدة عبر بعض المخرجات أو لا مخرجات.
/messages/modules/<moduleId>/*	أي رسالة من الجهاز إلى السحابة ترسل بواسطة وحدة معينة عبر بعض أو بدون مخرجات.
/messages/modules/<moduleId>/outputs/*	أي رسالة من جهاز إلى سحابة يتم إرسالها بواسطة وحدة معينة عبر مخرجات معينة.
/messages/modules/<moduleId>/outputs/<output>	أي رسالة من جهاز إلى سحابة ترسل بواسطة وحدة معينة عبر مخرج معين.

الشرط

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

الرسائل التي تنتقل بين الوحدات في IoT Edge تستخدم نفس تنسيق الرسائل بين أجهزتك وAzure IoT Hub. تستخدم جميع الرسائل تنسيق JSON وامتلكت خصائص النظام و appProperties ومعلمات النص الأساسي .

قم ببناء الاستعلامات حول أي من المعلمات الثلاثة باستخدام هذا الصياغة:

• خصائص نظام: $<propertyName> أو {$<propertyName>}
• خصائص التطبيق: <propertyName>
• خصائص الجسم: $body.<propertyName>

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

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

FROM /messages/* WHERE NOT IS_DEFINED($connectionModuleId) INTO $upstream

المتلقي

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

يمكن لخاصية المتلقي استخدام أي من هذه القيم:

المتلقي	‏‏الوصف
$upstream	أرسل الرسالة إلى IoT Hub
BrokeredEndpoint("/modules/<moduleId>/inputs/<input>")	إرسال الرسالة إلى إدخال معين لوحدة نمطية معينة

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

يخزن IoT Edge المركز الرسائل حتى الوقت المعين في خاصية storeAndForwardConfiguration.timeToLiveSecs في خصائص IoT Edge التي يرغب بها.

الأولوية ووقت البقاء

قم بتعريف المسارات كسلسلة تعرف المسار، أو ككائن مع سلسلة توجيه، وعدد صحيح للأولوية، وعدد صحيح لفترة البقاء.

خيار 1

"route1": "FROM <source> WHERE <condition> INTO <sink>",

الخيار 2 (تم تقديمه في إصدار IoT Edge 1.0.10 مع مخطط مركز IoT Edge إصدار 1.1)

"route2": {
  "route": "FROM <source> WHERE <condition> INTO <sink>",
  "priority": 0,
  "timeToLiveSecs": 86400
}

تتراوح قيم الأولوية من 0 إلى 9، حيث تكون القيمة 0 هي الأولوية القصوى. يقوم النظام بترتيب الرسائل حسب نقاط نهايتها. يعالج النظام جميع رسائل الأولوية 0 لنقطة نهاية معينة قبل أن يعالج أي رسائل ذات أولوية 1 لنفس نقطة النهاية. إذا كانت عدة مسارات لنفس نقطة النهاية لها نفس الأولوية، يعالج النظام الرسائل حسب ترتيب وصولها. إذا لم تقم بتعيين أولوية، فإن المسار يستخدم أقل أولوية.

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

للمزيد من التفاصيل حول كيفية إدارة قوائم الانتظار ذات الأولوية، راجع Route Priority وtime-to-live.

تحديد أو تحديث الخصائص المطلوبة

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

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

نفس الآليات التي تتيح لك تغيير توائم الجهاز تتيح لك أيضا تغيير توائم الوحدة النمطية. لمزيد من المعلومات، راجع دليل المطور المزدوج للوحدة النمطية.

مثال بيان التوزيع

يوضح المثال التالي كيف يمكن أن يبدو مستند بيان التوزيع الصالح.

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": {
          "type": "docker",
          "settings": {
            "minDockerVersion": "v1.25",
            "loggingOptions": "",
            "registryCredentials": {
              "ContosoRegistry": {
                "username": "myacr",
                "password": "<password>",
                "address": "myacr.azurecr.io"
              }
            }
          }
        },
        "systemModules": {
          "edgeAgent": {
            "type": "docker",
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-agent:1.5",
              "createOptions": "{}"
            }
          },
          "edgeHub": {
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 0,
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
              "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"443/tcp\":[{\"HostPort\":\"443\"}],\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}]}}}"
            }
          }
        },
        "modules": {
          "SimulatedTemperatureSensor": {
            "version": "1.5",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 2,
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.5",
              "createOptions": "{}"
            }
          },
          "filtermodule": {
            "version": "1.0",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 1,
            "env": {
              "tempLimit": {"value": "100"}
            },
            "settings": {
              "image": "myacr.azurecr.io/filtermodule:latest",
              "createOptions": "{}"
            }
          }
        }
      }
    },
    "$edgeHub": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "routes": {
          "sensorToFilter": {
            "route": "FROM /messages/modules/SimulatedTemperatureSensor/outputs/temperatureOutput INTO BrokeredEndpoint(\"/modules/filtermodule/inputs/input1\")",
            "priority": 0,
            "timeToLiveSecs": 1800
          },
          "filterToIoTHub": {
            "route": "FROM /messages/modules/filtermodule/outputs/output1 INTO $upstream",
            "priority": 1,
            "timeToLiveSecs": 1800
          }
        },
        "storeAndForwardConfiguration": {
          "timeToLiveSecs": 100
        }
      }
    }
  }
}

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

• للحصول على قائمة كاملة بالخصائص التي يمكنك أو يجب تضمينها في $edgeAgent و $edgeHub، انظر خصائص وكيل IoT Edge و IoT Edge hub.
• الآن بعد أن عرفت كيف تعمل IoT Edge الوحدات، تعلم عن المتطلبات والأدوات لتطوير وحدات IoT Edge.