モジュールツインの監視

2025-06-10

適用対象: IoT Edge 1.5

重要

IoT Edge 1.5 LTS は、サポートされているリリースです。 IoT Edge 1.4 LTS は、2024 年 11 月 12 日をもってサポートが終了しています。以前のリリースの場合は、「IoT Edge を更新する」を参照してください。

Azure IoT Hub のモジュールツインを使用すると、IoT Edge デプロイの接続性と正常性を監視できます。モジュールツインは、実行中のモジュールのパフォーマンスに関する情報を IoT ハブに格納します。 IoT Edge エージェントと IoT Edge ハブランタイムモジュールは、それぞれ独自のモジュールツイン ($edgeAgentと$edgeHub) を維持します。

$edgeAgent には、IoT Edge エージェント、IoT Edge ハブランタイムモジュール、およびカスタムモジュールに関する正常性と接続データがあります。 IoT Edge エージェントは、モジュールをデプロイして監視し、接続状態を Azure IoT ハブに報告します。
$edgeHub には、デバイスで実行されている IoT Edge ハブと Azure IoT Hub の間の通信に関するデータがあります。これには、ダウンストリームデバイスからの受信メッセージの処理が含まれます。 IoT Edge ハブは、Azure IoT Hub と IoT Edge デバイスとモジュール間の通信を処理します。

データは、モジュールツインの JSON 構造でメタデータ、タグ、および必要なプロパティセットと報告されるプロパティセットに編成されます。 deployment.json ファイルで指定する必要なプロパティがモジュールツインにコピーされます。 IoT Edge エージェントと IoT Edge ハブではそれぞれ、モジュールに対する報告されたプロパティが更新されます。

同様に、deployment.json ファイル内のカスタムモジュールに指定する必要なプロパティは、そのモジュールツインにコピーされますが、ソリューションによって報告されるプロパティ値が提供されます。

この記事では、Azure portal、Azure CLI、Visual Studio Code でモジュールツインを確認する方法について説明します。デバイスによるデプロイの受信状況を監視する方法については、「IoT Edge デプロイの監視」を参照してください。モジュールツインの概要については、 IoT Hub でのモジュールツインの理解と使用に関するページを参照してください。

ヒント

IoT Edge デバイスが IoT ハブから切断されると、ランタイムモジュールの報告されるプロパティが古くなる可能性があります。モジュールに $edgeAgent を実行して、接続が失われたかどうかを確認します。

ランタイムモジュールツインを監視する

デプロイの接続の問題をトラブルシューティングするには、IoT Edge エージェントと IoT Edge ハブのランタイムモジュールツインを確認してから、その他のモジュールにドリルダウンします。

IoT Edge エージェントのモジュールツインを監視する

この JSON では、ほとんどのセクションが折りたたまれている Visual Studio Code の $edgeAgent モジュールツインを示しています。

{
  "deviceId": "Windows109",
  "moduleId": "$edgeAgent",
  "etag": "AAAAAAAAAAU=",
  "deviceEtag": "NzgwNjA1MDUz",
  "status": "enabled",
  "statusUpdateTime": "0001-01-01T00:00:00Z",
  "connectionState": "Disconnected",
  "lastActivityTime": "0001-01-01T00:00:00Z",
  "cloudToDeviceMessageCount": 0,
  "authenticationType": "sas",
  "x509Thumbprint": {
    "primaryThumbprint": null,
    "secondaryThumbprint": null
  },
  "version": 53,
  "properties": {
    "desired": { "···" },
    "reported": {
      "schemaVersion": "1.0",
      "version": { "···" },
      "lastDesiredStatus": { "···" },
      "runtime": { "···" },
      "systemModules": {
        "edgeAgent": { "···" },
        "edgeHub": { "···" }
      },
      "lastDesiredVersion": 5,
      "modules": {
        "SimulatedTemperatureSensor": { "···" }
      },
      "$metadata": { "···" },
      "$version": 48
    }
  }
}

この JSON には、次のセクションがあります。

