IoT Edgeでモジュールをデプロイし、ルートを確立する方法について説明します

対象： IoT Edge 1.5

重要

IoT Edge 1.5 LTS は、サポートされているリリースです。 IoT Edge 1.4 LTS は 2024 年 11 月 12 日に終了しました。以前のリリースを使用している場合は、「Update IoT Edgeを参照してください。

各IoT Edgeデバイスは、IoT Edge ランタイムの一部である $edgeAgent と $edgeHub という少なくとも 2 つのモジュールを実行します。 IoT Edge デバイスは、異なるプロセスに対して複数のモジュールを実行できます。配置マニフェストを使用して、インストールするモジュールと、それらを連携するように設定する方法をデバイスに指示します。

デプロイマニフェストは、次の内容が記述された JSON ドキュメントです。

IoT Edge エージェント モジュールツイン。これには、次の 3 つのコンポーネントが含まれます。
- デバイスで実行される各モジュールのコンテナーイメージ。
- モジュールイメージを持つプライベートコンテナーレジストリを使用するための資格情報。
- 各モジュールの作成方法と管理方法について説明します。
IoT Edge hub モジュールツイン。これには、モジュール間とIoT Hub間のメッセージの流れ方が含まれます。
任意の追加モジュールツインの希望プロパティ (省略可能)。

すべてのIoT Edgeデバイスには配置マニフェストが必要です。新しくインストールされたIoT Edge ランタイムには、有効なマニフェストを設定するまでエラーコードが表示されます。

Azure IoT Edgeチュートリアルでは、Azure IoT Edge ポータルのウィザードを使用して配置マニフェストを作成します。 REST または IoT Hub Service SDK を使用して、プログラムで配置マニフェストを適用することもできます。詳細については、「IoT Edge デプロイの概要を参照してください。

配置マニフェストの作成

配置マニフェストは、必要なプロパティで設定されたモジュールツインの一覧です。インストールするモジュールとその設定方法をIoT Edgeデバイスまたはデバイスグループに通知します。配置マニフェストには、必要なプロパティがモジュールツインごとに記述されています。 IoT Edgeデバイスは、各モジュールの報告されたプロパティを報告します。

すべての配置マニフェストには、との 2 つのモジュールが必要です。これらのモジュールは、IoT Edge デバイスとその上で実行されているモジュールを管理するIoT Edge ランタイムの一部です。これらのモジュールの詳細については、「IoT Edge ランタイムとそのアーキテクチャを理解するを参照してください。

2 つのランタイムモジュールに加えて、IoT Edge デバイスで実行するモジュールを最大 50 個追加できます。

IoT Edge ランタイム ($edgeAgent および $edgeHub) のみを持つ配置マニフェストが有効です。

配置マニフェストでは、次の形式が使用されます。

{
  "modulesContent": {
    "$edgeAgent": { // required
      "properties.desired": {
        // desired properties of the IoT Edge agent
        // includes the image URIs of all deployed modules
        // includes container registry credentials
      }
    },
    "$edgeHub": { //required
      "properties.desired": {
        // desired properties of the IoT Edge hub
        // includes the routing information between modules and to IoT Hub
      }
    },
    "module1": {  // optional
      "properties.desired": {
        // desired properties of module1
      }
    },
    "module2": {  // optional
      "properties.desired": {
        // desired properties of module2
      }
    }
  }
}

モジュールの構成

IoT Edge ランタイムがデプロイにモジュールをインストールする方法を定義します。 IoT Edge エージェントは、IoT Edge デバイスのインストール、更新、状態レポートを管理するランタイムコンポーネントです。そのため、モジュールツインには、すべてのモジュールの構成と管理の情報があります。この情報には、IoT Edge エージェント自体の構成パラメーターが含まれます。

プロパティでは、次の形式が使用されます。

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": {
          "settings":{
            "registryCredentials":{
              // let the IoT Edge agent use container images that aren't public
            }
          }
        },
        "systemModules": {
          "edgeAgent": {
            // configuration and management details
          },
          "edgeHub": {
            // configuration and management details
          }
        },
        "modules": {
          "module1": {
            // configuration and management details
          },
          "module2": {
            // configuration and management details
          }
        }
      }
    },
    "$edgeHub": { ... },
    "module1": { ... },
    "module2": { ... }
  }
}

