استيعاب القياس عن بعد ل IoT Hub في Azure Digital Twins

مقالة
01/03/2024

يستعرض هذا الدليل عملية كتابة دالة يمكنها استيعاب بيانات تتبع الاستخدام للجهاز من IoT Hub وإرسالها إلى مثيل Azure Digital Twins.

يتم تشغيل Azure Digital Twins ببيانات من أجهزة IoT ومصادر أخرى. مصدر شائع لبيانات الجهاز لاستخدامها في Azure Digital Twins هو IoT Hub.

تتمثل عملية استيعاب البيانات في Azure Digital Twins في إعداد مورد حساب خارجي، مثل دالة تم إنشاؤها باستخدام Azure Functions. تتلقى الدالة البيانات وتستخدم واجهات برمجة تطبيقات DigitalTwins لتعيين الخصائص أو إطلاق أحداث القياس عن بعد على التوائم الرقمية وفقا لذلك.

يستعرض هذا المستند الإرشادي عملية كتابة دالة يمكنها استيعاب بيانات تتبع الاستخدام للجهاز من IoT Hub.

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

قبل المتابعة مع هذا المثال، ستحتاج إلى إعداد الموارد التالية كمتطلبات أساسية:

IoT Hub. للحصول على الإرشادات، راجع قسم إنشاء مركز IoT في التشغيل السريع ل IoT Hub هذا.
مثيل Azure Digital Twins الذي سيتلقى بيانات تتبع الاستخدام لجهازك. للحصول على إرشادات، راجع إعداد مثيل Azure Digital Twins والمصادقة.

مثال لسيناريو بيانات تتبع الاستخدام

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

جهاز ترموستات في IoT Hub، مع معرف جهاز معروف
توأم رقمي لتمثيل الجهاز بمعرف مطابق

إشعار

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

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

Diagram of IoT Hub device sending Temperature telemetry to a function in Azure, which updates a Temperature property on a twin in Azure Digital Twins.

إضافة نموذج وتوائم

في هذا القسم، ستقوم بإعداد توأم رقمي في Azure Digital Twins يمثل جهاز منظم الحرارة وسيتم تحديثه بمعلومات من IoT Hub.

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

سيبدو النموذج كما يلي:

{
    "@id": "dtmi:contosocom:DigitalTwins:Thermostat;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;3",
    "contents": [
      {
        "@type": "Property",
        "name": "Temperature",
        "schema": "double"
      }
    ]
  }

لتحميل هذا النموذج إلى مثيل التوأم الخاص بك، قم بتشغيل أمر Azure CLI التالي، والذي يقوم بتحميل النموذج أعلاه ك JSON مضمن. يمكنك تشغيل الأمر في Azure Cloud Shell في المستعرض الخاص بك (استخدم بيئة Bash)، أو على جهازك إذا كان لديك CLI مثبتا محليا. هناك عنصر نائب واحد لاسم مضيف المثيل (يمكنك أيضا استخدام الاسم المألوف للمثيل مع انخفاض طفيف في الأداء).

az dt model create --dt-name <instance-hostname-or-name> --models '{  "@id": "dtmi:contosocom:DigitalTwins:Thermostat;1",  "@type": "Interface",  "@context": "dtmi:dtdl:context;2",  "contents": [    {      "@type": "Property",      "name": "Temperature",      "schema": "double"    }  ]}'

إشعار

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

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

az dt twin create  --dt-name <instance-hostname-or-name> --dtmi "dtmi:contosocom:DigitalTwins:Thermostat;1" --twin-id thermostat67 --properties '{"Temperature": 0.0}'

عند إنشاء التوأم بنجاح، يجب أن يبدو إخراج CLI من الأمر كما يلي:

{
  "$dtId": "thermostat67",
  "$etag": "W/\"0000000-9735-4f41-98d5-90d68e673e15\"",
  "$metadata": {
    "$model": "dtmi:contosocom:DigitalTwins:Thermostat;1",
    "Temperature": {
      "lastUpdateTime": "2021-09-09T20:32:46.6692326Z"
    }
  },
  "Temperature": 0.0
}

إنشاء دالة Azure

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

أولا، قم بإنشاء مشروع Azure Functions جديد من نوع مشغل Event Grid.

