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

ينطبق على:IoT Edge 1.4 علامة اختيار IoT Edge 1.4

يعمل كل جهاز 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 أو SDK لخدمة 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":{
              // give the IoT Edge agent access to 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 جنبا إلى جنب مع الإصدار 1.0.10 من IoT Edge، وتمكين طلب بدء تشغيل الوحدة النمطية. يوصى باستخدام إصدار المخطط 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
    • متغيرات البيئة
    • نهج إعادة التشغيل
    • نهج سحب الصور
    • version
    • طلب بدء التشغيل

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

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

يدير مركز IoT Edge الاتصال بين الوحدات النمطية ومركز IoT وأي أجهزة انتقال البيانات من الخادم. لذلك، تحتوي الوحدة النمطية المزدوجة $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>

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

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

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

Sink

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

يمكن أن تكون الخاصية المتلقي أي من القيم التالية:

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

تزود IoT Edge ضمانات مرة واحدة على الأقل. يقوم محور IoT Edge بتخزين الرسائل محليا في حالة عدم تمكن المسار من توصيل الرسالة إلى حوضه. على سبيل المثال، إذا كان IoT Edge hub لا يمكنه الاتصال بـ 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.4",
              "createOptions": "{}"
            }
          },
          "edgeHub": {
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 0,
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-hub:1.4",
              "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"443/tcp\":[{\"HostPort\":\"443\"}],\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}]}}}"
            }
          }
        },
        "modules": {
          "SimulatedTemperatureSensor": {
            "version": "1.0",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 2,
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0",
              "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
        }
      }
    }
  }
}

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