IoT Hub telemetri verilerini Azure Digital Twins'e alma

Makale
01/03/2024

Bu kılavuz, IoT Hub'dan cihaz telemetrisi alabilen ve azure digital twins örneğine gönderebilen bir işlev yazma işleminde yol gösterir.

Azure Digital Twins, IoT cihazlarından ve diğer kaynaklardan alınan verilerle yönlendirilir. Azure Digital Twins'de kullanılacak cihaz verilerinin yaygın kaynaklarından biri IoT Hub'dır.

Azure Digital Twins'e veri alma işlemi, Azure İşlevleri kullanılarak yapılan bir işlev gibi bir dış işlem kaynağı ayarlamaktır. İşlev verileri alır ve DigitalTwins API'lerini kullanarak özellikleri ayarlar veya buna göre dijital ikizlerde telemetri olaylarını tetikler.

Bu nasıl yapılır belgesi, IoT Hub'dan cihaz telemetrisi alabilen bir işlev yazma işleminde yol gösterir.

Önkoşullar

Bu örnekle devam etmeden önce aşağıdaki kaynakları önkoşul olarak ayarlamanız gerekir:

Bir IoT hub'ı. Yönergeler için bu IoT Hub hızlı başlangıcının IoT Hub oluşturma bölümüne bakın.
Cihaz telemetrinizi alacak bir Azure Digital Twins örneği. Yönergeler için bkz . Azure Digital Twins örneği ve kimlik doğrulaması ayarlama.

Örnek telemetri senaryosu

Bu nasıl yapılır, Azure'da bir işlev kullanarak IoT Hub'dan Azure Digital Twins'e ileti göndermeyi özetler. İleti göndermek için kullanabileceğiniz birçok olası yapılandırma ve eşleştirme stratejisi vardır, ancak bu makalenin örneği aşağıdaki bölümleri içerir:

IoT Hub'da bilinen cihaz kimliğine sahip bir termostat cihazı
Eşleşen bir kimlikle cihazı temsil eden dijital ikiz

Dekont

Bu örnekte cihaz kimliği ile buna karşılık gelen bir dijital ikizin kimliği arasında basit bir kimlik eşleşmesi kullanılır, ancak cihazdan ikizine (eşleme tablosu gibi) daha karmaşık eşlemeler sağlamak mümkündür.

Termostat cihazı tarafından bir sıcaklık telemetri olayı gönderildiğinde, bir işlev telemetriyi işler ve Temperature dijital ikizin özelliği güncelleştirilmelidir. Bu senaryo aşağıdaki diyagramda özetlenmiştir:

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.

Model ve ikiz ekleme

Bu bölümde, Azure Digital Twins'de termostat cihazını temsil edecek ve IoT Hub'dan gelen bilgilerle güncelleştirilecek bir dijital ikiz ayarlayacaksınız.

Termostat türünde bir ikiz oluşturmak için öncelikle termostat modelini örneğinize yüklemeniz gerekir. Bu model termostat özelliklerini açıklar ve daha sonra ikizini oluşturmak için kullanılır.

Model şuna benzer:

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

Bu modeli ikiz örneğinize yüklemek için yukarıdaki modeli satır içi JSON olarak yükleyen aşağıdaki Azure CLI komutunu çalıştırın. Komutunu tarayıcınızda Azure Cloud Shell'de (Bash ortamını kullanın) veya CLI yerel olarak yüklüyse makinenizde çalıştırabilirsiniz. Örneğin ana bilgisayar adı için bir yer tutucu vardır (örneğin kolay adını performansta küçük bir düşüşle de kullanabilirsiniz).

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"    }  ]}'

Dekont

Bash ortamında Cloud Shell dışında bir şey kullanıyorsanız doğru şekilde ayrıştırmak için satır içi JSON'daki belirli karakterlerden kurtulmanız gerekebilir. Daha fazla bilgi için bkz . Farklı kabuklarda özel karakterler kullanma.

Ardından bu modeli kullanarak bir ikiz oluşturmanız gerekir. Thermostat67 adlı bir termostat ikizini oluşturmak ve 0,0 değerini ilk sıcaklık değeri olarak ayarlamak için aşağıdaki komutu kullanın. Örneğin ana bilgisayar adı için bir yer tutucu vardır (örneğin kolay adını performansta küçük bir düşüşle de kullanabilirsiniz).

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

İkiz başarıyla oluşturulduğunda komutundan alınan CLI çıkışı şuna benzer olmalıdır:

