تصدير بيانات IoT إلى Webhook

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

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

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

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

تلميح

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

إشعار

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

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

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

إعداد وجهة تصدير Webhook

بالنسبة لوجهات Webhook، يصدر IoT Central البيانات في الوقت الفعلي تقريبا. البيانات الموجودة في نص الرسالة بنفس تنسيق Event Hubs وService Bus.

إنشاء وجهة Webhook

يمكنك تصدير البيانات إلى نقطة نهاية HTTP Webhook متاحة للجمهور. يمكنك إنشاء نقطة نهاية Webhook اختبار باستخدام RequestBin. يقيد RequestBin الطلب عند الوصول إلى حد الطلب:

1. انتقل إلى RequestBin.

2. حدد Create a RequestBin.

3. سجل الدخول باستخدام إحدى الطرق المتوفرة.

4. انسخ عنوان URL ل RequestBin الخاص بك يمكنك استخدام عنوان URL هذا عند اختبار تصدير البيانات.

لإنشاء وجهة Azure Data Explorer في IoT Central في صفحة تصدير البيانات:

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

2. حدد Webhook كنوع الوجهة.

3. الصق عنوان URL لرد الاتصال لنقطة نهاية Webhook. يمكنك اختياريا تكوين تخويل Webhook وإضافة عناوين مخصصة.

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

4. حدد حفظ.

مثال على تكوين OAuth 2.0

يوضح هذا المثال كيفية تكوين وجهة Webhook لاستخدام تطبيق Azure Function المحمي باستخدام تسجيل الدخول إلى Microsoft Entra:

الإعدادات	مثال	ملاحظات
نوع الوجهة	خطاف الويب
عنوان URL لرد الاتصال	https://myapp.azurewebsites.net/api/HttpExample	عنوان URL للدالة.
التصريح	OAuth 2.0
عنوان URL للرمز المميز	https://login.microsoftonline.com/your-tenant-id/oauth2/v2.0/token	عنوان URL الذي يجب استخدامه لاسترداد رمز مميز. يمكنك العثور على هذه القيمة في تطبيق الوظائف: المصادقة > نقاط > نهاية موفر > هوية Microsoft الخاصة بك OAuth 2.0 نقطة نهاية الرمز المميز (v2)
معرف العميل	your-client-id	معرف العميل لتطبيق الوظائف الخاص بك. يمكنك العثور على هذه القيمة في تطبيق الوظائف: مصادقة > معرف تطبيق موفر > هوية Microsoft (العميل)
سر العميل	your-client-secret	سر العميل لتطبيق الوظائف الخاص بك. يمكنك العثور على هذه القيمة في تطبيق الوظائف: مصادقة > شهادات وأسرار موفر > هوية Microsoft
الجمهور	‏‫غير متوفر‬	فارغ إذا كنت تستخدم تطبيق الوظائف.
النطاق	https://your-client-id/.default	نطاق الرمز المميز. بالنسبة إلى Function App، استخدم قيمة معرف العميل.**
نوع محتوى طلب الرمز المميز	تلقائي

قد تتطلب وجهات خطاف الويب الأخرى قيما مختلفة لهذه الإعدادات.

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

الآن بعد أن أصبح لديك وجهة لتصدير بياناتك إليها، قم بإعداد تصدير البيانات في تطبيق 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 D2C.

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

توضح القصاصة البرمجية التالية كيفية إضافة الخاصية 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);
}

Java

private static void sendTemperatureTelemetry() {
  String telemetryName = "temperature";
  String telemetryPayload = String.format("{\"%s\": %f}", telemetryName, temperature);

  Message message = new Message(telemetryPayload);
  message.setContentEncoding(StandardCharsets.UTF_8.name());
  message.setContentTypeFinal("application/json");
  message.setProperty("iothub-creation-time-utc", Instant.now().toString());

  deviceClient.sendEventAsync(message, new MessageIotHubEventCallback(), message);
  log.debug("My Telemetry: Sent - {\"{}\": {}°C} with message Id {}.", telemetryName, temperature, message.getMessageId());
  temperatureReadings.put(new Date(), temperature);
}

C#‎

private async Task SendTemperatureTelemetryAsync()
{
  const string telemetryName = "temperature";

  string telemetryPayload = $"{{ \"{telemetryName}\": {_temperature} }}";
  using var message = new Message(Encoding.UTF8.GetBytes(telemetryPayload))
  {
      ContentEncoding = "utf-8",
      ContentType = "application/json",
  };
  message.Properties.Add("iothub-creation-time-utc", DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ"));
  await _deviceClient.SendEventAsync(message);
  _logger.LogDebug($"Telemetry: Sent - {{ \"{telemetryName}\": {_temperature}°C }}.");
}

Python

async def send_telemetry_from_thermostat(device_client, telemetry_msg):
    msg = Message(json.dumps(telemetry_msg))
    msg.custom_properties["iothub-creation-time-utc"] = datetime.now(timezone.utc).isoformat()
    msg.content_encoding = "utf-8"
    msg.content_type = "application/json"
    print("Sent message")
    await device_client.send_message(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، فإن الخطوة التالية المقترحة هي تعلم التصدير إلى مراكز الأحداث.