البرنامج التعليمي: استخدام إثراء رسائل Azure IoT Hub

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

في الجزء الأول من هذا البرنامج التعليمي، رأيت كيفية إنشاء نقاط نهاية مخصصة وتوجيه الرسائل إلى خدمات Azure الأخرى. في هذا البرنامج التعليمي، سترى كيفية إنشاء وتكوين الموارد الإضافية اللازمة لاختبار تحسينات الرسائل لمركز إنترنت الأشياء. تتضمن الموارد حاوية تخزين ثانية لحساب تخزين موجود (تم إنشاؤه في الجزء الأول من البرنامج التعليمي) للاحتفاظ بالرسائل المخصّصة ومسار رسالة لإرسالها هناك. بعد الانتهاء من التكوينات الخاصة بتوجيه الرسائل وإثراء الرسائل، يمكنك استخدام تطبيق لإرسال الرسائل إلى مركز IoT. ثم يقوم المركز بتوجيهها إلى كل من حاويتي التخزين. يتم إثراء الرسائل المرسلة إلى نقطة النهاية لحاوية التخزين التي تم إثراؤها فقط.

في هذا البرنامج التعليمي، تنفذ المهام التالية:

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

المتطلبات الأساسية

• لديك اشتراك Azure. في حال لم يكن لديك اشتراك Azure، فأنشئ حساباً مجانيّاً قبل البدء.

• يجب أن تكون قد أكملت البرنامج التعليمي: إرسال بيانات الجهاز إلى Azure Storage باستخدام توجيه رسالة IoT Hub والحفاظ على الموارد التي أنشأتها له.

• تأكد من أن المنفذ 8883 مفتوح في جدار الحماية. يستخدم نموذج الجهاز في هذا البرنامج التعليمي بروتوكول MQTT، الذي يتصل عبر المنفذ 8883. قد يُحظر هذا المنفذ في بعض بيئات الشبكات التعليمية، وشبكات الشركات. لمزيد من المعلومات وطرق التغلب على هذه المشكلة، راجع الاتصال بمركز IoT (MQTT).

مدخل Microsoft Azure

لا توجد متطلبات أساسية أخرى لمدخل Microsoft Azure.

Azure CLI

• استخدم بيئة Bash في Azure Cloud Shell. لمزيد من المعلومات، راجع التشغيل السريع ل Bash في Azure Cloud Shell.

  

• إذا كنت تفضل تشغيل أوامر مرجع CLI محلياً قم بتثبيت CLI Azure. إذا كنت تعمل على نظام تشغيل Windows أو macOS، ففكر في تشغيل Azure CLI في حاوية Docker. لمزيد من المعلومات، راجع كيفية تشغيل Azure CLI في حاوية Docker.

  • إذا كنت تستخدم تثبيت محلي، يُرجى تسجيل الدخول إلى Azure CLI مستخدمًا أمر az login. لإنهاء عملية المصادقة، اتبع الخطوات المعروضة في جهازك. للحصول على خيارات أخرى لتسجيل دخول، راجع تسجيل الدخول باستخدام Azure CLI.

  • عندما يُطلب منك، قم بتثبيت ملحق Azure CLI عند الاستخدام لأول مرة. لمزيد من المعلومات بشأن الامتدادات، راجع استخدام امتدادات مع Azure CLI.

  • يُرجى تشغيل إصدار az للوصول إلى الإصدار والمكتبات التابعة التي تم تثبيتها. للتحديث لآخر إصدار، يُرجى تشغيل تحديث az.

قم بإنشاء حاوية ثانية في حساب التخزين الخاص بك

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

مدخل Microsoft Azure

1. افتح مدخل Microsoft Azure وابحث عن Storage accounts.

2. حدد الحساب الذي أنشأته سابقًا.

3. في قائمة حساب التخزين، حدد Containers من قسم Data storage.

4. حدد الحاويات لإنشاء حاوية جديدة.

   

5. قم بتسمية الحاوية enriched، وحدد Create.

Azure CLI

تلميح

تستخدم العديد من أوامر CLI المستخدمة في هذا البرنامج التعليمي نفس المعلمات. لراحتك، قمنا بتحديد المتغيرات المحلية التي يمكن استدعاؤها حسب الحاجة. تأكد من تشغيل جميع الأوامر في نفس الجلسة، وإلا فسيتعين عليك إعادة تعريف المتغيرات.

يجب أن تكون قيم هذه المتغيرات لنفس الموارد التي استخدمتها في الجزء الأول من هذا البرنامج التعليمي.