IoT Edge エージェントスキーマバージョン 1.1 IoT Edgeバージョン 1.0.10 でリリースされ、モジュールの起動順序を設定できます。バージョン 1.0.10 以降を実行しているIoT Edge展開には、スキーマバージョン 1.1 を使用します。

モジュールの構成と管理

IoT Edge デバイスで実行するモジュールと、IoT Edge エージェントの必要なプロパティの一覧でモジュールを設定および管理する方法を定義します。

必要なプロパティを含めることができるか含める必要があるプロパティの完全な一覧については、「IoT Edge エージェントとIoT Edge ハブのプロパティを参照してください。

次に例を示します。

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": { ... },
        "systemModules": {
          "edgeAgent": { ... },
          "edgeHub": { ... }
        },
        "modules": {
          "module1": {
            "version": "1.0",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 2,
            "settings": {
              "image": "myacr.azurecr.io/module1:latest",
              "createOptions": "{}"
            }
          },
          "module2": { ... }
        }
      }
    },
    "$edgeHub": { ... },
    "module1": { ... },
    "module2": { ... }
  }
}

すべてのモジュールには、モジュールイメージを含む設定プロパティ、コンテナーレジストリ内のコンテナーイメージのアドレス、および起動時にイメージを設定するための createOptions があります。詳細については、「IoT Edge モジュールのコンテナー作成オプションを構成する方法を参照してください。

edgeHub モジュールとカスタムモジュールには、IoT Edge エージェントに管理方法を指示する 3 つのプロパティもあります。

状態: モジュールが最初にデプロイされたときに実行または停止するかどうか。必須。
RestartPolicy: IoT Edge エージェントが停止した場合にモジュールを再起動するタイミングとタイミング。エラーなしでモジュールが停止した場合、モジュールは自動的に再起動されません。詳細については、Docker Docs のコンテナーの自動開始に関するページを参照してください。必須。
StartupOrder: IoT Edge バージョン 1.0.10 で導入されました。 IoT Edge エージェントが最初にデプロイされたときにモジュールを開始するために使用する順序。この順序では整数が使用されます。スタートアップ値が 0 のモジュールが最初に開始され、次に数値が大きくなります。 $edgeAgent モジュールは常に最初に起動するため、スタートアップ値を持ちません。省略可能。

IoT Edge エージェントは、スタートアップ値の順序でモジュールを起動しますが、各モジュールの開始が完了してから次のモジュールが開始されるまで待機しません。

起動順序は、一部のモジュールが他のモジュールに依存している場合に役立ちます。たとえば、 edgeHub モジュールを最初に起動して、他のモジュールの起動時にメッセージをルーティングする準備が整う場合があります。または、データを送信するモジュールを開始する前に、ストレージモジュールを開始することもできます。ただし、他のモジュールの障害を処理するように、常にモジュールを設計してください。コンテナーは、いつでも、および任意の回数で停止および再起動できます。
注

モジュールのプロパティを変更すると、そのモジュールが再起動されます。たとえば、次のプロパティを変更すると再起動が発生します。
- モジュールイメージ
- Docker の作成オプション
- 環境変数
- 再起動ポリシー
- イメージのプルポリシー
- バージョン
- 起動順序
モジュールのプロパティを変更しない場合、モジュールの再起動はトリガーされません。

ルートの宣言

IoT Edge ハブは、モジュール、IoT Hub、ダウンストリームデバイス間の通信を管理します。 $edgeHub モジュールツインには、展開内でのメッセージの移動方法を定義すると呼ばれる必要なプロパティがあります。同じデプロイで複数のルートを設定できます。

次の構文を使用して、 $edgeHub 必要なプロパティでルートを宣言します。

{
  "modulesContent": {
    "$edgeAgent": { ... },
    "$edgeHub": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "routes": {
          "route1": "FROM <source> WHERE <condition> INTO <sink>",
          "route2": {
            "route": "FROM <source> WHERE <condition> INTO <sink>",
            "priority": 0,
            "timeToLiveSecs": 86400
          }
        },
        "storeAndForwardConfiguration": {
          "timeToLiveSecs": 10
        }
      }
    },
    "module1": { ... },
    "module2": { ... }
  }
}

IoT Edge バージョン 1.0.10 でリリースされた IoT Edge ハブスキーマバージョン 1 を使用すると、ルートの優先順位付けと有効期間を設定できます。バージョン 1.0.10 以降を実行しているIoT Edge展開には、スキーマバージョン 1.1 を使用します。

