تصدير بيانات IoT إلى ناقل خدمة Microsoft Azure

توضح هذه المقالة كيفية تكوين تصدير البيانات لإرسال البيانات إلى ناقل خدمة Microsoft Azure.

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

على سبيل المثال، يمكنك:

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

تلميح

عند تشغيل تصدير البيانات، تحصل فقط على البيانات من تلك اللحظة فصاعدا. للاحتفاظ بمزيد من البيانات التاريخية، قم بتشغيل تصدير البيانات في وقت مبكر. لتصدير البيانات يدويا من الأوقات التي تم فيها إيقاف تصدير البيانات، راجع كيفية استخدام واجهة برمجة تطبيقات REST ل IoT Central للاستعلام عن الأجهزة.

إشعار

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

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

لاستخدام ميزات تصدير البيانات، يجب أن يكون لديك إذن تصدير البيانات.

إعداد وجهة تصدير ناقل خدمة Microsoft Azure

يتم دعم كل من قوائم الانتظار والموضوعات للوجهات ناقل خدمة Azure.

يصدر IoT Central البيانات في الوقت الفعلي تقريبا. البيانات موجودة في نص الرسالة ويتم ترميزها بتنسيق JSON ك UTF-8.

تحتوي التعليقات التوضيحية أو حقيبة خصائص النظام للرسالة على iotcentral-device-idiotcentral-application-idiotcentral-message-sourceالحقول و iotcentral-message-type التي لها نفس قيم الحقول المقابلة في نص الرسالة.

خيارات الاتصال

تتيح لك وجهات ناقل خدمة Microsoft Azure تكوين الاتصال باستخدام سلسلة الاتصال أو هوية مدارة.

الهويات المدارة أكثر أمانا لأن:

  • لا تقوم بتخزين بيانات الاعتماد لموردك في سلسلة الاتصال في تطبيق IoT Central.
  • ترتبط بيانات الاعتماد تلقائيا بمدة بقاء تطبيق IoT Central الخاص بك.
  • تقوم الهويات المدارة تلقائيا بتدوير مفاتيح الأمان الخاصة بها بانتظام.

يستخدم IoT Central حاليا الهويات المدارة المعينة من قبل النظام.

عند تكوين هوية مدارة، يتضمن التكوين نطاقا ودورا:

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

يوفر الفيديو التالي المزيد من المعلومات حول الهويات المدارة المعينة من قبل النظام:

تنبيه

للتصدير إلى تخزين كائن ثنائي كبير الحجم، لا تستخدم مساهم حساب التخزين كما هو موضح في الفيديو. استخدم دور Storage Blob Data Contributor بدلا من ذلك.

إنشاء قائمة انتظار ناقل خدمة Microsoft Azure أو وجهة الموضوع

توضح هذه المقالة كيفية إنشاء هوية مدارة باستخدام Azure CLI. يمكنك أيضا استخدام مدخل Microsoft Azure لإنشاء هوية مدارة.

إذا لم يكن لديك مساحة اسم ناقل خدمة Microsoft Azure موجودة للتصدير إليها، فقم بتشغيل البرنامج النصي التالي في بيئة Bash Azure Cloud Shell. ينشئ البرنامج النصي مجموعة موارد ومساحة اسم ناقل خدمة Microsoft Azure وقائمة انتظار. ثم يمكن البرنامج النصي الهوية المدارة لتطبيق IoT Central الخاص بك ويعين الدور الذي يحتاجه للوصول إلى قائمة انتظار ناقل خدمة Microsoft Azure:

# Replace the Service Bus namespace name with your own unique value
SBNS=your-service-bus-namespace-$RANDOM

# Replace the IoT Central app name with the name of your
# IoT Central application.
CA=your-iot-central-app

SBQ=exportdata
RG=centralexportresources
LOCATION=eastus

RGID=$(az group create -n $RG --location $LOCATION --query "id" --output tsv)
az servicebus namespace create --name $SBNS --resource-group $RG -l $LOCATION
az servicebus queue create --name $SBQ --resource-group $RG --namespace-name $SBNS

