IoT Edge にモジュールをデプロイしてルートを確立する方法について説明します。Learn how to deploy modules and establish routes in IoT Edge

各 IoT Edge デバイスでは、$edgeAgent と $edgeHub という少なくとも 2 つのモジュールが実行されます。これらは IoT Edge ランタイムに含まれています。Each IoT Edge device runs at least two modules: $edgeAgent and $edgeHub, which are part of the IoT Edge runtime. IoT Edge デバイスは、任意の数のプロセスに対して複数の追加モジュールを実行できます。IoT Edge device can run multiple additional modules for any number of processes. インストールするモジュールとそれらを連携させるための構成方法をデバイスに伝えるには、配置マニフェストを使用します。Use a deployment manifest to tell your device which modules to install and how to configure them to work together.

デプロイ マニフェストは、次の内容が記述された JSON ドキュメントです。The deployment manifest is a JSON document that describes:

  • 3 つのコンポーネントを含む IoT Edge エージェント モジュール ツイン。The IoT Edge agent module twin, which includes three components.
    • デバイスで実行される各モジュールのコンテナー イメージ。The container image for each module that runs on the device.
    • モジュール イメージを含むプライベート コンテナー レジストリにアクセスするための資格情報。The credentials to access private container registries that contain module images.
    • 各モジュールの作成と管理の方法に関する指示。Instructions for how each module should be created and managed.
  • IoT Edge ハブ モジュール ツイン。モジュール間および最終的には IoT Hub へのメッセージ フローの方法が含まれます。The IoT Edge hub module twin, which includes how messages flow between modules and eventually to IoT Hub.
  • さらに別のモジュール ツインがある場合は、オプションとして、その必要なプロパティ。Optionally, the desired properties of any additional module twins.

配置マニフェストを使用してすべての IoT Edge デバイスを構成する必要があります。All IoT Edge devices must be configured with a deployment manifest. 新しくインストールされた IoT Edge ランタイムは、有効なマニフェストで構成されるまでエラー コードを報告します。A newly installed IoT Edge runtime reports an error code until configured with a valid manifest.

Azure IoT Edge チュートリアルでは、Azure IoT Edge ポータルでウィザードを使用することによってデプロイ マニフェストを作成します。In the Azure IoT Edge tutorials, you build a deployment manifest by going through a wizard in the Azure IoT Edge portal. また、REST または IoT Hub サービス SDK を使用して、プログラムでデプロイ マニフェストを適用することもできます。You can also apply a deployment manifest programmatically using REST or the IoT Hub Service SDK. 詳細については、IoT Edge のデプロイに関する記事を参照してください。For more information, see Understand IoT Edge deployments.

配置マニフェストの作成Create a deployment manifest

大まかに言えば、配置マニフェストとは、必要なプロパティを使用して構成されたモジュール ツインのリストです。At a high level, a deployment manifest is a list of module twins that are configured with their desired properties. インストールするモジュールとその構成方法は、配置マニフェストから IoT Edge デバイス (1 つまたは複数のデバイス) に伝えられます。A deployment manifest tells an IoT Edge device (or a group of devices) which modules to install and how to configure them. 配置マニフェストには、"desired プロパティ" (必要なプロパティ) がモジュール ツインごとに記述されています。Deployment manifests include the desired properties for each module twin. IoT Edge デバイスは、モジュールごとに "reported プロパティ" (レポートされるプロパティ) を返します。IoT Edge devices report back the reported properties for each module.

すべての配置マニフェストに、$edgeAgent$edgeHub という 2 つのモジュールが必要です。Two modules are required in every deployment manifest: $edgeAgent, and $edgeHub. これらのモジュールは、IoT Edge デバイスとそこで実行されるモジュールを管理する IoT Edge ランタイムの構成要素です。These modules are part of the IoT Edge runtime that manages the IoT Edge device and the modules running on it. これらのモジュールの詳細については、IoT Edge ランタイムとそのアーキテクチャの概要に関するページを参照してください。For more information about these modules, see Understand the IoT Edge runtime and its architecture.

この 2 つのランタイム モジュールに加え、独自のモジュールを 20 個まで追加して、IoT Edge デバイス上で動作させることができます。In addition to the two runtime modules, you can add up to 20 modules of your own to run on an IoT Edge device.

