IoT Hub テレメトリを Azure Digital Twins に取り込む

2025-04-23

このガイドでは、IoT Hub からデバイステレメトリを取り込んで Azure Digital Twins のインスタンスに送信できる関数を記述するプロセスについて説明します。

Azure Digital Twins は、IoT デバイスやその他のソースからのデータで駆動されます。 Azure Digital Twins で使用するデバイスデータの一般的なソースは IoT Hub です。

Azure Digital Twins にデータを取り込むプロセスは、 Azure Functions を使用して作成された関数などの外部コンピューティングリソースを設定することです。この関数はデータを受け取り、DigitalTwins API を使用してプロパティを設定したり、それに応じてデジタルツインでテレメトリイベントを発生させたりします。

このハウツードキュメントでは、IoT Hub からデバイステレメトリを取り込むことができる関数を記述するプロセスについて説明します。

[前提条件]

この例を続行する前に、前提条件として次のリソースを設定する必要があります。

IoT ハブ手順については、この IoT Hub クイックスタートの「IoT Hub の作成」セクションを参照してください。
デバイステレメトリを受信する Azure Digital Twins インスタンス。手順については、「 Azure Digital Twins インスタンスと認証の設定」を参照してください。

テレメトリシナリオの例

このハウツーでは、Azure の関数を使用して、IoT Hub から Azure Digital Twins にメッセージを送信する方法について説明します。メッセージの送信に使用できる構成と照合方法は多数ありますが、この記事の例には次の部分が含まれています。

既知のデバイス ID を持つ IoT Hub のサーモスタットデバイス
ID が一致するデバイスを表すデジタルツイン

注

この例では、デバイス ID と対応するデジタルツインの ID の間で単純な ID 一致を使用しますが、デバイスからツインへのより高度なマッピング (マッピングテーブルなど) を提供できます。

サーモスタットデバイスが温度テレメトリイベントを送信するたびに、関数によってテレメトリが処理され、デジタルツインの Temperature プロパティが更新されます。このシナリオの概要を次の図に示します。

IoT Hub デバイスが Azure 内の関数に温度テレメトリを送信し、その関数が Azure Digital Twins のツインの温度プロパティを更新する図。

モデルとツインを追加する

このセクションでは、サーモスタットデバイスを表し、IoT Hub からの情報で更新されるデジタルツインを Azure Digital Twins で設定します。

サーモスタット型ツインを作成するには、最初にサーモスタットモデルをインスタンスにアップロードする必要があります。このモデルはサーモスタットのプロパティを記述し、後でツインを作成するために使用されます。

モデルは次のようになります。