# This assumes your IoT Central application is in the 
# default `IOTC` resource group.
az iot central app identity assign --name $CA --resource-group IOTC --system-assigned
PI=$(az iot central app identity show --name $CA --resource-group IOTC --query "principalId" --output tsv)

az role assignment create --assignee $PI --role "Azure Service Bus Data Sender" --scope $RGID

az role assignment list --assignee $PI --all -o table

echo "Host name: $SBNS.servicebus.windows.net"
echo "Queue: $SBQ"

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

لإنشاء وجهة ناقل خدمة Microsoft Azure في IoT Central في صفحة تصدير البيانات:

  1. حدد + وجهة جديدة.

  2. حدد ناقل خدمة Azure Queue أو ناقل خدمة Azure Topic كنوع الوجهة.

  3. حدد الهوية المدارة المعينة من قبل النظام كنوع التخويل.

  4. أدخل اسم المضيف لمورد ناقل خدمة Microsoft Azure. ثم أدخل اسم قائمة الانتظار أو الموضوع الحساس لحالة الأحرف. يبدو اسم المضيف كما يلي: contoso-waste.servicebus.windows.net.

  5. حدد حفظ.

إذا لم تتمكن من رؤية البيانات التي تصل إلى خدمة الوجهة، فراجع استكشاف المشكلات المتعلقة بتصدير البيانات وإصلاحها من تطبيق Azure IoT Central.

إعداد تصدير البيانات

