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

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

هام

IoT Edge 1.5 LTS هو الإصدار المدعوم. IoT Edge 1.4 LTS هو نهاية العمر الافتراضي اعتبارا من 12 نوفمبر 2024. إذا كنت تستخدم إصدارا سابقا، فشاهد تحديث 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 Service SDK. لمزيد من المعلومات، راجع فهم عمليات توزيع 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 النمطية.

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

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

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

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

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

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

  إشعار

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

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

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

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

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

قم بتعريف المسارات في $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 1 مع الإصدار 1.0.10 من IoT Edge ويتيح لك تعيين ترتيب أولويات المسار ووقت البقاء. استخدم الإصدار 1.1 من المخطط لأي نشر IoT Edge يعمل بالإصدار 1.0.10 أو أحدث.

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

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

المصدر

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

باستخدام IoT SDKs، يمكن للوحدات النمطية تعيين قوائم انتظار إخراج معينة لرسائلها باستخدام فئة ModuleClient. قوائم انتظار الإخراج غير مطلوبة، ولكنها تساعد في إدارة مسارات متعددة. تستخدم أجهزة انتقال البيانات من الخادم فئة DeviceClient في IoT SDKs لإرسال رسائل إلى أجهزة بوابة 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 (المقدم في الإصدار 1.0.10 من IoT Edge مع إصدار مخطط مركز IoT Edge 1.1)

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

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

تستخدم الخاصية timeToLiveSecs القيمة من مخزن مركز IoT EdgeAndForwardConfiguration ما لم تقم بتعيينها مباشرة. يمكن أن يكون ناتج القيمة أي عدد صحيح موجب.

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

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

يعين بيان التوزيع الخصائص المطلوبة لكل وحدة نمطية تم نشرها على جهاز 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.

• الآن بعد أن عرفت كيفية عمل وحدات IoT Edge، تعرف على متطلبات وأدوات تطوير وحدات IoT Edge.