メタデータ - 接続データがあります。 IoT Edge エージェントの接続状態は、デバイスからクラウド (D2C) メッセージに適用され、IoT Edge エージェントが D2C メッセージを送信しないため、常に "Disconnected" されます。
プロパティ - desired サブセクションと reported サブセクションがあります。
Properties.desired - (折りたたまれて表示される) deployment.jsonファイルで設定される期待されるプロパティ値。
Properties.reported - IoT Edge エージェントによって報告された最新のプロパティ値。

properties.desiredセクションとproperties.reported セクションの構造は似ていますが、スキーマ、バージョン、ランタイム情報のメタデータも含まれています。また、modulesなどのカスタムモジュールのSimulatedTemperatureSensor セクションと、systemModulesおよび$edgeAgentランタイムモジュール用の$edgeHub セクションもあります。

報告されたプロパティ値を目的の値と比較して不一致を見つけ、問題のトラブルシューティングに役立つ切断を特定します。値を比較するときは、調査中のプロパティの$lastUpdatedセクションで、metadata報告された値を確認します。

トラブルシューティングを行うときは、次のプロパティを確認してください。

exitcode - ゼロ以外の値は、障害が発生してモジュールが停止したことを意味します。エラーコード 137 または 143 は、モジュールが意図的に停止状態に設定されている場合に使用されます。
lastStartTimeUtc - コンテナーが最後に開始されたときの DateTime を表示します。コンテナーが開始されていない場合、この値は 0001-01-01T00:00:00Z です。
lastExitTimeUtc - コンテナーが最後に完了したときの DateTime を表示します。コンテナーが実行中で、停止されなかった場合、この値は 0001-01-01T00:00:00Z になります。

runtimeStatus - 次のいずれかの値があります。

値	説明
不明	デプロイが作成されるまでの既定の状態。
バックオフ	モジュールは開始するようにスケジュールされていますが、実行されていません。この値は、再起動するモジュールに役立ちます。障害が発生したモジュールがクールオフ期間中に再起動を待機している場合、モジュールはバックオフ状態になります。
実行中	モジュールが実行されています。
不健康	正常性プローブチェックがエラーまたはタイムアウトになりました。
停止	モジュールが正常に終了しました (終了コードが 0)。
失敗	モジュールは、エラー終了コード (ゼロ以外) で終了しました。モジュールは、再起動ポリシーに応じて、この状態からバックオフに戻ることができます。この状態は、モジュールに回復不可能なエラーがあることを意味します。エラーは、Microsoft Monitoring Agent (MMA) がモジュールを再起動できないときに発生し、新しいデプロイが必要になります。

詳細については、 EdgeAgent の報告されるプロパティに関するページを参照してください。

IoT Edge ハブのモジュールツインを監視する

次の JSON に、ほとんどのセクションが折りたたまれている、Visual Studio Code の $edgeHub モジュールツインを示します。

{
  "deviceId": "Windows109",
  "moduleId": "$edgeHub",
  "etag": "AAAAAAAAAAU=",
  "deviceEtag": "NzgwNjA1MDU2",
  "status": "enabled",
  "statusUpdateTime": "0001-01-01T00:00:00Z",
  "connectionState": "Connected",
  "lastActivityTime": "0001-01-01T00:00:00Z",
  "cloudToDeviceMessageCount": 0,
  "authenticationType": "sas",
  "x509Thumbprint": {
    "primaryThumbprint": null,
    "secondaryThumbprint": null
  },
  "version": 102,
    "properties": {
      "desired": { "···" },
      "reported": {
        "schemaVersion": "1.0",
        "version": { "···" },
      "lastDesiredVersion": 5,
      "lastDesiredStatus": { "···" },
      "clients": {
        "Windows109/SimulatedTemperatureSensor": {
          "status": "Disconnected",
          "lastConnectedTimeUtc": "2020-04-08T21:42:42.1743956Z",
          "lastDisconnectedTimeUtc": "2020-04-09T07:02:42.1398325Z"
        }
      },
      "$metadata": { "···" },
      "$version": 97
    }
  }
}

JSON は上から順に、次のセクションで表すことができます。

Metadata - 接続データが含まれます。
Properties - desired および reported サブセクションが含まれます。
Properties.desired - (折りたたまれて表示されています) deployment.json ファイル内に、演算子で設定されたプロパティ値が必要です。
Properties.reported - IoT Edge ハブによって報告された最新のプロパティ値。

