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