IoT Edge ランタイム (edgeAgent と edgeHub) さえ含まれていれば配置マニフェストは有効です。A deployment manifest that contains only the IoT Edge runtime (edgeAgent and edgeHub) is valid.

配置マニフェストの構造は次のとおりです。Deployment manifests follow this structure:

{
    "modulesContent": {
        "$edgeAgent": { // required
            "properties.desired": {
                // desired properties of the Edge agent
                // includes the image URIs of all modules
                // includes container registry credentials
            }
        },
        "$edgeHub": { //required
            "properties.desired": {
                // desired properties of the 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
            }
        },
        ...
    }
}

モジュールの構成Configure modules

デプロイに含まれるモジュールを IoT Edge ランタイムでどのようにインストールするかを定義します。Define how the IoT Edge runtime installs the modules in your deployment. IoT Edge エージェントは、IoT Edge デバイスのインストール、更新、状態レポートを管理するランタイム コンポーネントです。The IoT Edge agent is the runtime component that manages installation, updates, and status reporting for an IoT Edge device. そのため、$edgeAgent モジュール ツインには、すべてのモジュールの構成情報と管理情報が必要です。Therefore, the $edgeAgent module twin requires the configuration and management information for all modules. この情報には、IoT Edge エージェント自体の構成パラメーターが含まれます。This information includes the configuration parameters for the IoT Edge agent itself.

含めることができるプロパティおよび必須プロパティの完全な一覧については、IoT Edge エージェントおよび IoT Edge ハブのプロパティに関するページをご覧ください。For a complete list of properties that can or must be included, see Properties of the IoT Edge agent and IoT Edge hub.

$EdgeAgent プロパティは次の構造に従います。The $edgeAgent properties follow this structure:

"$edgeAgent": {
    "properties.desired": {
        "schemaVersion": "1.0",
        "runtime": {
            "settings":{
                "registryCredentials":{ // give the edge agent access to container images that aren't public
                    }
                }
            }
        },
        "systemModules": {
            "edgeAgent": {
                // configuration and management details
            },
            "edgeHub": {
                // configuration and management details
            }
        },
        "modules": {
            "module1": { // optional
                // configuration and management details
            },
            "module2": { // optional
                // configuration and management details
            }
        }
    }
},

ルートの宣言Declare routes

IoT Edge ハブは、モジュール、IoT ハブ、リーフ デバイス間の通信を管理します。The IoT Edge hub manages communication between modules, IoT Hub, and any leaf devices. そのため、$edgeHub モジュール ツインには、デプロイ内でのメッセージの受け渡し方法を宣言する、routes と呼ばれる必要なプロパティが含まれています。Therefore, the $edgeHub module twin contains a desired property called routes that declares how messages are passed within a deployment. 同じデプロイ内にルートを複数持たせることができます。You can have multiple routes within the same deployment.

ルートは、 $edgeHub の必要なプロパティで、次の構文を使用して宣言します。Routes are declared in the $edgeHub desired properties with the following syntax:

"$edgeHub": {
    "properties.desired": {
        "routes": {
            "route1": "FROM <source> WHERE <condition> INTO <sink>",
            "route2": "FROM <source> WHERE <condition> INTO <sink>"
        },
    }
}

ソースとシンクはすべてのルートに必要ですが、条件は、メッセージをフィルター処理するために使用できる省略可能な部分です。Every route needs a source and a sink, but the condition is an optional piece that you can use to filter messages.

sourceSource

ソースでは、メッセージがどこから送信されるのかを指定します。The source specifies where the messages come from. IoT Edge は、モジュールまたはリーフ デバイスからメッセージをルーティングすることができます。IoT Edge can route messages from modules or leaf devices.