各ルートには、受信メッセージのソースと送信メッセージのシンクが必要です。条件は省略可能であり、メッセージをフィルター処理できます。

重要なメッセージを最初に処理するために、ルートに優先順位を割り当てます。この機能は、アップストリーム接続が弱いか制限されていて、標準のテレメトリメッセージよりも重要なデータに優先順位を付ける必要がある場合に役立ちます。

ソース

ソースでは、メッセージがどこから送信されるのかを指定します。 IoT Edgeは、モジュールまたはダウンストリームデバイスからメッセージをルーティングできます。

IoT SDK を使用すると、モジュールはクラスを使用して、メッセージの特定の出力キューを設定できます。出力キューは必須ではありませんが、複数のルートを管理するのに役立ちます。ダウンストリームデバイスでは、ioT SDK の DeviceClient クラスを使用して、IoT Hubにメッセージを送信するのと同様に、IoT Edge ゲートウェイデバイスにメッセージを送信します。詳細については、「Azure IoT Hub SDK の理解と使用」を参照してください。

source プロパティでは、次のいずれかの値を使用できます。

ソース	説明
`/*`	任意のモジュールまたはダウンストリームデバイスからのすべての device-to-cloud メッセージまたはツイン変更通知。
`/twinChangeNotifications`	任意のモジュールまたはダウンストリームデバイスから送信されるツイン変更 (reported プロパティ)。
`/messages/*`	何らかの出力を通じてまたは出力なしでモジュールによって送信される、またはダウンストリームデバイスによって送信される device-to-cloud メッセージ。
`/messages/modules/*`	出力の一部または指定なしでモジュールを通じて送信される、デバイスからクラウドへのメッセージ。
`/messages/modules/<moduleId>/*`	何らかの出力を通じて、または出力なしで特定のモジュールによって送信される任意の device-to-cloud メッセージ。
`/messages/modules/<moduleId>/outputs/*`	特定のモジュールから何らかの出力を介して送信されたデバイスからクラウドへのメッセージ。
`/messages/modules/<moduleId>/outputs/<output>`	特定の出力を介して特定のモジュールによって送信されるデバイスからクラウドへのメッセージ。

条件

条件は、ルートの宣言では省略可能です。ソースからシンクにすべてのメッセージを渡すには、 WHERE 句を省略します。または、IoT Hub クエリ言語を使用して、条件を満たすメッセージまたはメッセージの種類をフィルター処理します。 IoT Edge ルートでは、ツインタグまたはプロパティに基づくメッセージのフィルター処理はサポートされていません。

IoT Edgeモジュール間で移動するメッセージは、デバイスとAzure IoT Hub間のメッセージと同じ形式を使用します。すべてのメッセージは JSON 形式を使用し、 systemProperties、 appProperties、および本文パラメーターを持っています。

次の構文を使用して、次の 3 つのパラメーターのいずれかに関するクエリを作成します。

システムプロパティ: または
アプリケーションプロパティ:
本文プロパティ:

メッセージプロパティのクエリを作成する方法の例については、「 Device-to-cloud message routes query expressions」を参照してください。

たとえば、ダウンストリームデバイスからゲートウェイデバイスに到着したメッセージをフィルター処理できます。モジュールから送信されるメッセージには、connectionModuleId と呼ばれるシステムプロパティが含まれます。ダウンストリームデバイスから直接IoT Hubにメッセージをルーティングし、モジュールメッセージを除外するには、次のルートを使用します。

