البرنامج التعليمي: إرسال بيانات الجهاز إلى Azure Storage باستخدام توجيه رسائل IoT Hub

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

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

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

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

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

• مركز IoT في اشتِراك Azure الخاص بك. إذا لم تكن لديك مركز بعد، فإنه يمكنك اتباع الخطوات الواردة في إنشاء مركز IoT.

• يستخدم هذا البرنامج التعليمي نموذج التعليمات البرمجية من Azure IoT SDK ل C#‎.

  • قم بتنزيل أو استنساخ مستودع SDK إلى جهاز التطوير الخاص بك.
  • امتلك الإصدار .NET Core 3.0.0 أو إصدارًا أعلى على جهاز التطوير لديك. تحقق من الإصدار الخاص بك عن طريق تشغيل dotnet --versionوتنزيل .NET إذا لزم الأمر.

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

• اختياريًا، قم بتثبيت Azure IoT Explorer. تساعدك هذه الأداة على مراقبة الرسائل عند وصولها إلى مركز IoT الخاص بك. تستخدم هذه المقالة Azure IoT Explorer.

مدخل 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.

تسجيل جهاز وإرسال الرسائل إلى IoT Hub

تسجيل جهاز جديد في IoT hub.

مدخل Microsoft Azure

1. سجل الدخول إلى مدخل Microsoft Azure والانتقال إلى IoT hub الخاص بك.

2. حدد Devices من قسم Device management في القائمة.

3. حدد Add device.

   

4. قم بتوفير معرف جهاز وحدد Save.

5. يجب أن يكون الجهاز الجديد في قائمة الأجهزة الآن. إذا لم يكن الأمر كذلك، فقم بتحديث الصفحة. حدد معرف الجهاز لفتح صفحة تفاصيل الجهاز.

6. انسخ أحد مفاتيح الجهاز واحفظها. ستستخدم هذه القيمة لتكوين نموذج التعليمات البرمجية الذي ينشئ رسائل محاكاة بيانات تتبع الاستخدام للجهاز.

   

Azure CLI

تلميح

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

1. حدد المتغيرات لمركز IoT وجهازك.

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

   DEVICE_NAME: استبدل هذا العنصر النائب بأي اسم تريد استخدامه للجهاز في هذا البرنامج التعليمي.

   hubName=IOTHUB_NAME
   deviceName=DEVICE_NAME
   

2. قم بتشغيل الأمر az iot hub device-identity create في غلاف CLI الخاص بك. يقوم هذا الأمر بإنشاء هوية الجهاز.

   az iot hub device-identity create --device-id $deviceName --hub-name $hubName
   

3. من إخراج هوية الجهاز، انسخ قيمة primaryKey بدون علامات الاقتباس المحيطة واحفظها. ستستخدم هذه القيمة لتكوين نموذج التعليمات البرمجية الذي ينشئ رسائل محاكاة بيانات تتبع الاستخدام للجهاز.

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

تلميح

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

1. إذا لم تكن جزءا من المتطلبات الأساسية، فبادر بتنزيل أو استنساخ Azure IoT SDK ل C# repo من GitHub الآن.

2. من المجلد حيث قمت بتنزيل SDK أو نسخه، انتقل إلى azure-iot-sdk-csharp\iothub\device\samples\how to guides\HubRoutingSample المجلد .

3. تثبيت Azure IoT C# SDK والتبعيات الضرورية كما هو محدد في الملف HubRoutingSample.csproj:

   dotnet restore
   

4. في محرر من اختيارك، افتح Parameters.cs الملف. يعرض هذا الملف المعلمات المدعومة من النموذج. سيتم استخدام المعلمة PrimaryConnectionString فقط في هذه المقالة عند تشغيل النموذج. راجع التعليمات البرمجية في هذا الملف. لا توجد حاجة لإجراء تغييرات.

5. إنشاء وتشغيل نموذج التعليمات البرمجية باستخدام الأمر التالي:

   استبدل <myDevicePrimaryConnectionString> سلسلة الاتصال الأساسية من جهازك في مركز IoT.

   dotnet run --PrimaryConnectionString <myDevicePrimaryConnectionString>
   

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

تكوين IoT Explorer لعرض الرسائل

تكوين IoT Explorer للاتصال بمركز IoT وقراءة الرسائل عند وصولها إلى نقطة النهاية المضمنة.

أولاً، استرداد سلسلة الاتصال لمركز IoT الخاص بك.

مدخل Microsoft Azure

1. في مدخل Microsoft Azure توجه إلى مركز IoT.

2. حدد Shared access policies من قسم Security settings في القائمة.

3. حدد سياسة iothubowner.

   

4. انسخ سلسلة الاتصال الأساسية.

   

Azure CLI

1. شغّل أمر az iot hub connection-string show:

   az iot hub connection-string show --hub-name $hubName
   

2. نسخ سلسلة الاتصال دون رموز الاقتباس المحيطة.

الآن، استخدم سلسلة الاتصال هذه لتكوين IoT Explorer لمركز IoT الخاص بك.

1. افتح IoT Explorer على جهاز التطوير الخاص بك.

2. حدد إضافة اتصال.

   

3. ألصق سلسلة اتصال المركز في مربع النص.

4. حدد حفظ.

5. بمجرد الاتصال بمركز IoT، يجب أن تشاهد قائمة بالأجهزة. حدد معرف الجهاز الذي أنشأته لهذا البرنامج التعليمي.

6. حدد Telemetry.

7. مع استمرار تشغيل جهازك، حدد بدء. إذا لم يكن جهازك قيد التشغيل، فلن ترى بيانات تتبع الاستخدام.

   