IoT SDK を使用することにより、モジュールは、ModuleClient クラスを使用してメッセージの特定の出力キューを宣言することができます。Using the IoT SDKs, modules can declare specific output queues for their messages using the ModuleClient class. 出力キューは必要ではありませんが、複数のルートを管理するのに役立ちます。Output queues aren't necessary, but are helpful for managing multiple routes. リーフ デバイスは、IoT SDK の DeviceClient クラスを使用して、IoT Hub にメッセージを送信するのと同じ方法で IoT Edge ゲートウェイ デバイスにメッセージを送信することができます。Leaf devices can use the DeviceClient class of the IoT SDKs to send messages to IoT Edge gateway devices in the same way that they would send messages to IoT Hub. 詳細については、「Azure IoT Hub SDK の概要と使用方法」を参照してください。For more information, see Understand and use Azure IoT Hub SDKs.

ソース プロパティは、次のいずれかの値にすることができます。The source property can be any of the following values:

sourceSource 説明Description
/* 任意のモジュールまたはリーフ デバイスからのすべての device-to-cloud メッセージまたはツイン変更通知All device-to-cloud messages or twin change notifications from any module or leaf device
/twinChangeNotifications 任意のモジュールまたはリーフ デバイスから送信されるツイン変更 (reported プロパティ)Any twin change (reported properties) coming from any module or leaf device
/messages/* モジュールによって (なんらかの出力を通じてまたは出力なしで) 送信される、またはリーフ デバイスによって送信される device-to-cloud メッセージAny device-to-cloud message sent by a module through some or no output, or by a leaf device
/messages/modules/* 何らかの出力と共に、または出力なしでモジュールによって送信された、デバイスからクラウドへの任意のメッセージAny device-to-cloud message sent by a module through some or no output
/messages/modules/<moduleId>/* なんらかの出力を通じて、または出力なしで特定のモジュールによって送信される任意の device-to-cloud メッセージAny device-to-cloud message sent by a specific module through some or no output
/messages/modules/<moduleId>/outputs/* なんらかの出力を通じて特定のモジュールによって送信される任意の device-to-cloud メッセージAny device-to-cloud message sent by a specific module through some output
/messages/modules/<moduleId>/outputs/<output> 特定の出力を通じて特定のモジュールによって送信される任意の device-to-cloud メッセージAny device-to-cloud message sent by a specific module through a specific output

条件Condition

条件は、ルートの宣言では省略可能です。The condition is optional in a route declaration. ソースからシンクへのメッセージをすべて渡す場合は、WHERE 句全体をそのまま削除します。If you want to pass all messages from the source to the sink, just leave out the WHERE clause entirely. または、IoT Hub クエリ言語を使用して、条件を満たす特定のメッセージまたはメッセージの種類をフィルター処理することができます。Or you can use the IoT Hub query language to filter for certain messages or message types that satisfy the condition. IoT Edge のルートは、ツインのタグやプロパティに基づくメッセージのフィルタリングをサポートしません。IoT Edge routes don't support filtering messages based on twin tags or properties.

IoT Edge のモジュール間を通過するメッセージは、デバイスと Azure IoT Hub の間を通過するメッセージと同じ形式になります。The messages that pass between modules in IoT Edge are formatted the same as the messages that pass between your devices and Azure IoT Hub. すべてのメッセージは JSON で書式設定され、パラメーターとして systemPropertiesappPropertiesbody が与えられます。All messages are formatted as JSON and have systemProperties, appProperties, and body parameters.

次の構文を利用して、この 3 つのパラメーターを中心にクエリを構築できます。You can build queries around any of the three parameters with the following syntax:

  • システム プロパティ: $<propertyName> または {$<propertyName>}System properties: $<propertyName> or {$<propertyName>}
  • アプリケーション プロパティ: <propertyName>Application properties: <propertyName>
  • 本文プロパティ: $body.<propertyName>Body properties: $body.<propertyName>

メッセージ プロパティのクエリを作成する方法の例は、「デバイスからクラウドへのメッセージ ルートのクエリ式」を参照してください。For examples about how to create queries for message properties, see Device-to-cloud message routes query expressions.

IoT Edge に固有の例としては、たとえば、リーフ デバイスからゲートウェイ デバイスに到着したメッセージにフィルターを適用します。An example that is specific to IoT Edge is when you want to filter for messages that arrived at a gateway device from a leaf device. モジュールから送信されるメッセージには、connectionModuleId と呼ばれるシステム プロパティが含まれます。Messages that come from modules include a system property called connectionModuleId. したがって、リーフ デバイスからメッセージを直接 IoT Hub にルーティングする場合は、次のルートを使用してモジュールのメッセージを除外します。So if you want to route messages from leaf devices directly to IoT Hub, use the following route to exclude module messages:

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

シンクSink

シンクでは、メッセージの送信先が定義されます。The sink defines where the messages are sent. メッセージを受信できるのは、モジュールと IoT Hub だけです。Only modules and IoT Hub can receive messages. 他のデバイスにメッセージをルーティングすることはできません。Messages can't be routed to other devices. シンク プロパティにワイルドカードのオプションはありません。There are no wildcard options in the sink property.

シンク プロパティは、次のいずれかの値にすることができます。The sink property can be any of the following values:

シンクSink 説明Description
$upstream IoT Hub にメッセージを送信するSend the message to IoT Hub
BrokeredEndpoint("/modules/<moduleId>/inputs/<input>") 特定のモジュールの特定の入力にメッセージを送信するSend the message to a specific input of a specific module

IoT Edge は、At-Least-Once 保証を提供します。IoT Edge provides at-least-once guarantees. IoT Edge ハブは、ルートでそのシンクにメッセージを配信できなかった場合のために、ローカルにメッセージを保存します。The IoT Edge hub stores messages locally in case a route can't deliver the message to its sink. たとえば、IoT Edge ハブが IoT Hub に接続できない場合や、ターゲット モジュールが接続されていない場合です。For example, if the IoT Edge hub can't connect to IoT Hub, or the target module isn't connected.

IoT Edge ハブでは、IoT Edge ハブの必要なプロパティstoreAndForwardConfiguration.timeToLiveSecs プロパティで指定した時間まで、メッセージが格納されます。IoT Edge hub stores the messages up to the time specified in the storeAndForwardConfiguration.timeToLiveSecs property of the IoT Edge hub desired properties.

必要なプロパティの定義または更新Define or update desired properties

配置マニフェストでは、IoT Edge デバイスにデプロイされるモジュールごとに、必要なプロパティを指定します。The deployment manifest specifies desired properties for each module deployed to the IoT Edge device. 現時点でモジュール ツインにある必要なプロパティは、配置マニフェストにある必要なプロパティによってすべて上書きされます。Desired properties in the deployment manifest overwrite any desired properties currently in the module twin.

モジュール ツインの必要なプロパティを配置マニフェストで指定していない場合、IoT Hub はどのような方法であれ、モジュール ツインを変更することはありません。If you do not specify a module twin's desired properties in the deployment manifest, IoT Hub won't modify the module twin in any way. 必要なプロパティを自分でプログラムから設定することはできます。Instead, you can set the desired properties programmatically.

デバイス ツインを変更できるのと同じメカニズムを使用してモジュール ツインを変更できます。The same mechanisms that allow you to modify device twins are used to modify module twins. 詳細については、モジュール ツイン開発者ガイドをご覧ください。For more information, see the module twin developer guide.

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

有効な配置マニフェスト ドキュメントの例を次に示します。The following example shows what a valid deployment manifest document may look like.

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.0",
        "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.0",
              "createOptions": ""
            }
          },
          "edgeHub": {
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-hub:1.0",
              "createOptions": ""
            }
          }
        },
        "modules": {
          "SimulatedTemperatureSensor": {
            "version": "1.0",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0",
              "createOptions": "{}"
            }
          },
          "filtermodule": {
            "version": "1.0",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "settings": {
              "image": "myacr.azurecr.io/filtermodule:latest",
              "createOptions": "{}"
            }
          }
        }
      }
    },
    "$edgeHub": {
      "properties.desired": {
        "schemaVersion": "1.0",
        "routes": {
          "sensorToFilter": "FROM /messages/modules/SimulatedTemperatureSensor/outputs/temperatureOutput INTO BrokeredEndpoint(\"/modules/filtermodule/inputs/input1\")",
          "filterToIoTHub": "FROM /messages/modules/filtermodule/outputs/output1 INTO $upstream"
        },
        "storeAndForwardConfiguration": {
          "timeToLiveSecs": 10
        }
      }
    }
  }
}

次の手順Next steps