إثراء رسائل IoT Hub من الجهاز إلى السحابة
إثراء الرسائل هي قدرة مركز IoT على ختم الرسائل بمعلومات إضافية قبل إرسال الرسائل إلى نقطة النهاية المحدّدة. من أسباب استخدام إثراء الرسائل هو تضمين البيانات التي يمكن استخدامها لتبسيط معالجة انتقال البيانات من الخادم. على سبيل المثال، يمكن أن يؤدي إثراء رسائل تتبع القياس عن بُعد للجهاز بعلامة مزدوجة على الجهاز إلى تقليل الحمل على العملاء لإجراء مكالمات API المزدوجة للجهاز للحصول على هذه المعلومات.
يتضمن إثراء الرسائل ثلاثة عناصر رئيسية:
اسم الإثراء أو مفتاحه
قيمة
نقطة نهاية واحدة أو أكثر ينبغي تطبيق الإثراء عليها.
إن المفتاحَ سلسلةٌ. يمكن أن يحتوي المفتاح على أحرف أبجدية أو على هذه الرموز المميزة فقط: الواصلة (-)، الشرطة السفلية (_)، والنقطة (.).
قد تكون القيمة أي من الأمثلة التالية:
أي سلسلة ثابتة. لا يُسمح بالقيم الديناميكية مثل الشروط، والمنطق، والعمليات، والدالات. على سبيل المثال، إذا قمت بتطوير تطبيق SaaS الذي يستخدمه العديد من العملاء، يمكنك تعيين مُعرّف لكل عميل وتوفير هذا المعرف في التطبيق. عند تشغيل التطبيق، سيقوم IoT Hub بختم رسائل بيانات تتبع الاستخدام للجهاز بمعرف العميل، مما يجعل معالجة الرسائل أمرًا ممكنًا تختلف من عميل لآخر.
اسم مركز IoT المُرسل للرسالة. إن هذه القيمة هي $iothubname.
معلومات من توأم الجهاز، مثل مساره. ومن الأمثلة على ذلك ستكون $twin.tags.field و $twin.tags.latitude.
ملاحظة
في هذا الوقت، $iothubname فقط، و$twin.tags، و$twin.properties.desired، و$twin.properties هي متغيرات مدعومة لإثراء الرسائل. بالإضافة إلى ذلك، يتم دعم الأنواع الأولية فقط للإثراء. لا يمكن إثراء الرسائل مع أنواع العناصر.
تتم إضافة عمليات إثراء الرسائل كخصائص التطبيق إلى الرسائل المرسلة إلى نقطة النهاية (نقاط النهاية) المُختارة.
تطبيق عمليات الإثراء
يمكن أن تأتي الرسائل من أي مصدر بيانات مدعوم من توجيه رسائل مركز IoT، بما في ذلك الأمثلة التالية:
- بيانات تتبع الاستخدام للجهاز، مثل درجة الحرارة أو الضغط
- إعلامات تغيير الجهاز التوأم -- التغييرات في الجهاز التوأم
- أحداث دورة حياة الجهاز، مثل وقت إنشاء الجهاز أو إزالته
يمكنك إضافة عمليات الإثراء إلى الرسائل التي تنتقل إلى نقطة النهاية المُضمّنة من مركز IoT، أو الرسائل التي يتم توجيهها إلى نقاط النهاية المخصصة مثل تخزين Azure Blob، أو قائمة Service Bus، أو موضوع Service Bus.
يمكنك أيضًا إضافة عمليات الإثراء إلى الرسائل التي يتم نشرها إلى Event Grid عن طريق إنشاء اشتراك Event Grid أولاً باستخدام نوع رسالة بيانات تتبع الاستخدام للجهاز. بناء على هذا الاشتراك، سنُنشئ مسارًا افتراضيًا في Azure IoT Hub لبيانات تتبع الاستخدام. يمكن لهذا المسار الفردي التعامل مع جميع اشتراكات Event Grid. يمكنك بعد ذلك تكوين عمليات الإثراء لنقطة النهاية باستخدام علامة التبويب إثراء الرسائل في قسم توجيه رسائل مركز IoT. للحصول على معلومات حول التفاعل مع الأحداث باستخدام Event Grid، راجع Iot Hub و Event Grid.
يتم تطبيق عمليات الإثراء في كل نقطة نهاية. إذا قمت بتحديد خمسة عمليات إثراء لختمها في نقطة نهاية محددة، يتم ختم جميع الرسائل التي تنتقل إلى هذه النقطة بعمليات الإثراء الخمسة نفسها.
يمكن تكوين عمليات الإثراء باستخدام الطرق التالية:
| الأسلوب | الأمر |
|---|---|
| المدخل | مدخل Microsoft Azure راجع البرنامج التعليمي لإثراء الرسائل |
| Azure CLI | إثراء رسائل az iot |
| Azure PowerShell | Add-AzIotHubMessageEnrichment |
لا تؤدي إضافة إثراء الرسائل إلى إضافة زمن انتقال إلى توجيه الرسائل.
لتجربة عمليات إثراء الرسائل، راجع البرنامج التعليمي لإثراء الرسائل
التقييدات
يمكنك إضافة ما يصل إلى 10 عمليات إثراء لكل مركز IoT من هذه المراكز في المستوى القياسي أو الأساسي. بالنسبة لمراكز IoT في المستوى المجاني، يمكنك إضافة ما يصل إلى عمليتي إثراء.
في بعض الحالات، إذا كنت تقوم بإثراء رسالة بقيمة معينة إلى علامة أو خاصية في توأم الجهاز، فسيتم ختم القيمة بمسار الجهاز التوأم المحدد. على سبيل المثال، إذا تم تعيين قيمة الإثراء إلى $twin.tags.field، فسيتم ختم الرسائل بالسلسلة "$twin.tags.field"، بدلاً من قيمة هذا الحقل من التوأم. يحدث ذلك السلوك في الحالات التالية:
إن مركز IoT الخاص بك في المستوى الأساسي. لا يدعم المستوى الأساسي من مراكز IoT توائم الجهاز.
إن مركز IoT الخاص بك في المستوى القياسي، ولكن لا يوجد مسار توأم الجهاز المُستخدَم في قيمة الإثراء. على سبيل المثال، إذا تم تعيين قيمة الإثراء إلى $twin.tags.location، ولم يكن لدى الجهاز التوأم خاصية ضمن العلامات، يتم ختم الرسالة بالسلسلة "$twin.tags.location".
إن مستوى مركز IoT الخاص بك في المستوى القياسي، ولكن مسار الجهاز التوأم المستخدم لقيمة الإثراء يحل إلى عنصر، بدلاً من خاصية بسيطة. على سبيل المثال، إذا تم تعيين قيمة الإثراء إلى $twin.tags.location، وكانت خاصية الموقع ضمن العلامات عنصر يحتوي على خصائص فرعية تابعة مثل
{"building": 43, "room": 503}، يتم ختم الرسالة بالسلسلة "$twin.tags.location".
يمكن أن تستغرق تحديثات توأم الجهاز ما يصل إلى خمس دقائق ليتم عكسها في قيمة الإثراء المتوافقة.
لا يمكن أن يتجاوز إجمالي حجم الرسالة، بما في ذلك عمليات الإثراء، حجم 256 كيلوبايت. إذا تجاوز حجم الرسالة 256 كيلو بايت، فسيقوم مركز IoT بإسقاط الرسالة. يمكنك استخدام مقاييس مركز IoT لتحديد الأخطاء وتصحيحها وتتبعها عند إسقاط الرسائل. على سبيل المثال، يمكنك مراقبة مقياس رسائل بيانات تتبع الاستخدام غير المتوافقة (d2c.telemetry.egress.invalid) في مقاييس التوجيه. للتعرّف على المزيد، راجع مركز Monitor IoT.
لا تنطبق عمليات إثراء الرسائل على أحداث تغيير التوأم الرقمية.
لا تنقل الوحدات النمطية العلامات المزدوجة من أجهزتها المقابلة. يجب أن تستخدم عمليات إثراء الرسائل التي تنشأ من وحدات الجهاز النمطية (على سبيل المثال من وحدات IoT Edge) العلامات المزدوجة التي تم تعيينها على الوحدة النمطية المزدوجة.
التسعير
تتوفّر عمليات إثراء الرسائل دون أي تكلفة إضافية. حاليًا، تُفرض عليك رسوم عند إرسال رسالة إلى أي مركز من مراكز IoT. تُفرض عليك رسوم مرة واحدة فقط مقابل هذه الرسالة، وإن كانت الرسالة تنتقل إلى نقاط نهاية متعددة.
الخطوات التالية
تفقَّد هذه المقالات لمزيد من المعلومات حول توجيه الرسائل إلى مركز IoT: