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

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

هام

IoT Edge 1.4 هو الإصدار المدعوم. إذا كنت تستخدم إصدارا سابقا، فشاهد تحديث 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":{
              // 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 جنبا إلى جنب مع إصدار 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": { ... }
  }
}

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

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

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

Source

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

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

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

Source	‏‏الوصف
/*	جميع الرسائل من جهاز إلى سحابة أو إعلامات التغيير المزدوج من أي وحدة نمطية أو جهاز انتقال البيانات من الخادم
/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

المتلقي

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

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

المتلقي	‏‏الوصف
$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 EdgeالتكوينAndForwardConfiguration ما لم يتم تعيينه بشكل صريح. يمكن أن يكون ناتج القيمة أي عدد صحيح موجب.

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

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

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

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

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

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