الآن بعد أن أصبح لديك وجهة لتصدير بياناتك إليها، قم بإعداد تصدير البيانات في تطبيق IoT Central الخاص بك:

  1. سجل الدخول إلى تطبيق IoT Central.

  2. في الجزء الأيمن، حدد تصدير البيانات.

    تلميح

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

  3. حدد + تصدير جديد.

  4. أدخل اسم عرض للتصدير الجديد، وتأكد من تمكين تصدير البيانات.

  5. اختر نوع البيانات المراد تصديرها. يسرد الجدول التالي أنواع تصدير البيانات المدعومة:

    نوع البيانات ‏‏الوصف تنسيق البيانات
    القياس عن بعد تصدير رسائل بيانات تتبع الاستخدام من الأجهزة في الوقت الفعلي تقريبا. تحتوي كل رسالة تم تصديرها على المحتويات الكاملة لرسالة الجهاز الأصلية، التي تمت تسويتها. تنسيق رسالة بيانات تتبع الاستخدام
    تغييرات الخاصية تصدير التغييرات إلى خصائص الجهاز والسحابة في الوقت الفعلي تقريبا. بالنسبة لخصائص الجهاز للقراءة فقط، يتم تصدير التغييرات على القيم المبلغ عنها. بالنسبة لخصائص القراءة والكتابة، يتم تصدير كل من القيم المبلغ عنها والمطلوبة. تنسيق رسالة تغيير الخاصية
    اتصال الجهاز تصدير الأحداث المتصلة وغير المتصلة بالجهاز. تنسيق رسالة اتصال الجهاز
    دورة حياة الجهاز تصدير الأجهزة المسجلة والمحذوفة والموفرة والممكنة والمعطلة وsplayNameChanged وdeviceTemplateChanged الأحداث. تغيير تنسيق رسالة دورة حياة الجهاز
    دورة حياة قالب الجهاز تصدير تغييرات قالب الجهاز المنشورة بما في ذلك الإنشاء والتحديث والحذف. دورة حياة قالب الجهاز تغير تنسيق الرسالة
    سجلات التدقيق سجلات التحديثات التي بدأها المستخدم للكيانات في التطبيق. لمعرفة المزيد، راجع استخدام سجلات التدقيق لتعقب النشاط في تطبيق IoT Central تنسيق رسالة سجل التدقيق
  6. اختياريا، أضف عوامل تصفية لتقليل كمية البيانات المصدرة. هناك أنواع مختلفة من عوامل التصفية المتوفرة لكل نوع من أنواع تصدير البيانات:

    نوع البيانات عوامل التصفية المتاحة‬
    القياس عن بعد
    • تصفية حسب اسم الجهاز ومعرف الجهاز وقالب الجهاز وإذا تمت محاكاة الجهاز
    • تدفق التصفية ليحتوي فقط على بيانات تتبع الاستخدام التي تفي بشروط التصفية
    • تدفق التصفية ليحتوي فقط على بيانات تتبع الاستخدام من الأجهزة ذات الخصائص المطابقة لشروط التصفية
    • تدفق التصفية ليحتوي فقط على بيانات تتبع الاستخدام التي تحتوي على خصائص رسالة تفي بشرط عامل التصفية. يتم إرسال خصائص الرسالة (المعروفة أيضا باسم خصائص التطبيق) في حقيبة من أزواج قيمة المفتاح في كل رسالة بيانات تتبع الاستخدام. لإنشاء عامل تصفية خاصية رسالة، أدخل مفتاح خاصية الرسالة الذي تبحث عنه، وحدد شرطا. يتم تصدير رسائل بيانات تتبع الاستخدام التي تحتوي على خصائص تطابق شرط عامل التصفية المحدد فقط. تعرف على المزيد حول خصائص التطبيق من مستندات IoT Hub
    تغييرات الخاصية
    • تصفية حسب اسم الجهاز ومعرف الجهاز وقالب الجهاز وإذا تمت محاكاة الجهاز
    • تصفية الدفق لتحتوي فقط على تغييرات الخاصية التي تفي بشروط التصفية
    اتصال الجهاز
    • التصفية حسب اسم الجهاز ومعرف الجهاز وقالب الجهاز والمؤسسات وإذا تمت محاكاة الجهاز
    • تصفية الدفق لتحتوي فقط على تغييرات من الأجهزة ذات الخصائص المطابقة لشروط التصفية
    دورة حياة الجهاز
    • تصفية حسب اسم الجهاز، ومعرف الجهاز، وقالب الجهاز، وإذا تم توفير الجهاز أو تمكينه أو محاكاته
    • تصفية الدفق لتحتوي فقط على تغييرات من الأجهزة ذات الخصائص المطابقة لشروط التصفية
    دورة حياة قالب الجهاز
    • التصفية حسب قالب الجهاز
    سجلات التدقيق ‏‫غير متوفر‬
  7. اختياريا، إثراء الرسائل المصدرة ببيانات تعريف زوج قيمة المفتاح الإضافية. تتوفر عمليات الإثراء التالية لبيانات تتبع الاستخدام وتغييرات الخصائص واتصال الجهاز وأنواع تصدير بيانات دورة حياة الجهاز:

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

تكوين وجهة التصدير:

  1. حدد + الوجهة لإضافة وجهة قمت بإنشائها بالفعل أو حدد إنشاء وجهة جديدة.

  2. لتحويل بياناتك قبل تصديرها، حدد + Transform. لمعرفة المزيد، راجع تحويل البيانات داخل تطبيق IoT Central للتصدير.

  3. حدد + Destination لإضافة ما يصل إلى خمس وجهات إلى تصدير واحد.

  4. عند الانتهاء من إعداد التصدير، حدد حفظ. بعد بضع دقائق، تظهر بياناتك في وجهاتك.

مراقبة التصدير

في IoT Central، تتيح لك صفحة تصدير البيانات التحقق من حالة عمليات التصدير الخاصة بك. يمكنك أيضا استخدام Azure Monitor لمعرفة مقدار البيانات التي تقوم بتصديرها وأي أخطاء في التصدير. يمكنك الوصول إلى مقاييس التصدير وصحة الجهاز في المخططات في مدخل Microsoft Azure باستخدام أو واجهة برمجة تطبيقات REST أو الاستعلامات في PowerShell أو Azure CLI. حاليا، يمكنك مراقبة مقاييس تصدير البيانات التالية في Azure Monitor:

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

لمعرفة المزيد، راجع مراقبة صحة التطبيق.