يمكنك القيام بذلك باستخدام Visual Studio (للحصول على إرشادات، راجع تطوير وظائف Azure باستخدام Visual Studio)، أو Visual Studio Code (للحصول على إرشادات، راجع إنشاء دالة C# في Azure باستخدام Visual Studio Code)، أو Azure CLI (للحصول على إرشادات، راجع إنشاء دالة C# في Azure من سطر الأوامر).
أضف الحزم التالية إلى مشروعك (يمكنك استخدام مدير حزمة Visual Studio NuGet، أو الأمر dotnet add package في أداة سطر الأوامر).

إنشاء دالة داخل المشروع تسمى IoTHubtoTwins.cs. الصق التعليمات البرمجية التالية في ملف الدالة:

using System;
using Azure;
using System.Net.Http;
using Azure.Core.Pipeline;
using Azure.DigitalTwins.Core;
using Azure.Identity;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using Azure.Messaging.EventGrid;

namespace IotHubtoTwins
{
    public class IoTHubtoTwins
    {
        private static readonly string adtInstanceUrl = Environment.GetEnvironmentVariable("ADT_SERVICE_URL");
        private static readonly HttpClient httpClient = new HttpClient();

        [FunctionName("IoTHubtoTwins")]
        // While async void should generally be used with caution, it's not uncommon for Azure function apps, since the function app isn't awaiting the task.
#pragma warning disable AZF0001 // Suppress async void error
        public async void Run([EventGridTrigger] EventGridEvent eventGridEvent, ILogger log)
#pragma warning restore AZF0001 // Suppress async void error
        {
            if (adtInstanceUrl == null) log.LogError("Application setting \"ADT_SERVICE_URL\" not set");

            try
            {
                // Authenticate with Digital Twins
                var cred = new DefaultAzureCredential();
                var client = new DigitalTwinsClient(new Uri(adtInstanceUrl), cred);
                log.LogInformation($"ADT service client connection created.");
            
                if (eventGridEvent != null && eventGridEvent.Data != null)
                {
                    log.LogInformation(eventGridEvent.Data.ToString());

                    // <Find_device_ID_and_temperature>
                    JObject deviceMessage = (JObject)JsonConvert.DeserializeObject(eventGridEvent.Data.ToString());
                    string deviceId = (string)deviceMessage["systemProperties"]["iothub-connection-device-id"];
                    var temperature = deviceMessage["body"]["Temperature"];
                    // </Find_device_ID_and_temperature>

                    log.LogInformation($"Device:{deviceId} Temperature is:{temperature}");

                    // <Update_twin_with_device_temperature>
                    var updateTwinData = new JsonPatchDocument();
                    updateTwinData.AppendReplace("/Temperature", temperature.Value<double>());
                    await client.UpdateDigitalTwinAsync(deviceId, updateTwinData);
                    // </Update_twin_with_device_temperature>
                }
            }
            catch (Exception ex)
            {
                log.LogError($"Error in ingest function: {ex.Message}");
            }
        }
    }
}

احفظ التعليمات البرمجية للدالة.

انشر المشروع باستخدام الدالة IoTHubtoTwins.cs إلى تطبيق دالة في Azure.

للحصول على إرشادات حول كيفية نشر الدالة باستخدام Visual Studio، راجع تطوير وظائف Azure باستخدام Visual Studio. للحصول على إرشادات حول كيفية نشر الدالة باستخدام Visual Studio Code، راجع إنشاء دالة C# في Azure باستخدام Visual Studio Code. للحصول على إرشادات حول كيفية نشر الدالة باستخدام Azure CLI، راجع إنشاء دالة C# في Azure من سطر الأوامر.

بمجرد اكتمال عملية نشر الدالة، يمكنك استخدام أمر Azure CLI هذا للتحقق من نجاح النشر. هناك عناصر نائبة لمجموعة الموارد واسم تطبيق الوظائف. سيقوم الأمر بطباعة معلومات حول الدالة IoTHubToTwins .

az functionapp function show --resource-group <your-resource-group> --name <your-function-app> --function-name IoTHubToTwins

تكوين تطبيق الوظائف

للوصول إلى Azure Digital Twins، يحتاج تطبيق الوظائف إلى هوية مدارة معينة من قبل النظام مع أذونات للوصول إلى مثيل Azure Digital Twins. ستقوم بإعداد ذلك في هذا القسم، عن طريق تعيين دور وصول للوظيفة وتكوين إعدادات التطبيق بحيث يمكنه الوصول إلى مثيل Azure Digital Twins.

قم بتشغيل الأوامر التالية في Azure Cloud Shell أو Azure CLI محلي.

إشعار

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

تعيين دور وصول

تتطلب دالة Azure تمرير رمز مميز للحامل إليه. للتأكد من تمرير الرمز المميز للحامل، امنح تطبيق الدالة دور مالك بيانات Azure Digital Twins لمثيل Azure Digital Twins، والذي سيمنح تطبيق الوظيفة الإذن لتنفيذ أنشطة مستوى البيانات على المثيل.

استخدم الأمر التالي لإنشاء هوية مدارة من قبل النظام لوظيفتك (إذا كانت الدالة تحتوي بالفعل على واحدة، فسيطبع هذا الأمر تفاصيلها). لاحظ الحقل في principalId الإخراج. ستستخدم هذا المعرف للإشارة إلى الدالة بحيث يمكنك منحها أذونات في الخطوة التالية.
```
az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
```
principalId استخدم القيمة في الأمر التالي لإعطاء الوظيفة دور مالك بيانات Azure Digital Twins لمثيل Azure Digital Twins.
```
az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"
```

تكوين إعدادات التطبيق

بعد ذلك، اجعل عنوان URL لمثيل Azure Digital Twins الخاص بك قابلا للوصول إلى وظيفتك عن طريق تعيين متغير بيئة له.

تلميح

يتم إجراء عنوان URL لمثيل Azure Digital Twins عن طريق إضافة https:// إلى بداية اسم مضيف المثيل الخاص بك. لمشاهدة اسم المضيف، جنبا إلى جنب مع جميع خصائص المثيل الخاص بك، قم بتشغيل az dt show --dt-name <your-Azure-Digital-Twins-instance>.

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

az functionapp config appsettings set --resource-group <your-resource-group> --name <your-function-app-name> --settings "ADT_SERVICE_URL=https://<your-Azure-Digital-Twins-instance-host-name>"

الاتصال الدالة إلى IoT Hub

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

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

az eventgrid event-subscription create --name <name-for-hub-event-subscription> --event-delivery-schema eventgridschema --source-resource-id /subscriptions/<your-subscription-ID>/resourceGroups/<your-resource-group>/providers/Microsoft.Devices/IotHubs/<your-IoT-hub> --included-event-types Microsoft.Devices.DeviceTelemetry --endpoint-type azurefunction --endpoint /subscriptions/<your-subscription-ID>/resourceGroups/<your-resource-group>/providers/Microsoft.Web/sites/<your-function-app>/functions/IoTHubtoTwins

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

"provisioningState": "Succeeded",

اختبار مع بيانات IoT المحاكاة

يمكنك اختبار وظيفة الدخول الجديدة باستخدام جهاز محاكاة من الاتصال حل شامل. يحتوي مشروع DeviceSimulator على جهاز منظم حرارة محاكاة يرسل عينة من بيانات درجة الحرارة. لإعداد محاكي الجهاز، اتبع الخطوات التالية:

انتقل إلى مستودع مشروع نموذج Azure Digital Twins الشامل. احصل على نموذج المشروع على جهازك عن طريق تحديد الزر Browse code أسفل العنوان. سينقلك هذا إلى مستودع GitHub للعينات، والتي يمكنك تنزيلها ك .zip عن طريق تحديد الزر Code متبوعا بتنزيل ZIP.

سيؤدي هذا إلى تنزيل مجلد .zip إلى جهازك ك digital-twins-samples-main.zip. قم بفك ضغط المجلد واستخراج الملفات. ستستخدم مجلد مشروع DeviceSimulator .
تسجيل جهاز المحاكاة باستخدام IoT Hub
تكوين وتشغيل المحاكاة

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

Screenshot of the output from the device simulator project.

التحقق من صحة النتائج

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

az dt twin query --query-command "SELECT * FROM digitaltwins WHERE \$dtId = 'thermostat67'" --dt-name <instance-hostname-or-name>

إشعار

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

يجب أن يظهر الإخراج الخاص بك تفاصيل التوأم thermostat67، بما في ذلك قيمة درجة الحرارة، مثل هذا:

{
  "result": [
    {
      "$dtId": "thermostat67",
      "$etag": "W/\"dbf2fea8-d3f7-42d0-8037-83730dc2afc5\"",
      "$metadata": {
        "$model": "dtmi:contosocom:DigitalTwins:Thermostat;1",
        "Temperature": {
          "lastUpdateTime": "2021-06-03T17:05:52.0062638Z"
        }
      },
      "Temperature": 70.20518558807913
    }
  ]
}

لمشاهدة Temperature تغيير القيمة، قم بتشغيل أمر الاستعلام أعلاه بشكل متكرر.

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

اقرأ عن دخول البيانات والخروج باستخدام Azure Digital Twins:

دخول البيانات والخروج

استيعاب القياس عن بعد ل IoT Hub في Azure Digital Twins

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

مثال لسيناريو بيانات تتبع الاستخدام

إضافة نموذج وتوائم

إنشاء دالة Azure

تكوين تطبيق الوظائف

تعيين دور وصول

تكوين إعدادات التطبيق

الاتصال الدالة إلى IoT Hub

اختبار مع بيانات IoT المحاكاة

التحقق من صحة النتائج

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

الموارد الإضافية