FROM /messages/* WHERE NOT IS_DEFINED($connectionModuleId) INTO $upstream

シンク

シンクは、メッセージを送信する場所を定義します。メッセージを受信できるのはモジュールとIoT Hubだけです。メッセージを他のデバイスにルーティングすることはできません。シンクプロパティはワイルドカードをサポートしていません。

シンクプロパティでは、次のいずれかの値を使用できます。

シンク	説明
`$upstream`	メッセージをIoT Hubに送信する
`BrokeredEndpoint("/modules/<moduleId>/inputs/<input>")`	特定のモジュールの特定の入力にメッセージを送信する

IoT Edgeは、少なくとも 1 回保証を提供します。 IoT Edge ハブは、ルートがそのシンクにメッセージを配信できない場合に、メッセージをローカルに格納します。たとえば、IoT EdgeハブがIoT Hubに接続できない場合、またはターゲットモジュールが接続されていない場合です。

IoT Edge ハブは、storeAndForwardConfiguration.timeToLiveSecsのプロパティに設定された時間までのメッセージを格納します。

優先順位と有効期限

ルートを、ルートを定義する文字列として、またはルート文字列、優先度整数、および time-to-live 整数を持つオブジェクトとして宣言します。

オプション 1

"route1": "FROM <source> WHERE <condition> INTO <sink>",

オプション 2 (IoT Edge バージョン 1.0.10 IoT Edge ハブスキーマバージョン 1.1 で導入)

"route2": {
  "route": "FROM <source> WHERE <condition> INTO <sink>",
  "priority": 0,
  "timeToLiveSecs": 86400
}

優先度の値の範囲は 0 から 9 で、0 が最も高い優先度です。システムは、エンドポイントによってメッセージをキューに入れます。システムは、同じエンドポイントの優先度 1 のメッセージを処理する前に、特定のエンドポイントのすべての優先度 0 メッセージを処理します。同じエンドポイントの複数のルートが同じ優先順位を持つ場合、システムはメッセージを到着順に処理します。優先度を設定しない場合、ルートは最も低い優先度を使用します。

timeToLiveSecs プロパティは、直接設定しない限り、IoT Edge ハブの storeAndForwardConfiguration の値を使用します。値には正の整数を指定できます。

優先順位キューの管理方法の詳細については、「Route の優先度と有効期間に関するページを参照してください。

必要なプロパティの定義または更新

配置マニフェストは、IoT Edge デバイスにデプロイされた各モジュールの必要なプロパティを設定します。配置マニフェストに記載された必要なプロパティは、現在モジュールツインにある必要なプロパティをすべて上書きします。

配置マニフェストでモジュールツインの必要なプロパティを設定しない場合、IoT Hubモジュールツインは変更されません。代わりに、必要なプロパティをプログラムで設定します。

デバイスツインを変更できるのと同じメカニズムを使用して、モジュールツインを変更することもできます。詳細については、モジュールツイン開発者ガイドをご覧ください。

デプロイマニフェストの例

次の例は、有効な配置マニフェストドキュメントの外観を示しています。

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": {
          "type": "docker",
          "settings": {
            "minDockerVersion": "v1.25",
            "loggingOptions": "",
            "registryCredentials": {
              "ContosoRegistry": {
                "username": "myacr",
                "password": "<password>",
                "address": "myacr.azurecr.io"
              }
            }
          }
        },
        "systemModules": {
          "edgeAgent": {
            "type": "docker",
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-agent:1.5",
              "createOptions": "{}"
            }
          },
          "edgeHub": {
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 0,
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
              "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"443/tcp\":[{\"HostPort\":\"443\"}],\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}]}}}"
            }
          }
        },
        "modules": {
          "SimulatedTemperatureSensor": {
            "version": "1.5",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 2,
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.5",
              "createOptions": "{}"
            }
          },
          "filtermodule": {
            "version": "1.0",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 1,
            "env": {
              "tempLimit": {"value": "100"}
            },
            "settings": {
              "image": "myacr.azurecr.io/filtermodule:latest",
              "createOptions": "{}"
            }
          }
        }
      }
    },
    "$edgeHub": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "routes": {
          "sensorToFilter": {
            "route": "FROM /messages/modules/SimulatedTemperatureSensor/outputs/temperatureOutput INTO BrokeredEndpoint(\"/modules/filtermodule/inputs/input1\")",
            "priority": 0,
            "timeToLiveSecs": 1800
          },
          "filterToIoTHub": {
            "route": "FROM /messages/modules/filtermodule/outputs/output1 INTO $upstream",
            "priority": 1,
            "timeToLiveSecs": 1800
          }
        },
        "storeAndForwardConfiguration": {
          "timeToLiveSecs": 100
        }
      }
    }
  }
}

次のステップ

およびに含めることができる、または含める必要があるプロパティの完全な一覧については、IoT Edge エージェントと IoT Edge ハブのプロパティを参照してください。
IoT Edgeモジュールのしくみを理解したら、IoT Edge モジュールを開発するための要件とツールについて学習します。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-02-26