تنسيقات البيانات

تصف الأقسام التالية تنسيقات البيانات المصدرة:

تنسيق بيانات تتبع الاستخدام

تحتوي كل رسالة تم تصديرها على نموذج تمت تسويته للرسالة الكاملة التي أرسلها الجهاز في نص الرسالة. الرسالة بتنسيق JSON ويتم ترميزها ك UTF-8. تتضمن المعلومات الواردة في كل رسالة ما يلي:

  • applicationId: معرف تطبيق IoT Central.
  • messageSource: مصدر الرسالة - telemetry.
  • deviceId: معرف الجهاز الذي أرسل رسالة بيانات تتبع الاستخدام.
  • schema: اسم وإصدار مخطط الحمولة.
  • templateId: معرف قالب الجهاز المعين للجهاز.
  • enqueuedTime: الوقت الذي تلقى فيه IoT Central هذه الرسالة.
  • enrichments: أي عمليات إثراء تم إعدادها على التصدير.
  • module: وحدة IoT Edge التي أرسلت هذه الرسالة. يظهر هذا الحقل فقط إذا كانت الرسالة واردة من وحدة IoT Edge.
  • component: المكون الذي أرسل هذه الرسالة. يظهر هذا الحقل فقط إذا تم تصميم الإمكانات المرسلة في الرسالة كمكون في قالب الجهاز
  • messageProperties: الخصائص الأخرى التي أرسلها الجهاز مع الرسالة. يشار إلى هذه الخصائص أحيانا باسم خصائص التطبيق. تعرف على المزيد من مستندات IoT Hub.

خصائص الرسالة

تحتوي رسائل بيانات تتبع الاستخدام على خصائص لبيانات التعريف بالإضافة إلى حمولة بيانات تتبع الاستخدام. تعرض القصاصة البرمجية السابقة أمثلة على رسائل النظام مثل deviceId و enqueuedTime. لمعرفة المزيد حول خصائص رسالة النظام، راجع خصائص النظام لرسائل IoT Hub من جهاز إلى سحابة.

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

توضح القصاصة البرمجية التالية كيفية إضافة الخاصية iothub-creation-time-utc إلى الرسالة عند إنشائها على الجهاز:

هام

يجب أن يكون تنسيق هذا الطابع الزمني بالتوقيت العالمي المتفق عليه دون معلومات عن المنطقة الزمنية. على سبيل المثال، 2021-04-21T11:30:16Z صالح، و2021-04-21T11:30:16-07:00 غير صالح.

async function sendTelemetry(deviceClient, index) {
  console.log('Sending telemetry message %d...', index);
  const msg = new Message(
    JSON.stringify(
      deviceTemperatureSensor.updateSensor().getCurrentTemperatureObject()
    )
  );
  msg.properties.add("iothub-creation-time-utc", new Date().toISOString());
  msg.contentType = 'application/json';
  msg.contentEncoding = 'utf-8';
  await deviceClient.sendEvent(msg);
}

تنسيق تغييرات الخاصية

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

  • applicationId: معرف تطبيق IoT Central.
  • messageSource: مصدر الرسالة - properties.
  • messageType: إما cloudPropertyChangeأو devicePropertyDesiredChangeأو devicePropertyReportedChange.
  • deviceId: معرف الجهاز الذي أرسل رسالة بيانات تتبع الاستخدام.
  • schema: اسم وإصدار مخطط الحمولة.
  • enqueuedTime: الوقت الذي اكتشف فيه IoT Central هذا التغيير.
  • templateId: معرف قالب الجهاز المعين للجهاز.
  • properties: صفيف من الخصائص التي تغيرت، بما في ذلك أسماء الخصائص والقيم التي تغيرت. يتم تضمين معلومات المكون والوحدة النمطية إذا تم تصميم الخاصية داخل مكون أو وحدة IoT Edge.
  • enrichments: أي عمليات إثراء تم إعدادها على التصدير.

تنسيق تغييرات اتصال الجهاز