{
  "$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 işlevini oluşturma

Bu bölümde, Azure Digital Twins'e erişmek ve aldığı IoT cihaz telemetri olaylarını temel alarak ikizleri güncelleştirmek için bir Azure işlevi oluşturacaksınız. İşlevi oluşturmak ve yayımlamak için aşağıdaki adımları izleyin.

İlk olarak, Event Grid tetikleyici türüne sahip yeni bir Azure İşlevleri projesi oluşturun.

Bunu Visual Studio kullanarak yapabilirsiniz (yönergeler için bkz. Visual Studio kullanarak Azure İşlevleri geliştirme), Visual Studio Code (yönergeler için bkz. Visual Studio Code kullanarak Azure'da C# işlevi oluşturma) veya Azure CLI (yönergeler için bkz. Komut satırından Azure'da C# işlevi oluşturma).
Projenize aşağıdaki paketleri ekleyin (Visual Studio NuGet paket yöneticisini veya komut satırı aracında dotnet add package komutunu kullanabilirsiniz).

Proje içinde IoTHubtoTwins.cs adlı bir işlev oluşturun. aşağıdaki kodu işlev dosyasına yapıştırın:

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}");
            }
        }
    }
}

İşlev kodunuzu kaydedin.

IoTHubtoTwins.cs işleviyle projeyi Azure'daki bir işlev uygulamasında yayımlayın.

İşlevi Visual Studio kullanarak yayımlama yönergeleri için bkz. Visual Studio kullanarak Azure İşlevleri geliştirme. İşlevi Visual Studio Code kullanarak yayımlama yönergeleri için bkz. Visual Studio Code kullanarak Azure'da C# işlevi oluşturma. İşlevi Azure CLI kullanarak yayımlama yönergeleri için bkz. Komut satırından Azure'da C# işlevi oluşturma.

İşlevi yayımlama işlemi tamamlandıktan sonra, yayımlama işleminin başarılı olduğunu doğrulamak için bu Azure CLI komutunu kullanabilirsiniz. Kaynak grubunuz için yer tutucular ve işlev uygulamanızın adı vardır. komutu IoTHubToTwins işlevi hakkındaki bilgileri yazdırır .

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

İşlev uygulamasını yapılandırma

Azure Digital Twins'e erişmek için işlev uygulamanızın Azure Digital Twins örneğine erişme izinlerine sahip sistem tarafından atanan yönetilen bir kimliğe sahip olması gerekir. Bu bölümde, işlev için bir erişim rolü atayarak ve uygulama ayarlarını Azure Digital Twins örneğine erişebilecek şekilde yapılandırarak ayarlayacaksınız.

Azure Cloud Shell'de veya yerel bir Azure CLI'da aşağıdaki komutları çalıştırın.

Dekont

Bu bölüm, izin verme ve temsilci atama dahil olmak üzere Azure kaynaklarına kullanıcı erişimini yönetme izinleri olan bir Azure kullanıcısı tarafından tamamlanmalıdır. Bu gereksinimi karşılayan yaygın roller Sahip, Hesap yöneticisi veya Kullanıcı Erişimi Yönetici istrator ve Katkıda Bulunan birleşimidir. Azure Digital Twins rolleri için izin gereksinimleri hakkında daha fazla bilgi için bkz . Örnek ve kimlik doğrulaması ayarlama.

Erişim rolü atama

Azure işlevine bir taşıyıcı belirtecin geçirilmesi gerekir. Taşıyıcı belirtecinin geçirildiğinden emin olmak için işlev uygulamasına Azure Digital Twins örneğiniz için Azure Digital Twins Veri Sahibi rolünü verin. Bu rol işlev uygulamasına örnekte veri düzlemi etkinlikleri gerçekleştirme izni verir.

İşleviniz için sistem tarafından yönetilen bir kimlik oluşturmak için aşağıdaki komutu kullanın (işlevin zaten bir kimliği varsa, bu komut ayrıntılarını yazdırır). Çıktıdaki principalId alanı not alın. Sonraki adımda işleve izin verebilmek için işleve başvurmak için bu kimliği kullanacaksınız.
```
az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
```
İşleve principalIdAzure Digital Twins örneğinizin Azure Digital Twins Veri Sahibi rolünü vermek için aşağıdaki komuttaki değeri kullanın.
```
az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"
```

Uygulama ayarlarını yapılandırma

Ardından, Azure Digital Twins örneğinizin URL'sini işleviniz için bir ortam değişkeni ayarlayarak erişilebilir hale getirin.

Bahşiş

