تعرف على كيفية نشر الوحدات النمطية وإنشاء مسارات في IoT Edge
ينطبق على:
IoT Edge 1.1 IoT Edge 1.2
يقوم كل جهاز من أجهزة 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": { ... }
}
}
تحتوي كل وحدة نمطية على خاصية إعدادات تحتوي على صورة الوحدة النمطية وعنوان لصورة الحاوية في سجل حاوية وأي خيارات إنشاء لتكوين الصورة عند بدء التشغيل. لمزيد من المعلومات، راجع كيفية تكوين خيارات إنشاء حاوية لوحدات IoT Edge النمطية.
تحتوي وحدة edgeHub النمطية والوحدات المخصصة أيضا على ثلاث خصائص تخبر وكيل IoT Edge بكيفية إدارتها:
الحالة: ما إذا كان يجب تشغيل الوحدة النمطية أو إيقافها عند نشرها لأول مرة. مطلوب
RestartPolicy: متى وإذا كان يجب على عامل IoT Edge إعادة تشغيل الوحدة النمطية إذا توقفت. إذا تم إيقاف الوحدة النمطية دون أي أخطاء، فلن تبدأ تلقائيا. لمزيد من المعلومات، راجع مستندات Docker - بدء الحاويات تلقائيا. مطلوب
StartupOrder: تم تقديمه في الإصدار 1.0.10 من IoT Edge. الترتيب الذي يجب أن يبدأ به عامل IoT Edge الوحدات النمطية عند نشرها لأول مرة. يتم الإعلان عن الأمر باستخدام أعداد صحيحة ، حيث يتم بدء تشغيل وحدة نمطية بقيمة بدء تشغيل 0 أولا ثم تتبع الأرقام الأعلى. لا تحتوي الوحدة النمطية edgeAgent على قيمة بدء تشغيل لأنها تبدأ دائما أولا. اختياري.
يبدأ وكيل IoT Edge الوحدات بترتيب قيمة بدء التشغيل ، ولكنه لا ينتظر حتى تنتهي كل وحدة من الوحدات قبل الانتقال إلى الوحدة التالية.
يكون أمر بدء التشغيل مفيدا إذا كانت بعض الوحدات تعتمد على وحدات أخرى. على سبيل المثال، قد ترغب في أن تبدأ الوحدة النمطية edgeHub أولا بحيث تكون جاهزة لتوجيه الرسائل عند بدء تشغيل الوحدات النمطية الأخرى. أو قد ترغب في بدء تشغيل وحدة تخزين قبل الوحدات النمطية التي ترسل البيانات إليها. ومع ذلك ، يجب عليك دائما تصميم وحداتك النمطية للتعامل مع فشل الوحدات الأخرى. إنها طبيعة الحاويات التي قد تتوقف وتعيد تشغيلها في أي وقت ، وأي عدد من المرات.
إعلان المسارات
يدير 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 جنبا إلى جنب مع الإصدار 1.0.10 من IoT Edge ، ويتيح تحديد أولويات المسار ووقت العيش. يوصى بالإصدار 1.1 من المخطط لأي عملية نشر IoT Edge تعمل بالإصدار 1.0.10 أو إصدار أحدث.
يحتاج كل مسار إلى مصدر تأتي منه الرسائل ومغسلة حيث تذهب الرسائل. الشرط عبارة عن جزء اختياري يمكنك استخدامه لتصفية الرسائل.
يمكنك تعيين الأولوية للمسارات التي تريد التأكد من معالجة رسائلها أولا. هذه الميزة مفيدة في السيناريوهات التي يكون فيها اتصال المنبع ضعيفا أو محدودا ولديك بيانات مهمة يجب أن تكون لها الأولوية على رسائل القياس عن بعد القياسية.
المصدر
يقوم المصدر بتحديد مصدر الرسائل. يمكن لـ IoT Edge توجيه الرسائل من الوحدات النمطية أو الأجهزة الطرفية.
باستخدام IoT SDKs، يمكن للوحدات النمطية إعلان قوائم انتظار الإخراج المحددة لرسائلها باستخدام فئة ModuleClient. لا تعد قوائم انتظار الإخراج ضرورية، ولكنها مفيدة لإدارة مسارات متعددة. يمكن لأجهزة Leaf استخدام فئة DeviceClient من IoT SDKs لإرسال رسائل إلى أجهزة بوابة IoT Edge بنفس الطريقة التي ترسل بها الرسائل إلى IoT Hub. لمزيد من المعلومات، راجع فهم مجموعات تطوير البرامج (SDKs) لمركز Azure IoT Hub واستخدامها.
يمكن أن تكون خاصية المصدر أيا من القيم التالية:
| المصدر | الوصف |
|---|---|
/* |
جميع الرسائل من الجهاز إلى السحابة أو إشعارات التغيير المزدوجة من أي وحدة نمطية أو جهاز ورقي |
/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 وتحتوي على systemProperties و 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 مع الإصدار 1.1 من مخطط محور IoT Edge:
"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.1",
"createOptions": "{}"
}
},
"edgeHub": {
"type": "docker",
"status": "running",
"restartPolicy": "always",
"startupOrder": 0,
"settings": {
"image": "mcr.microsoft.com/azureiotedge-hub:1.1",
"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.