8. يجب أن تشاهد الرسائل التي تصل من جهازك، مع عرض أحدث الرسائل في الأعلى.

   

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

تصل جميع هذه الرسائل إلى نقطة النهاية المضمنة الافتراضية لمركز IoT. في الأقسام التالية، سنقوم بإنشاء نقطة نهاية مخصصة وتوجيه بعض هذه الرسائل إلى التخزين استنادًا إلى خصائص الرسالة. ستتوقف هذه الرسائل عن الظهور في IoT Explorer لأن الرسائل تنتقل فقط إلى نقطة النهاية المضمنة عندما لا تتطابق مع أي مسارات أخرى في مركز IoT.

إعداد مسار الرسائل

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

يعين نموذج التطبيق لهذا البرنامج التعليمي خاصية level لكل رسالة يرسلها إلى مركز IoT. يتم تعيين مستوى normal أو storage أو critical لكل رسالة بشكل عشوائي.

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

إنشاء حساب تخزين

إنشاء حساب Azure Storage وحاوية داخل هذا الحساب، والتي ستحتفظ برسائل الجهاز التي يتم توجيهها إليه.

مدخل Microsoft Azure

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

2. حدد إنشاء.

3. قم بتوفير القيم التالية لحساب التخزين الخاص بك:

   المعلمة	القيمة
   الاشتراك	حدد نفس الاشتراك الذي يحتوي على مركز IoT الخاص بك.
   مجموعة الموارد	حدد نفس مجموعة الموارد التي تحتوي على مركز IoT الخاص بك.
   Storage account name	توفير اسم مميز عالمي لحساب التخزين خاصتك.
   الاداء	اقبل القيمة الافتراضية Standard.

   

4. يمكنك قبول جميع القيم الافتراضية الأخرى عن طريق تحديد Review + create.

5. وبعد اكتمال عملية التحقق، حدد Create.

6. عند اكتمال عملية التوزيع، حدد «Go to resource».

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

8. حدد + Container لإنشاء حاوية جديدة.

   

9. أدخل اسمًا لحاويتك وحدد Create.

Azure CLI

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

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

   STORAGE_NAME: استبدل هذا العنصر النائب باسم حساب التخزين الخاص بك. يجب أن يكون اسم حساب التخزين بأحرف صغيرة وفريد عالميًا.

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

   resourceGroup=GROUP_NAME
   storageName=STORAGE_NAME
   containerName=CONTAINER_NAME
   

2. استخدم الأمر az storage account create لإنشاء حساب تخزين قياسي للأغراض العامة v2.

   az storage account create --name $storageName --resource-group $resourceGroup
   

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

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

التوجيه إلى حساب التخزين

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

إشعار

يمكن كتابة البيانات لتخزين blob إما بتنسيق Apache Avro، وهو الإعداد الافتراضي، أو JSON.

يمكن تعيين تنسيق الترميز فقط عند تكوين نقطة نهاية تخزين blob. لا يمكن تغيير التنسيق لنقطة نهاية تم إعدادها بالفعل. عند استخدام ترميز JSON يجب تعيين contentType إلى JSON ومحتوىEncoding إلى UTF-8 في خصائص نظام الرسالة.

للحصول على معلومات أكثر تفصيلاً حول استخدام نقطة نهاية تخزين blob، يرجى الاطلاع على إرشادات حول التوجيه إلى التخزين.

مدخل Microsoft Azure

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

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

   

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

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

   

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

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

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

   

6. حدد Create + skip enrichments.

Azure CLI

1. تكوين المتغيرات التي تحتاجها لأوامر نقطة النهاية والمسار.

   ENDPOINT_NAME: أدخل اسمًا لنقطة النهاية التي تمثل حاوية التخزين الخاصة بك.

   ROUTE_NAME: توفير اسم للمسار الذي يقوم بتصفية الرسائل لنقطة نهاية التخزين

   endpointName=ENDPOINT_NAME
   routeName=ROUTE_NAME
   

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

   az iot hub message-endpoint create storage-container \
     --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"'
   

عرض الرسائل التي تم توجيهها

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

مراقبة نقطة النهاية المضمنة باستخدام IoT Explorer

ارجع إلى جلسة عمل IoT Explorer على جهاز التطوير الخاص بك. تذكر أن IoT Explorer يراقب نقطة النهاية المضمنة لمركز IoT الخاص بك. وهذا يعني أنه يجب أن تشاهد الآن فقط الرسائل التي لا يتم توجيهها بواسطة المسار المخصص الذي أنشأناه.

ابدأ النموذج مرة أخرى عن طريق تشغيل التعليمات البرمجية. شاهد الرسائل الواردة لبضع لحظات ويجب أن تشاهد فقط الرسائل التي تم تعيين level فيها إلى normal أو critical.

عرض الرسائل في حاوية التخزين

تحقق من وصول الرسائل إلى حاوية التخزين.

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

2. حدد Containers من قسم Data storage في القائمة.

3. حدد الحاوية التي أنشأتها لهذا البرنامج التعليمي.

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

   

5. حدد ملف JSON، ثم حدد Download لتنزيل ملف JSON. تأكد من أن الملف يحتوي على رسائل من جهازك تم تعيين الخاصية level عليها إلى storage.

6. توقف عن تشغيل العينة.

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

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

إذا كنت تنوي الاستمرار في البرنامج التعليمي التالي، فاحتفظ بالموارد التي قمت بإنشائها هنا.

مدخل 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
     

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

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

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