1. حدد المتغيرات الخاصة بمركز IoT وحساب التخزين والحاوية.

   GROUP_NAME: استبدل هذا العنصر النائب باسم مجموعة الموارد التي تحتوي على مركز IoT.

   IOTHUB_NAME: استبدل هذا العنصر النائب باسم مركز IoT الخاص بك.

   DEVICE_ID: استبدل هذا العنصر النائب بمعرف جهازك.

   STORAGE_NAME: استبدل هذا العنصر النائب باسم حساب التخزين الخاص بك.

   لهذا البرنامج التعليمي، يجب containerNameإثراء قيمة المتغير.

   resourceGroup=GROUP_NAME
   hubName=IOTHUB_NAME
   deviceId=DEVICE_ID
   storageName=STORAGE_NAME
   containerName=enriched
   

2. استخدم az storage container create لإضافة حاوية إلى حساب التخزين الخاص بك.

   az storage container create --auth-mode login --account-name $storageName --name $containerName
   

توجيه الرسائل إلى نقطة نهاية ثانية

إنشاء نقطة نهاية ثانية وتوجيه للرسائل التي تم إثراؤها.

مدخل Microsoft Azure

1. في مدخل Microsoft Azure، انتقل إلى مركز IoT.

2. في قائمة الموارد ضمن Hub settings، حدد Message routing ثم حدد Add.

   

3. في علامة التبويب Endpoint ، قم بإنشاء نقطة نهاية تخزين عن طريق توفير المعلومات التالية:

   المعلمة	القيمة
   نوع نقطة النهاية	اختار التخزين .
   اسم نقطة النهاية	أدخل ContosoStorageEndpointEnriched.
   حاوية تخزين Azure	حدد "Pick a container". اتبع المطالبات لتحديد حساب التخزين والحاوية التي قمت بإنشائها في القسم السابق.
   الترميز	حدد JSON. إذا كان هذا الحقل رمادي اللون، فإن منطقة حساب التخزين لا تدعم JSON. في هذه الحالة، تابع مع AVROالافتراضي.

   

4. اقبل القيم الافتراضية لبقية المعلمات وحدد Create + next.

5. تابع إنشاء المسار الجديد، الآن بعد أن أضفت نقطة نهاية التخزين. قدم المعلومات التالية لمسار الاختبار الجديد:

   المعلمة	القيمة
   الاسم	ContosoStorageRouteEnriched
   مصدر البيانات	تحقق من تحديد رسائل بيانات تتبع استخدام الجهاز من القائمة المنسدلة.
   تمكين المسار	تحقق من تعيين هذا الحقل إلى enabled.
   استعلام التوجيه	أدخل level="storage" مثل سلسة الاستعلام.

   

6. حدد Create + add enrichments.

Azure CLI

1. تكوين المتغيرات لأوامر نقطة النهاية والمسار لاستخدام القيم ContosoStorageEndpointEnriched وContosoStorageRouteEnriched، على التوالي.

   endpointName=ContosoStorageEndpointEnriched
   routeName=ContosoStorageRouteEnriched
   

2. استخدم الأمر az iot hub message-endpoint create لإنشاء نقطة نهاية مخصصة تشير إلى حاوية التخزين التي قمت بإنشائها في القسم السابق.

   az iot hub message-endpoint create \
     --connection-string $(az storage account show-connection-string --name $storageName --query connectionString -o tsv) \
     --endpoint-name $endpointName \
     --hub-name $hubName \
     --container $containerName \
     --resource-group $resourceGroup \
     --encoding json
   

3. استخدم الأمر az iot hub message-route create لإنشاء مسار يمرر أي رسالة إلى level=storage نقطة نهاية حاوية التخزين.

   az iot hub message-route create \
     --route-name $routeName \
     --hub-name $hubName \
     --resource-group $resourceGroup \
     --source-type devicemessages \
     --endpoint-name $endpointName \
     --enabled true \
     --condition 'level="storage"'
   

إضافة إثراء الرسائل إلى نقطة النهاية الجديدة

إنشاء ثلاث عمليات إثراء للرسائل التي سيتم توجيهها إلى حاوية التخزين التي تم إثراؤها.

مدخل Microsoft Azure

1. في علامة التبويب Enrichment في معالج Add a route ، أضف ثلاث عمليات إثراء رسائل للرسائل التي تنتقل إلى نقطة النهاية لحاوية التخزين المسماة enriched.

   أضف هذه القيم كإثراء رسائل لنقطة نهاية ContosoStorageEndpointEnriched:

   الاسم	القيمة‬
   myIotHub	$hubname
   DeviceLocation	$twin.tags.location (بافتراض أن توأم الجهاز لديه علامة موقع)
   customerID	6ce345b8-1e4a-411e-9398-d34587459a3a

   عند الانتهاء، يجب أن تبدو عمليات الإثراء مشابهة لهذه الصورة:

   