ダウンストリームデバイスで問題が発生している場合は、まずこのデータを確認します。

カスタムモジュールツインを監視する

IoT Edge エージェントモジュールツインは、カスタムモジュールの接続に関する情報を保持します。カスタムモジュールのモジュールツインには、主にソリューションのデータが格納されます。 deployment.json ファイルで定義する必要なプロパティはモジュールツインに表示され、モジュールは必要に応じて報告されるプロパティ値を更新できます。

Azure IoT Hub Device SDK で好みのプログラミング言語を使用して、モジュールのアプリケーションコードに基づいてモジュールツインの報告されたプロパティ値を更新します。次の手順では、Azure SDK for .NET と SimulatedTemperatureSensor モジュールのコードを使用します。

CreateFromEnvironmentAsync メソッドを使用して ModuleClient のインスタンスを作成します。
GetTwinAsync メソッドを使用して、モジュールツインのプロパティを取得します。
SetDesiredPropertyUpdateCallbackAsync メソッドを使用して、必要なプロパティへの変更をキャッチするコールバックを含むリスナーを作成します。
コールバックメソッドで、 UpdateReportedPropertiesAsync メソッドを使用してモジュールツインの報告されたプロパティを更新し、設定するプロパティ値の TwinCollection を渡します。

モジュールツインにアクセスする

Azure IoT Hub、Visual Studio Code、または Azure CLI のモジュールツインの JSON を確認します。

Azure IoT Hub 上で監視する

モジュールツインの JSON を表示します。

Azure Portal にサインインし、IoT Hub に移動します。
[デバイス管理] メニューで、[デバイス] を選択します。
監視する対象のモジュールを含む IoT Edge デバイスの [デバイス ID] を選択します。
[モジュール] タブからモジュール名を選択して、上部のメニューバーから [モジュール ID ツイン] を選択します。

"このモジュールのモジュール ID が存在しません" というメッセージが表示された場合、このエラーは、ID を最初に作成したバックエンドソリューションが使用できないことを意味します。

Visual Studio Code 上でモジュールツインを監視する

モジュールツインをレビューして編集します。

Azure IoT Edge 拡張機能と Azure IoT Hub 拡張機能がまだインストールされていない場合は、インストールします。 "Visual Studio Code 用の Azure IoT Edge Tools" 拡張機能は、メンテナンスモードになっています。
エクスプローラーで、Azure IoT Hub を展開し、監視するモジュールを含むデバイスを展開します。
モジュールを選択し、[ モジュールツインの編集] を選択します。モジュールツインの一時ファイルがコンピューターにダウンロードされ、Visual Studio Code で開きます。

変更を行った後、エディターのコードの上にある [モジュールツインの更新 ] を選択して、IoT ハブに保存します。

Visual Studio Code でモジュールツインを更新する方法を示すスクリーンショット。

Azure CLI 上でモジュールツインを監視する

az iot hub invoke-module-method コマンドを使用して IoT Edge エージェントに ping を実行して、IoT Edge が実行されているかどうかを確認します。

az iot hub module-twin 構造では、以下のコマンドが提供されています。

az iot hub module-twin show - モジュールツインの定義を表示します。
az iot hub module-twin update - モジュールツインの定義を更新します。
az iot hub module-twin replace - モジュールツインの定義を対象の JSON に置き換えます。

ヒント

CLI コマンドを使用してランタイムモジュールをターゲットにするには、モジュール ID の $ 文字をエスケープすることが必要になる場合があります。次に例を示します。

az iot hub module-twin show -m '$edgeAgent' -n <hub name> -d <device name>

または:

az iot hub module-twin show -m \$edgeAgent -n <hub name> -d <device name>

次のステップ

組み込みのダイレクトメソッドを使用して EdgeAgent と通信する方法について説明します。

次の方法で共有

モジュール ツインの監視

ランタイム モジュール ツインを監視する

IoT Edge エージェントのモジュール ツインを監視する

IoT Edge ハブのモジュール ツインを監視する

カスタム モジュール ツインを監視する

モジュール ツインにアクセスする