يمثل كل رسالة أو سجل حدث اتصال من جهاز واحد. تتضمن المعلومات الواردة في الرسالة المصدرة ما يلي:

  • applicationId: معرف تطبيق IoT Central.
  • messageSource: مصدر الرسالة - deviceConnectivity.
  • messageType: إما connected أو disconnected.
  • deviceId: معرف الجهاز الذي تم تغييره.
  • schema: اسم وإصدار مخطط الحمولة.
  • templateId: معرف قالب الجهاز المعين للجهاز.
  • enqueuedTime: الوقت الذي حدث فيه هذا التغيير في IoT Central.
  • enrichments: أي عمليات إثراء تم إعدادها على التصدير.

تنسيق تغييرات دورة حياة الجهاز

يمثل كل رسالة أو سجل تغييرا واحدا على جهاز واحد. تتضمن المعلومات الواردة في الرسالة المصدرة ما يلي:

  • applicationId: معرف تطبيق IoT Central.
  • messageSource: مصدر الرسالة - deviceLifecycle.
  • messageType: نوع التغيير الذي حدث. واحد من: registeredو deletedو provisionedenabledو. disableddeviceTemplateChangeddisplayNameChanged
  • deviceId: معرف الجهاز الذي تم تغييره.
  • schema: اسم وإصدار مخطط الحمولة.
  • templateId: معرف قالب الجهاز المعين للجهاز.
  • enqueuedTime: الوقت الذي حدث فيه هذا التغيير في IoT Central.
  • enrichments: أي عمليات إثراء تم إعدادها على التصدير.

تنسيق تغييرات دورة حياة قالب الجهاز

يمثل كل رسالة أو سجل تغييرا واحدا لقالب جهاز منشور واحد. تتضمن المعلومات الواردة في الرسالة المصدرة ما يلي:

  • applicationId: معرف تطبيق IoT Central.
  • messageSource: مصدر الرسالة - deviceTemplateLifecycle.
  • messageType: إما createdأو updatedأو deleted.
  • schema: اسم وإصدار مخطط الحمولة.
  • templateId: معرف قالب الجهاز المعين للجهاز.
  • enqueuedTime: الوقت الذي حدث فيه هذا التغيير في IoT Central.
  • enrichments: أي عمليات إثراء تم إعدادها على التصدير.

تنسيق سجل التدقيق

تمثل كل رسالة سجل تدقيق تغييرا بدأه المستخدم إلى كيان قابل للتدقيق داخل تطبيق IoT Central. تتضمن المعلومات الواردة في الرسالة المصدرة ما يلي:

  • actor: معلومات حول المستخدم الذي قام بتعديل الكيان.
  • applicationId: معرف تطبيق IoT Central.
  • messageSource: مصدر الرسالة - audit.
  • messageType: نوع التغيير الذي حدث. واحد من: updated، ، created. deleted
  • updated: موجود فقط إذا كان messageType هو updated. يوفر المزيد من التفاصيل حول التحديث.
  • resource: تفاصيل الكيان المعدل.
  • schema: اسم وإصدار مخطط الحمولة.
  • deviceId: معرف الجهاز الذي تم تغييره.
  • enqueuedTime: الوقت الذي حدث فيه هذا التغيير في IoT Central.
  • enrichments: أي عمليات إثراء تم إعدادها على التصدير.

بالنسبة لناقل خدمة Microsoft Azure، يصدر IoT Central بيانات الرسائل الجديدة إلى قائمة انتظار ناقل خدمة Microsoft Azure أو الموضوع في الوقت الفعلي تقريبا. في خصائص المستخدم (يشار إليها أيضا باسم خصائص التطبيق) لكل رسالة، iotcentral-device-idiotcentral-application-idiotcentral-message-sourceيتم تضمين و و iotcentral-message-type تلقائيا.

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

الآن بعد أن عرفت كيفية التصدير إلى ناقل خدمة Microsoft Azure، فإن الخطوة التالية المقترحة هي تعلم التصدير إلى مراكز الأحداث.