2. حدد Add لإضافة إثراء الرسائل.

Azure CLI

قم بإجراء ثلاثة استدعاءات إلى الأمر az iot hub message-enrichment create لإضافة إثراء الرسائل إلى المسار الانتقال إلى نقطة النهاية التي تم إنشاؤها مسبقًا.

az iot hub message-enrichment create \
  --key myIotHub \
  --value $hubName \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

# This assumes that the device twin has a location tag.
az iot hub message-enrichment create \
  --key DeviceLocation \
  --value '$twin.tags.location' \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

az iot hub message-enrichment create \
  --key customerID \
  --value 6ce345b8-1e4a-411e-9398-d34587459a3a \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

لديك الآن عمليات إثراء الرسائل التي تم إعدادها لجميع الرسائل التي تم توجيهها إلى نقطة النهاية التي أنشأتها للرسائل التي تم إثراؤها. إذا كنت لا تريد إضافة علامة موقع إلى توأم الجهاز، يمكنك التخطي إلى قسم Test message enrichments لمتابعة البرنامج التعليمي.

إضافة علامة الموقع للجهاز المزدوج

يحدد أحد عمليات إثراء الرسائل التي تم تكوينها على مركز IoT مفتاح DeviceLocation بقيمته التي يحددها المسار المزدوج للجهاز التالي: $twin.tags.location. إذا لم يكن لدى الجهاز المزدوج علامة موقع، فسيتم ختم مسار التوأم، $twin.tags.locationكسلسلة لمفتاح DeviceLocation في إثراء الرسائل.

اتبع هذه الخطوات لإضافة علامة موقع إلى توأم جهازك:

مدخل Microsoft Azure

1. انتقل إلى IoT Hub الخاص بك في مدخل Microsoft Azure.

2. حدد الأجهزة في قائمة التنقل في مركز IoT، ثم حدد جهازك.

3. حدد علامة التبويب Device twin أعلى صفحة الجهاز وأضف السطر التالي قبل قوس الإغلاق أسفل الجهاز المزدوج مباشرةً. ثم حدد حفظ.

     , "tags": {"location": "Plant 43"}
   

   

Azure CLI

استخدم الأمر az iot hub device-twin update لتحديث الجهاز المزدوج بمفتاح علامة وقيمة جديدين.

az iot hub device-twin update \
  --hub-name $hubName \
  --device-id $deviceId \
  --tags '{"location": "Plant 43"}'

تلميح

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

لمعرفة المزيد حول كيفية التعامل مع المسارات المزدوجة للأجهزة من خلال إثراءات الرسائل، راجع قيود إثراءات الرسائل. لمعرفة المزيد حول الأجهزة المزدوجة، راجع التعرف على الأجهزة المزدوجة واستخدامها في IoT Hub.

اختبار إثراء الرسائل

الآن بعد أن تم تكوين تحسينات الرسائل لنقطة نهاية ContosoStorageEndpointEnriched، قم بتشغيل تطبيق الجهاز المحاكى لإرسال الرسائل إلى مركز إنترنت الأشياء. عند هذه النقطة، تم إعداد توجيه الرسائل على النحو التالي:

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

• سيتم إثراء الرسائل الموجهة إلى نقطة نهاية التخزين ContosoStorageEndpointEnriched وتخزينها في حاوية التخزين الثرية.

إذا لم تكن لا تزال تقوم بتشغيل تطبيق وحدة تحكم SimulatedDevice من الجزء الأول من هذا البرنامج التعليمي، فقم بتشغيله مرة أخرى:

تلميح

إذا كنت تتبع خطوات Azure CLI لهذا البرنامج التعليمي، فقم بتشغيل نموذج التعليمات البرمجية في جلسة منفصلة. بهذه الطريقة، يمكنك السماح لمواصلة تشغيل نموذج التعليمات البرمجية أثناء اتباع باقي خطوات CLI.

1. في المجلد النموذجي، انتقل إلى /iot-hub/Tutorials/Routing/SimulatedDevice/ المجلد.