Azure Digital Twins örneğinin URL'si, örneğinizin ana bilgisayar adının başına https:// eklenerek oluşturulur. Ana bilgisayar adını ve örneğinizin tüm özelliklerini görmek için komutunu çalıştırın az dt show --dt-name <your-Azure-Digital-Twins-instance>.

Aşağıdaki komut, örneğinize erişmesi gereken her durumda işlevinizin kullanacağı örneğinizin URL'si için bir ortam değişkeni ayarlar.

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>"

İşlevi IoT Hub'a Bağlan

Bu bölümde, işlevinizi IoT hub cihaz verileri için bir olay hedefi olarak ayarlayacaksınız. İşlevinizi bu şekilde ayarlamak IoT Hub'daki termostat cihazından verilerin işlenmek üzere Azure işlevine gönderilmesini sağlar.

IoT Hub'ın IoTHubtoTwins işlevine olay verileri göndermek için kullanacağı bir olay aboneliği oluşturmak için aşağıdaki CLI komutunu kullanın. Olay aboneliği için bir ad girmeniz için bir yer tutucu ve ayrıca abonelik kimliğinizi, kaynak grubunuzu, IoT hub adınızı ve işlev uygulamanızın adını girmeniz için yer tutucular da vardır.

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

Çıkışta, oluşturulan olay aboneliğiyle ilgili bilgiler gösterilir. Sonuçtaki değeri doğrulayarak provisioningState işlemin başarıyla tamamlandığını onaylayabilirsiniz:

"provisioningState": "Succeeded",

Sanal IoT verileriyle test edin

Yeni giriş işlevinizi uçtan uca çözümden Bağlan cihaz simülatörünü kullanarak test edebilirsiniz. DeviceSimulator projesi, örnek sıcaklık verilerini gönderen bir simülasyon termostat cihazı içerir. Cihaz simülatörünü ayarlamak için şu adımları izleyin:

Azure Digital Twins uçtan uca örnek proje deposuna gidin. Başlığın altındaki Koda gözat düğmesini seçerek makinenizdeki örnek projeyi alın. Bu işlem sizi örnekler için GitHub deposuna götürür. Bu depoyu Kod düğmesini ve ardından ZIP İndir'i seçerek .zip olarak indirebilirsiniz.

Bu işlem makinenize digital-twins-samples-main.zip olarak bir .zip klasörü indirir. Klasörün sıkıştırmasını açın ve dosyaları ayıklayın. DeviceSimulator proje klasörünü kullanacaksınız.
Sanal cihazı IoT Hub'a kaydetme
Benzetimi yapılandırma ve çalıştırma

Bu adımları tamamladıktan sonra, çalışan ve sanal cihaz telemetri verilerini IoT hub'ınıza gönderen bir proje konsol penceresine sahip olmanız gerekir.

Screenshot of the output from the device simulator project.

Sonuçları doğrulama

Cihaz simülatörünü yukarıda çalıştırırken termostat dijital ikizinizin sıcaklık değeri değişecektir. Sıcaklık değerini görmek için Azure CLI'da aşağıdaki komutu çalıştırın. Örneğin ana bilgisayar adı için bir yer tutucu vardır (örneğin kolay adını performansta küçük bir düşüşle de kullanabilirsiniz).

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

Dekont

Bash ortamında Cloud Shell dışında bir şey kullanıyorsanız doğru şekilde ayrıştırmak için sorgudaki karakterden farklı bir şekilde kaçış $ yapmanız gerekebilir. Daha fazla bilgi için bkz . Farklı kabuklarda özel karakterler kullanma.

Çıkışınızda termostat67 ikizinin sıcaklık değeri de dahil olmak üzere aşağıdaki gibi ayrıntıları gösterilmelidir:

{
  "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
    }
  ]
}

Değer değişikliğini Temperature görmek için yukarıdaki sorgu komutunu tekrar tekrar çalıştırın.

Sonraki adımlar

Azure Digital Twins ile veri girişi ve çıkışı hakkında bilgi edinin:

Veri girişi ve çıkış

IoT Hub telemetri verilerini Azure Digital Twins'e alma

Önkoşullar

Örnek telemetri senaryosu

Model ve ikiz ekleme

Azure işlevini oluşturma

İşlev uygulamasını yapılandırma

Erişim rolü atama

Uygulama ayarlarını yapılandırma

İşlevi IoT Hub'a Bağlan

Sanal IoT verileriyle test edin

Sonuçları doğrulama

Sonraki adımlar

Ek kaynaklar