Menyerap telemetri IoT Hub ke Azure Digital Twins

Artikel
01/03/2024

Panduan ini memandu melalui proses penulisan fungsi yang dapat menyerap telemetri perangkat dari IoT Hub dan mengirimkannya ke instans Azure Digital Twins.

Azure Digital Twins digerakkan dengan data dari perangkat IoT dan sumber lainnya. Sumber umum untuk data perangkat yang akan digunakan di Azure Digital Twins adalah IoT Hub.

Proses penyerapan data ke Azure Digital Twins adalah menyiapkan sumber daya komputasi eksternal, seperti fungsi yang dibuat dengan menggunakan Azure Functions. Fungsi menerima data dan menggunakan API DigitalTwins untuk mengatur properti atau mengaktifkan kejadian telemetri pada kembaran digital.

Dokumen panduan ini menjelaskan proses penulisan fungsi yang dapat menyerap telemetri perangkat dari IoT Hub.

Prasyarat

Sebelum melanjutkan dengan contoh ini, Anda harus menyiapkan sumber daya berikut sebagai prasyarat:

Hub IoT. Untuk petunjuknya, lihat bagian Membuat IoT Hub dari mulai cepat IoT Hub ini.
Instans Azure Digital Twins yang akan menerima telemetri perangkat Anda. Untuk petunjuk, lihat Menyiapkan instans dan autentikasi Azure Digital Twins.

Contoh skenario telemetri

Panduan ini menjelesakan cara mengirim pesan dari IoT Hub ke Azure Digital Twins, menggunakan fungsi di Azure. Ada banyak kemungkinan konfigurasi dan strategi pencocokan yang dapat Anda gunakan untuk mengirim pesan, tetapi contoh untuk artikel ini berisi bagian berikut:

Perangkat termostat di IoT Hub, dengan ID perangkat yang diketahui
Kembaran digital untuk mewakili perangkat, dengan ID yang cocok

Catatan

Contoh ini menggunakan kecocokan ID langsung antara ID perangkat dan ID kembaran digital yang sesuai, tetapi dimungkinkan untuk memberikan pemetaan yang lebih canggih dari perangkat ke kembaran perangkat (seperti dengan tabel pemetaan).

Setiap kali peristiwa telemetri suhu dikirim oleh perangkat termostat, fungsi memproses telemetri dan Temperature properti kembar digital harus diperbarui. Skenario ini digambarkan dalam diagram di bawah ini:

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.

Menambahkan model dan twin

Di bagian ini, Anda akan menyiapkan digital twin di Azure Digital Twins yang akan mewakili perangkat termostat dan akan diperbarui dengan informasi dari IoT Hub.

Untuk membuat kembaran jenis termostat, Anda harus terlebih dahulu mengunggah model termostat ke instans, yang menjelaskan properti termostat dan akan digunakan nanti untuk membuat kembaran.

Modelnya terlihat seperti ini:

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

Untuk mengunggah model ini ke instans kembaran, jalankan perintah Azure CLI berikut, yang mengunggah model di atas sebagai JSON sebaris. Anda dapat menjalankan perintah di Azure Cloud Shell di browser Anda (gunakan lingkungan Bash), atau di komputer Anda jika Anda memiliki CLI yang diinstal secara lokal. Ada satu tempat penampung untuk nama host instans (Anda juga dapat menggunakan nama ramah instans dengan sedikit penurunan performa).

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

Catatan

Jika Anda menggunakan apa pun selain Cloud Shell di lingkungan Bash, Anda mungkin perlu menghindari karakter tertentu di JSON sebaris sehingga diurai dengan benar. Untuk informasi selengkapnya, lihat Menggunakan karakter khusus di shell yang berbeda.

Anda kemudian harus membuat satu kembaran menggunakan model ini. Gunakan perintah berikut untuk membuat kembaran termostat bernama termostat67, dan atur 0,0 sebagai nilai suhu awal. Ada satu tempat penampung untuk nama host instans (Anda juga dapat menggunakan nama ramah instans dengan sedikit penurunan performa).

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

Saat kembaran berhasil dibuat, output CLI dari perintah akan terlihat seperti ini:

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

Membuat fungsi Azure