2. يجب أن تظل تعريفات المتغيرات التي قمت بتحديثها من قبل صالحة، ولكن إذا لم يكن صحيحًا، فقم بتحريرها في Program.cs الملف:

   1. ابحث عن تعريفات المتغير في أعلى فئة البرنامج. قم بتحديث المتغيرات التالية بمعلوماتك الخاصة:

      • s_myDeviceId: معرف الجهاز الذي قمت بتعيينه عند تسجيل الجهاز في مركز IoT.
      • s_iotHubUri: اسم مضيف مركز IoT الخاص بك، والذي يأخذ التنسيق IOTHUB_NAME.azure-devices.net.
      • s_deviceKey: المفتاح الأساسي للجهاز الموجود في معلومات هوية الجهاز.

   2. احفظ الملف وأغلقه.

3. شغل التعليمات البرمجية النموذجية:

   dotnet run
   

بعد مغادرة تطبيق وحدة التحكم للتشغيل لبضع دقائق، اعرض البيانات:

1. في Azure portal، انتقل إلى حساب التخزين الخاص بك.

2. حدد مستعرض التخزين من قائمة التنقل. حدد حاويات Blob لمشاهدة الحاويتين اللتين أنشأتهما خلال هذه البرامج التعليمية.

   

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

عندما تنظر إلى الرسائل التي تم تحسينها، يجب أن ترى "myIotHub"مع اسم المركز والموقع ومعرف العميل، على النحو التالي:

{
  "EnqueuedTimeUtc":"2019-05-10T06:06:32.7220000Z",
  "Properties":
  {
    "level":"storage",
    "myIotHub":"{your hub name}",
    "DeviceLocation":"Plant 43",
    "customerID":"6ce345b8-1e4a-411e-9398-d34587459a3a"
  },
  "SystemProperties":
  {
    "connectionDeviceId":"Contoso-Test-Device",
    "connectionAuthMethod":"{\"scope\":\"device\",\"type\":\"sas\",\"issuer\":\"iothub\",\"acceptingIpFilterRule\":null}",
    "connectionDeviceGenerationId":"636930642531278483",
    "enqueuedTime":"2019-05-10T06:06:32.7220000Z"
  },"Body":"eyJkZXZpY2VJZCI6IkNvbnRvc28tVGVzdC1EZXZpY2UiLCJ0ZW1wZXJhdHVyZSI6MjkuMjMyMDE2ODQ4MDQyNjE1LCJodW1pZGl0eSI6NjQuMzA1MzQ5NjkyODQ0NDg3LCJwb2ludEluZm8iOiJUaGlzIGlzIGEgc3RvcmFnZSBtZXNzYWdlLiJ9"
}

تنظيف الموارد

لإزالة جميع الموارد التي قمت بإنشائها في كلا الجزأين من هذا البرنامج التعليمي، احذف مجموعة الموارد. يؤدي هذا الإجراء إلى حذف جميع الموارد الموجودة داخل المجموعة. إذا كنت لا تريد حذف مجموعة الموارد بأكملها، يمكنك تحديد موارد فردية داخل لحذفها.

مدخل Microsoft Azure

1. في مدخل Microsoft Azure، انتقل إلى مجموعة الموارد التي تحتوي على مركز IoT وحساب التخزين لهذا البرنامج التعليمي.
2. راجع جميع الموارد الموجودة في مجموعة الموارد لتحديد الموارد التي تريد تنظيفها.
   • إذا كنت تريد حذف كل المورد، فحدد حذف مجموعة الموارد.
   • إذا كنت تريد حذف مورد معين فقط، فاستخدم خانات الاختيار الموجودة بجانب كل اسم مورد لتحديد تلك التي تريد حذفها. ثم حدد حذف.

Azure CLI

1. استخدم الأمر az resources list لعرض جميع الموارد في مجموعة الموارد الخاصة بك.

   az resource list --resource-group $resourceGroup --output table
   

2. راجع جميع الموارد الموجودة في مجموعة الموارد لتحديد الموارد التي تريد تنظيفها.

   • إذا كنت تريد حذف كافة الموارد، فاستخدم الأمر az group delete.

     az group delete --name $resourceGroup
     

   • إذا كنت تريد حذف موارد معينة فقط، فاستخدم الأمر az resource delete. على سبيل المثال:

     az resource delete --resource-group $resourceGroup --name $storageName
     

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

في هذا البرنامج التعليمي، قمت بتكوين واختبار تحسينات الرسائل لرسائل IoT Hub أثناء توجيهها إلى نقطة نهاية.

لمزيد من المعلومات حول إثراء الرسائل، راجع نظرة عامة على إثراء الرسائل.

لمعرفة المزيد حول IoT Hub، تابع إلى البرنامج التعليمي التالي.

برنامج تعليمي: إعداد واستخدام المقاييس والسجلات مع مركز IoT