{
    "@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 がローカルにインストールされている場合は、ご利用のコンピューター上でも実行できます。インスタンスのホスト名にはプレースホルダーが 1 つあります (インスタンスのフレンドリ名を使用することもできますが、パフォーマンスが若干低下します)。

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

注

Bash 環境で Cloud Shell 以外のものを使用している場合は、インライン JSON 内の特定の文字をエスケープして、正しく解析することが必要になる場合があります。詳細については、さまざまなシェルでの特殊文字の使用に関するページを参照してください。

その後、このモデルを使用して 1 つのツインを作成する必要があります。次のコマンドを使用して thermostat67 という名前のサーモスタットツインを作成し、初期温度値として 0.0 を設定します。インスタンスのホスト名にはプレースホルダーが 1 つあります (インスタンスのフレンドリ名を使用することもできますが、パフォーマンスが若干低下します)。

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 Digital Twins にアクセスし、受信した IoT デバイステレメトリイベントに基づいてツインを更新する Azure 関数を作成します。関数を作成して発行するには、次の手順を実行します。

まず、Event Grid トリガーの種類の新しい Azure Functions プロジェクトを作成します。

これを行うには、Visual Studio (手順については、「Visual Studioを使用する Azure Functions の開発」を参照)、Visual Studio Code (手順については、「Visual Studio Code を使用して Azure に C# 関数を作成する」を参照)、または Azure CLI (手順については、Azure でコマンドラインから C# 関数を作成する」を参照) を使用します。
次のパッケージをプロジェクトに追加します (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 を使用して関数を発行する方法については、「Visual Studio を使用する Azure Functions の開発」を参照してください。 Visual Studio Code を使用して関数を発行する方法については、「Visual Studio Code を使用して Azure に C# 関数を作成する」を参照してください。 Azure CLI を使用して関数を発行する方法については、「Azure でコマンドラインから C# 関数を作成する」を参照してください。

関数の発行プロセスが完了したら、この Azure CLI コマンドを使用して、発行が成功したことを確認できます。リソースグループのプレースホルダーと関数アプリの名前があります。このコマンドは 、IoTHubToTwins 関数に関する情報を出力します。

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

Function App を構成する

Azure Digital Twins にアクセスするには、関数アプリには、Azure Digital Twins インスタンスにアクセスするためのアクセス許可を持つシステム割り当てマネージド ID が必要です。このセクションでは、関数のアクセスロールを割り当て、Azure Digital Twins インスタンスにアクセスできるようにアプリケーション設定を構成して設定します。

Azure Cloud Shell またはローカル Azure CLI で次のコマンドを実行します。

注

アクセス許可の付与や委任など、Azure リソースへのユーザーアクセスを管理するアクセス許可を持つ Azure ユーザーは、このセクションを完了する必要があります。この要件を満たす一般的なロールは、所有者、アカウント管理者、ユーザーアクセス管理者と共同作成者の組み合わせです。 Azure Digital Twins のロールのアクセス許可要件の詳細については、インスタンスと認証の設定に関する記事を参照してください。

アクセスロールを割り当てる

Azure 関数には、ベアラートークンを渡す必要があります。ベアラートークンが確実に渡されるようにするには、関数アプリに Azure Digital Twins インスタンスの Azure Digital Twins データ所有者 ロールを付与します。このロールにより、インスタンスでデータプレーンアクティビティを実行するアクセス許可が関数アプリに付与されます。

次のコマンドを使用して、関数のシステムマネージド ID を作成します (関数に既に存在する場合、このコマンドはその詳細を出力します)。出力内の principalId フィールドをメモします。この ID は、次の手順でアクセス許可を付与できるように、関数を参照するために使用します。
```
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"
```

アプリケーション設定の構成

次に、環境変数を設定することで、関数から Azure Digital Twins インスタンスの URL にアクセスできるようにします。

ヒント

Azure Digital Twins インスタンスの URL を作成するには、インスタンスのホスト名の先頭に 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 Hub デバイスデータのイベントの送信先として関数を設定します。この方法で関数を設定すると、IoT Hub のサーモスタットデバイスからのデータが処理のために Azure 関数に確実に送信される場合があります。

次の CLI コマンドを使用して、IoT Hub が IoTHubtoTwins 関数にイベントデータを送信するために使用するイベントサブスクリプションを作成します。イベントサブスクリプションの名前を入力するためのプレースホルダーだけでなく、サブスクリプション ID、リソースグループ、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 のエンドツーエンドのサンプルプロジェクトリポジトリに移動します。タイトルの下にある [コードの参照 ] ボタンを選択して、コンピューター上のサンプルプロジェクトを取得します。このボタンをクリックすると、サンプルの GitHub リポジトリに移動します。このリポジトリは、[ コード ] ボタンを選択し、[ ZIP のダウンロード] を選択して .zip としてダウンロードできます。

この選択により、digital-twins-samples-main.zipとして .zip フォルダーがコンピューターにダウンロード されます 。フォルダーを解凍し、ファイルを抽出します。ファイルが抽出されたら、 DeviceSimulator プロジェクトフォルダーを使用します。
シミュレートされたデバイスを IoT Hub に登録する
シミュレーションを構成して実行する

これらの手順を完了すると、プロジェクトコンソールウィンドウが実行され、シミュレートされたデバイステレメトリデータが IoT ハブに送信されます。

デバイスシミュレータープロジェクトからの出力のスクリーンショット。

結果を検証する

前に示したように、コンソールウィンドウでデバイスシミュレーターを実行すると、サーモスタットデジタルツインの温度値が変化します。 Azure CLI で、次のコマンドを実行して温度の値を確認します。インスタンスのホスト名にはプレースホルダーが 1 つあります (インスタンスのフレンドリ名を使用することもできますが、パフォーマンスが若干低下します)。

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

注

Bash 環境で Cloud Shell 以外のものを使用している場合は、クエリ内の $ 文字を別の方法でエスケープして、正しく解析することが必要になる場合があります。詳細については、さまざまなシェルでの特殊文字の使用に関するページを参照してください。

出力には、次のような温度値を含む 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 を使用したデータのイングレスとエグレスについて説明します。

データの流入と流出