Di bagian ini, Anda akan membuat fungsi Azure untuk mengakses Azure Digital Twins dan memperbarui kembar berdasarkan peristiwa telemetri perangkat IoT yang diterimanya. Ikuti langkah-langkah di bawah ini untuk membuat dan menerbitkan fungsi.

Pertama, buat proyek Azure Functions baru dari jenis pemicu Event Grid.

Anda dapat melakukan ini menggunakan Visual Studio (untuk instruksi, lihat Mengembangkan Azure Functions menggunakan Visual Studio), Visual Studio Code (untuk instruksi, lihat Membuat fungsi C# di Azure menggunakan Visual Studio Code), atau Azure CLI (untuk instruksi, lihat Membuat fungsi C# di Azure dari baris perintah).
Tambahkan paket berikut ke proyek Anda (Anda dapat menggunakan manajer paket Visual Studio NuGet, atau perintah tambahkan paket dotnet dalam alat baris perintah).

Buat fungsi dalam proyek yang disebut IoTHubtoTwins.cs. Tempelkan kode berikut ke dalam file fungsi:

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

Simpan kode fungsi Anda.

Terbitkan proyek dengan fungsi IoTHubtoTwins.cs ke aplikasi fungsi di Microsoft Azure.

Untuk petunjuk tentang cara menerbitkan fungsi menggunakan Visual Studio, lihat Mengembangkan Azure Functions menggunakan Visual Studio. Untuk petunjuk tentang cara menerbitkan fungsi menggunakan Visual Studio Code, lihat Membuat fungsi C# di Azure menggunakan Visual Studio Code. Untuk instruksi tentang cara menerbitkan fungsi menggunakan Azure CLI, lihat Membuat fungsi C# di Azure dari baris perintah.

Setelah proses penerbitan fungsi selesai, Anda dapat menggunakan perintah Azure CLI ini untuk memverifikasi bahwa penerbitan berhasil. Ada tempat penampung untuk grup sumber daya Anda, dan nama aplikasi fungsi Anda. Perintah akan mencetak informasi tentang fungsi IoTHubToTwins .

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

Mengkonfigurasi aplikasi fungsi

Untuk mengakses Azure Digital Twins, aplikasi fungsi Anda memerlukan identitas terkelola yang ditetapkan sistem dengan izin untuk mengakses instans Azure Digital Twins Anda. Anda akan menyiapkannya di bagian ini, dengan menetapkan peran akses untuk fungsi dan mengonfigurasi pengaturan aplikasi sehingga dapat mengakses instans Azure Digital Twins Anda.

Jalankan perintah berikut di Azure Cloud Shell atau Azure CLI lokal.

Catatan

Bagian ini harus diselesaikan oleh pengguna Azure yang memiliki izin untuk mengelola akses pengguna ke sumber daya Azure, termasuk memberikan dan mendelegasikan izin. Peran umum yang memenuhi persyaratan ini adalah Pemilik, Admin akun, atau kombinasi Kontributor dan Administrator Akses Pengguna. Untuk mengetahui informasi selengkapnya tentang persyaratan izin untuk peran Azure Digital Twins, lihat Menyiapkan instans dan autentikasi.

Menetapkan peran akses

Fungsi Azure mengharuskan token pembawa diteruskan ke fungsi Azure. Untuk memastikan bahwa token pembawa diteruskan, beri aplikasi fungsi peran Pemilik Data Azure Digital Twins untuk instans Azure Digital Twins Anda, yang akan memberi aplikasi fungsi izin untuk melakukan aktivitas data plane di instans tersebut.

Gunakan perintah berikut untuk membuat identitas yang dikelola sistem untuk fungsi Anda (jika fungsi sudah memilikinya, perintah ini akan mencetak detailnya). Perhatikan bidang principalId dalam output. Anda akan menggunakan ID ini untuk merujuk ke fungsi sehingga Anda dapat memberikannya izin pada langkah berikutnya.
```
az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
```

Gunakan nilai principalId dalam perintah berikut untuk memberi fungsi peran Pemilik Data Azure Digital Twins untuk instans Azure Digital Twins Anda.

az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"

Mengonfigurasi pengaturan aplikasi

Selanjutnya, buat URL instans Azure Digital Twins Anda dapat diakses oleh fungsi Anda dengan mengatur variabel lingkungan untuk instans tersebut.

Tip

URL instans Azure Digital Twins dibuat dengan menambahkan https:// ke awal nama host instans Anda. Untuk melihat nama host, bersama dengan semua properti instans Anda, jalankan az dt show --dt-name <your-Azure-Digital-Twins-instance>.

Perintah berikut mengatur variabel lingkungan untuk URL instans yang akan digunakan fungsi Anda setiap kali fungsi tersebut perlu mengakses instans.

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

Koneksi fungsi ke IoT Hub

Di bagian ini, Anda akan menyiapkan fungsi sebagai tujuan kejadian untuk data perangkat hub IoT. Menyiapkan fungsi Anda dengan cara ini akan memastikan bahwa data dari perangkat termostat di IoT Hub akan dikirim ke fungsi Azure untuk diproses.

Gunakan perintah CLI berikut untuk membuat langganan peristiwa yang akan digunakan IoT Hub untuk mengirim data peristiwa ke fungsi IoTHubtoTwins . Ada tempat penampung bagi Anda untuk memasukkan nama untuk langganan peristiwa, dan ada juga tempat penampung bagi Anda untuk memasukkan ID langganan, grup sumber daya, nama hub IoT, dan nama aplikasi fungsi Anda.

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

Output akan menampilkan informasi tentang langganan peristiwa yang telah dibuat. Anda dapat mengonfirmasi bahwa operasi berhasil diselesaikan dengan memverifikasi provisioningState nilai dalam hasil:

"provisioningState": "Succeeded",

Uji dengan data IoT yang disimulasikan

Anda dapat menguji fungsi ingress baru Anda dengan menggunakan simulator perangkat dari Koneksi solusi end-to-end. Proyek DeviceSimulator berisi perangkat termostat simulasi yang mengirim data suhu sampel. Untuk menyiapkan simulator perangkat, ikuti langkah-langkah berikut:

Navigasikan ke repositori proyek sampel end-to-end Azure Digital Twins. Dapatkan proyek sampel di komputer Anda dengan memilih tombol Telusuri kode di bawah judul. Ini akan membawa Anda ke repositori GitHub untuk sampel, yang dapat Anda unduh sebagai .zip dengan memilih tombol Kode diikuti dengan Unduh ZIP.

Ini akan mengunduh folder .zip ke komputer Anda sebagai digital-twins-samples-main.zip. Buka zip folder dan ekstrak file. Anda akan menggunakan folder proyek DeviceSimulator .
Mendaftarkan perangkat simulasi dengan IoT Hub
Mengonfigurasi dan menjalankan simulasi

Setelah menyelesaikan langkah-langkah ini, Anda harus memiliki jendela konsol proyek yang berjalan dan mengirim data telemetri perangkat yang disimulasikan ke hub IoT Anda.

Screenshot of the output from the device simulator project.

Memvalidasi hasil

Saat menjalankan simulator perangkat di atas, nilai suhu kembar digital termostat Anda akan berubah. Di CLI Azure, jalankan perintah berikut untuk melihat nilai suhu. Ada satu tempat penampung untuk nama host instans (Anda juga dapat menggunakan nama ramah instans dengan sedikit penurunan performa).

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

Catatan

Jika Anda menggunakan apa pun selain Cloud Shell di lingkungan Bash, Anda mungkin perlu melepaskan $ karakter dalam kueri secara berbeda sehingga diurai dengan benar. Untuk informasi selengkapnya, lihat Menggunakan karakter khusus di shell yang berbeda.

Output Anda harus menunjukkan detail kembar termostat67, termasuk nilai suhu, seperti ini:

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

Untuk melihat Temperature perubahan nilai, berulang kali jalankan perintah kueri di atas.

Langkah berikutnya

Baca tentang masuk dan keluarnya data dengan Azure Digital Twins:

Ingress dan egress data

Menyerap telemetri IoT Hub ke Azure Digital Twins

Prasyarat

Contoh skenario telemetri

Menambahkan model dan twin

Membuat fungsi Azure

Mengkonfigurasi aplikasi fungsi

Menetapkan peran akses

Mengonfigurasi pengaturan aplikasi

Koneksi fungsi ke IoT Hub

Uji dengan data IoT yang disimulasikan

Memvalidasi hasil

Langkah berikutnya

Sumber Daya Tambahan: