IoT Hub のモジュール ツインの理解と使用Understand and use module twins in IoT Hub

この記事は、「IoT Hub のデバイス ツインの理解と使用」をすでに読み、理解していることを前提としています。This article assumes you've read Understand and use device twins in IoT Hub first. IoT Hub では、デバイス ID ごとに最大 20 個のモジュール ID を作成できます。In IoT Hub, under each device identity, you can create up to 20 module identities. モジュールの ID ごとに、モジュール ツインは暗黙的に生成されます。Each module identity implicitly generates a module twin. モジュール ツインは、デバイス ツインと同様、モジュールの状態に関する情報 (メタデータ、構成、状態など) を格納する JSON ドキュメントです。Similar to device twins, module twins are JSON documents that store module state information including metadata, configurations, and conditions. Azure IoT Hub は、IoT Hub に接続したモジュールごとにモジュール ツインを管理します。Azure IoT Hub maintains a module twin for each module that you connect to IoT Hub.

デバイス側では、IoT Hub デバイス SDK を使用して、それぞれが IoT Hub への独立した接続を確立するモジュールを作成できます。On the device side, the IoT Hub device SDKs enable you to create modules where each one opens an independent connection to IoT Hub. この機能により、デバイスのさまざまなコンポーネントごとに個別の名前空間を使用することができます。This functionality enables you to use separate namespaces for different components on your device. たとえば、3 つの異なるセンサーが付いた自動販売機があるとします。For example, you have a vending machine that has three different sensors. 各センサーは、社内の異なる部署によって管理されています。Each sensor is controlled by different departments in your company. センサーごとにモジュールを作成することができます。You can create a module for each sensor. これにより、各部門は、管轄するセンサーにのみジョブを送信したり、メソッドを転送できるため、競合やユーザー エラーを回避できます。This way, each department is only able to send jobs or direct methods to the sensor that they control, avoiding conflicts and user errors.

モジュール ID とモジュール ツインは、デバイス ID とデバイス ツインと同様の機能を、より細かい粒度で提供します。Module identity and module twin provide the same capabilities as device identity and device twin but at a finer granularity. このより細かい粒度により、オペレーティング システム ベースのデバイスやファームウェア デバイスなどの複数のコンポーネントで構成され、この機能をサポートするデバイスの各コンポーネントの構成と状態を特定できます。This finer granularity enables capable devices, such as operating system-based devices or firmware devices managing multiple components, to isolate configuration and conditions for each of those components. モジュール形式のソフトウェア コンポーネントを含む IoT デバイスを使用する場合、モジュール ID とモジュール ツインを使用することで、コンポーネントの管理を分割できます。Module identity and module twins provide a management separation of concerns when working with IoT devices that have modular software components. マイクロソフトは、モジュール ツインの一般可用性により、モジュール ツイン レベルですべてのデバイス ツイン機能をサポートすることを目指しています。We aim at supporting all the device twin functionality at module twin level by module twin general availability.

注意

この記事で説明される機能は、IoT Hub の Standard レベルでのみ利用できます。The features described in this article are only available in the standard tier of IoT hub. IoT Hub の Basic レベルおよび Standard レベルについて詳しくは、適切な IoT Hub レベルの選び方に関するページを参照してください。For more information about the basic and standard IoT Hub tiers, see How to choose the right IoT Hub tier.

この記事では、次の内容について説明します。This article describes:

  • モジュール ツインの構造: タグ必要なプロパティ報告されるプロパティThe structure of the module twin: tags, desired and reported properties.
  • モジュールとバックエンドがモジュール ツイン上で実行できる操作。The operations that the modules and back ends can perform on module twins.

報告されるプロパティ、device-to-cloud メッセージ、ファイルのアップロードのどれを使用するべきかの指針については、「device-to-cloud 通信に関するガイダンス」を参照してください。Refer to Device-to-cloud communication guidance for guidance on using reported properties, device-to-cloud messages, or file upload.

必要なプロパティ、ダイレクト メソッド、cloud-to-device メッセージの使用に関する指針については、「cloud-to-device 通信に関するガイダンス」を参照してください。Refer to Cloud-to-device communication guidance for guidance on using desired properties, direct methods, or cloud-to-device messages.

モジュール ツインModule twins

モジュール ツインには、モジュールに関連する次のような情報が格納されます。Module twins store module-related information that:

  • デバイス上のモジュールと IoT Hub がモジュールの状態と構成を同期するために使用できます。Modules on the device and IoT Hub can use to synchronize module conditions and configuration.

  • 実行時間の長い操作にクエリを行い、ターゲットを設定するために使用するソリューション バックエンド。The solution back end can use to query and target long-running operations.

モジュール ツインのライフサイクルは、対応するモジュール ID にリンクされます。The lifecycle of a module twin is linked to the corresponding module identity. モジュール ツインは、IoT Hub でモジュール ID を作成または削除したときに、暗黙的に作成または削除されます。Modules twins are implicitly created and deleted when a module identity is created or deleted in IoT Hub.

モジュール ツインは、次の情報を含む JSON ドキュメントです。A module twin is a JSON document that includes:

  • タグTags. ソリューション バックエンドで読み書きできる JSON ドキュメントのセクションです。A section of the JSON document that the solution back end can read from and write to. タグは、デバイス上のモジュールからは認識されません。Tags are not visible to modules on the device. タグは、クエリの目的で設定されます。Tags are set for querying purpose.

  • 必要なプロパティDesired properties. モジュールの構成や状態を同期するために、報告されるプロパティと共に使用します。Used along with reported properties to synchronize module configuration or conditions. ソリューション バックエンドは必要なプロパティを設定でき、モジュール アプリはそれらを読み取れます。The solution back end can set desired properties, and the module app can read them. モジュール アプリでは、必要なプロパティに対する変更を知らせる通知を受け取ることもできます。The module app can also receive notifications of changes in the desired properties.

  • 報告されるプロパティReported properties. モジュールの構成や状態を同期するために、必要なプロパティと共に使用します。Used along with desired properties to synchronize module configuration or conditions. モジュール アプリは報告されるプロパティを設定でき、ソリューション バックエンドはそれらを読み取りクエリを実行できます。The module app can set reported properties, and the solution back end can read and query them.

  • モジュール ID のプロパティModule identity properties. モジュール ツインの JSON ドキュメントのルートには、ID レジストリに格納される対応するモジュール ID の読み取り専用プロパティが含まれます。The root of the module twin JSON document contains the read-only properties from the corresponding module identity stored in the identity registry.

デバイス ツインのアーキテクチャの表現

次の例は、モジュール ツインの JSON ドキュメントを示しています。The following example shows a module twin JSON document:

{
    "deviceId": "devA",
    "moduleId": "moduleA",
    "etag": "AAAAAAAAAAc=", 
    "status": "enabled",
    "statusReason": "provisioned",
    "statusUpdateTime": "0001-01-01T00:00:00",
    "connectionState": "connected",
    "lastActivityTime": "2015-02-30T16:24:48.789Z",
    "cloudToDeviceMessageCount": 0, 
    "authenticationType": "sas",
    "x509Thumbprint": {     
        "primaryThumbprint": null, 
        "secondaryThumbprint": null 
    }, 
    "version": 2, 
    "tags": {
        "$etag": "123",
        "deploymentLocation": {
            "building": "43",
            "floor": "1"
        }
    },
    "properties": {
        "desired": {
            "telemetryConfig": {
                "sendFrequency": "5m"
            },
            "$metadata" : {...},
            "$version": 1
        },
        "reported": {
            "telemetryConfig": {
                "sendFrequency": "5m",
                "status": "success"
            },
            "batteryLevel": 55,
            "$metadata" : {...},
            "$version": 4
        }
    }
}

ルート オブジェクトには、モジュール ID プロパティと、tags のコンテナー オブジェクトと、reported プロパティと desired プロパティの両方があります。In the root object are the module identity properties, and container objects for tags and both reported and desired properties. properties コンテナーには、「モジュール ツインのメタデータ」と「オプティミスティック コンカレンシー」セクションで説明されているいくつかの読み取り専用の要素 ($metadata$etag$version) が含まれています。The properties container contains some read-only elements ($metadata, $etag, and $version) described in the Module twin metadata and Optimistic concurrency sections.

報告されるプロパティの例Reported property example

前の例では、デバイス アプリによって報告される batteryLevel プロパティがモジュール ツインに含まれています。In the previous example, the module twin contains a batteryLevel property that is reported by the module app. このプロパティでは、最後に報告されたバッテリ レベルに基づいて、モジュール上でクエリや操作を実行できます。This property makes it possible to query and operate on modules based on the last reported battery level. 別の例には、モジュール アプリにモジュールの報告機能や接続オプションが含まれています。Other examples include the module app reporting module capabilities or connectivity options.

注意

ソリューション バックエンドにおける関心の対象が、最後に確認されているプロパティの値であるような状況では、報告されたプロパティを使用した方が簡単です。Reported properties simplify scenarios where the solution back end is interested in the last known value of a property. ソリューション バックエンドでタイムスタンプが付けられた連続するイベントの形式でモジュール テレメトリ (時系列など) を処理する必要がある場合は、device-to-cloud メッセージを使用します。Use device-to-cloud messages if the solution back end needs to process module telemetry in the form of sequences of timestamped events, such as time series.

必要なプロパティの例Desired property example

上記の例では、ソリューション バックエンドとモジュール アプリが telemetryConfig モジュール ツインの必要なプロパティと報告されたプロパティを使用して、モジュールのテレメトリ構成を同期しています。In the previous example, the telemetryConfig module twin desired and reported properties are used by the solution back end and the module app to synchronize the telemetry configuration for this module. 例: For example:

  1. ソリューション バックエンドでは、必要なプロパティが必要な構成値で設定されます。The solution back end sets the desired property with the desired configuration value. 以下は、ドキュメント内の必要なプロパティ セットを使用した部分です。Here is the portion of the document with the desired property set:

    ...
    "desired": {
        "telemetryConfig": {
            "sendFrequency": "5m"
        },
        ...
    },
    ...
    
  2. 最初に再接続されたとき、あるいは接続に変更が加えられたときには、モジュール アプリに直ちに通知されます。The module app is notified of the change immediately if connected, or at the first reconnect. その後、モジュール アプリが更新された構成 (またはエラー条件。status プロパティを使用) を報告します。The module app then reports the updated configuration (or an error condition using the status property). 報告されるプロパティの部分を次に示します。Here is the portion of the reported properties:

    "reported": {
        "telemetryConfig": {
            "sendFrequency": "5m",
            "status": "success"
        }
        ...
    }
    
  3. ソリューション バックエンドは、モジュール ツインにクエリを実行することによって、複数のモジュールとの間で行われる構成操作の結果を追跡できます。The solution back end can track the results of the configuration operation across many modules, by querying module twins.

注意

上記のスニペットは、モジュール構成とその状態をエンコードするための例の 1 つであり、読みやすいように最適化されています。The preceding snippets are examples, optimized for readability, of one way to encode a module configuration and its status. IoT Hub は、モジュール ツインの必要なプロパティや報告されたプロパティに対して、モジュール ツイン用の特定のスキーマを強制しません。IoT Hub does not impose a specific schema for the module twin desired and reported properties in the module twins.

バック エンドの操作Back-end operations

ソリューション バックエンドは、HTTPS を介して公開される次のアトミック操作を使用して、モジュール ツインを操作します。The solution back end operates on the module twin using the following atomic operations, exposed through HTTPS:

  • ID を条件にモジュールを取得するRetrieve module twin by ID. この操作は、タグ、必要なシステム プロパティ、報告されるシステム プロパティを含むモジュール ツインのドキュメントを返します。This operation returns the module twin document, including tags and desired and reported system properties.

  • モジュール ツインを部分的に更新するPartially update module twin. この操作では、ソリューション バックエンドがモジュール ツインのタグまたは必要なプロパティを部分的に更新できます。This operation enables the solution back end to partially update the tags or desired properties in a module twin. 部分的な更新は JSON ドキュメントとして表され、プロパティが追加または更新されます。The partial update is expressed as a JSON document that adds or updates any property. null に設定されたプロパティが削除されます。Properties set to null are removed. 次の例では、{"newProperty": "newValue"} の値を持つ新しい必要なプロパティが作成され、existingProperty の既存の値が "otherNewValue" で上書きされ、otherOldProperty が削除されます。The following example creates a new desired property with value {"newProperty": "newValue"}, overwrites the existing value of existingProperty with "otherNewValue", and removes otherOldProperty. それ以外、既にある必要なプロパティまたはタグは変更されません。No other changes are made to existing desired properties or tags:

    {
        "properties": {
            "desired": {
                "newProperty": {
                    "nestedProperty": "newValue"
                },
                "existingProperty": "otherNewValue",
                "otherOldProperty": null
            }
        }
    }
    
  • 必要なプロパティの置換Replace desired properties. この操作では、ソリューション バックエンドによって既存の必要なプロパティをすべて完全に上書きし、properties/desired の新しい JSON ドキュメントに置き換えられます。This operation enables the solution back end to completely overwrite all existing desired properties and substitute a new JSON document for properties/desired.

  • タグの置換Replace tags. この操作では、ソリューション バックエンドによって既存のタグをすべて完全に上書きし、tags の新しい JSON ドキュメントに置き換えられます。This operation enables the solution back end to completely overwrite all existing tags and substitute a new JSON document for tags.

  • ツイン通知の受信Receive twin notifications. この操作は、ソリューション バックエンドでツインが変更されたときに通知できるようにします。This operation allows the solution back end to be notified when the twin is modified. そのためには、IoT ソリューションでルートを作成し、データ ソースの値を twinChangeEvents に設定する必要があります。To do so, your IoT solution needs to create a route and to set the Data Source equal to twinChangeEvents. 既定では、ツイン通知は送信されません。つまり、このようなルートは事前に存在しません。By default, no twin notifications are sent, that is, no such routes pre-exist. 変化率が高すぎる場合、または内部エラーなどの理由のために、IoT Hub はすべての変更を含む 1 つの通知のみを送信する場合があります。If the rate of change is too high, or for other reasons such as internal failures, the IoT Hub might send only one notification that contains all changes. そのため、アプリケーションに信頼性の高い監査とすべての中間状態のログ記録が必要な場合は、device-to-cloud メッセージを使用する必要があります。Therefore, if your application needs reliable auditing and logging of all intermediate states, you should use device-to-cloud messages. ツイン通知メッセージには、プロパティおよび本文が含まれます。The twin notification message includes properties and body.

    • PropertiesProperties

      NameName Value
      $content-type$content-type application/jsonapplication/json
      $iothub-enqueuedtime$iothub-enqueuedtime 通知が送信された時刻Time when the notification was sent
      $iothub-message-source$iothub-message-source twinChangeEventstwinChangeEvents
      $content-encoding$content-encoding utf-8utf-8
      deviceIddeviceId デバイスの IDID of the device
      moduleIdmoduleId モジュールの IDID of the module
      hubNamehubName IoT Hub の名前Name of IoT Hub
      operationTimestampoperationTimestamp 操作の ISO8601 タイムスタンプISO8601 timestamp of operation
      iothub-message-schemaiothub-message-schema deviceLifecycleNotificationdeviceLifecycleNotification
      opTypeopType "replaceTwin" または "updateTwin""replaceTwin" or "updateTwin"

      メッセージのシステム プロパティには、$ シンボルが付きます。Message system properties are prefixed with the $ symbol.

    • 本文Body

      このセクションには、すべてのツイン変更が JSON 形式で含まれています。This section includes all the twin changes in a JSON format. 修正プログラムと同じ形式を使用しますが、すべてのツイン セクション (タグ、properties.reported、properties.desired) を含めることができ、"$metadata" 要素を含みます。It uses the same format as a patch, with the difference that it can contain all twin sections: tags, properties.reported, properties.desired, and that it contains the “$metadata” elements. たとえば、次のように入力します。For example,

      {
        "properties": {
            "desired": {
                "$metadata": {
                    "$lastUpdated": "2016-02-30T16:24:48.789Z"
                },
                "$version": 1
            },
            "reported": {
                "$metadata": {
                    "$lastUpdated": "2016-02-30T16:24:48.789Z"
                },
                "$version": 1
            }
        }
      }
      

上述の操作はすべてオプティミスティック コンカレンシーをサポートしており、「IoT Hub へのアクセスの制御」の記事で定義されているとおり、ServiceConnect アクセス許可を必要とします。All the preceding operations support Optimistic concurrency and require the ServiceConnect permission, as defined in the Control Access to IoT Hub article.

これらの操作に加えて、ソリューション バックエンドでは SQL に似た IoT Hub クエリ言語を使用してモジュール ツインのクエリを実行できます。In addition to these operations, the solution back end can query the module twins using the SQL-like IoT Hub query language.

モジュールの操作Module operations

モジュール アプリは、次のアトミック操作を使用して、モジュール ツインを操作します。The module app operates on the module twin using the following atomic operations:

  • モジュール ツインを取得するRetrieve module twin. この操作は、タグ、必要なシステム プロパティ、報告されるシステム プロパティを含む、現在接続されているモジュールのモジュール ツインのドキュメントを返します。This operation returns the module twin document (including tags and desired and reported system properties) for the currently connected module.

  • 報告されるプロパティの部分的な更新Partially update reported properties. この操作では、現在接続されているモジュールの報告されるプロパティを部分的に更新できます。This operation enables the partial update of the reported properties of the currently connected module. この操作には、必要なプロパティを部分的に更新する際にソリューション バックエンドで使用されるものと同じ JSON 更新フォーマットが使用されます。This operation uses the same JSON update format that the solution back end uses for a partial update of desired properties.

  • 必要なプロパティの監視Observe desired properties. 現在接続されているモジュールでは、必要なプロパティの更新が行われたときに通知をするように設定できます。The currently connected module can choose to be notified of updates to the desired properties when they happen. モジュールは、ソリューション バックエンドによって実行される更新 (部分的または完全な置換) と同じフォームを受け取ります。The module receives the same form of update (partial or full replacement) executed by the solution back end.

IoT Hub へのアクセスの制御」の記事に定義されているように、上述の操作にはすべて ModuleConnect アクセス許可が必要です。All the preceding operations require the ModuleConnect permission, as defined in the Control Access to IoT Hub article.

Azure IoT device SDK を使用すると、多数の言語とプラットフォームで上述の操作を簡単に使用できます。The Azure IoT device SDKs make it easy to use the preceding operations from many languages and platforms.

タグやプロパティの形式Tags and properties format

タグ、必要なプロパティ、報告されるプロパティは JSON オブジェクトであり、次のような制限があります。Tags, desired properties, and reported properties are JSON objects with the following restrictions:

  • JSON オブジェクトのすべてのキーは、大文字小文字が区別される 64 バイトの UTF-8 UNICODE 文字列です。All keys in JSON objects are case-sensitive 64 bytes UTF-8 UNICODE strings. UNICODE 制御文字列 (セグメント C0 と C1)、.、SP、$ は使用できません。Allowed characters exclude UNICODE control characters (segments C0 and C1), and ., SP, and $.

  • JSON オブジェクトのすべての値には、ブール値、数値、文字列、オブジェクトの JSON 型を使用できます。All values in JSON objects can be of the following JSON types: boolean, number, string, object. 配列は使用できません。Arrays are not allowed. 整数の最大値は 4503599627370495 であり、整数の最小値は -4503599627370496 です。The maximum value for integers is 4503599627370495 and the minimum value for integers is -4503599627370496.

  • タグ、必要なプロパティ、および報告されるプロパティのすべての JSON オブジェクトは、深さ 5 まで許容されます。All JSON objects in tags, desired, and reported properties can have a maximum depth of 5. たとえば、次のオブジェクトは有効です。For instance, the following object is valid:

    {
        ...
        "tags": {
            "one": {
                "two": {
                    "three": {
                        "four": {
                            "five": {
                                "property": "value"
                            }
                        }
                    }
                }
            }
        },
        ...
    }
    
  • すべての文字列値の長さは、最大で 512 バイトまで許容されます。All string values can be at most 512 bytes in length.

モジュール ツインのサイズModule twin size

読み取り専用の要素を除き、IoT Hub では tagsproperties/desiredproperties/reported の各合計値に対して強制的に 8 KB のサイズ制限が適用されます。IoT Hub enforces an 8KB size limitation on each of the respective total values of tags, properties/desired, and properties/reported, excluding read-only elements.

このサイズは、UNICODE 制御文字 (セグメント C0 と C1) を除くすべての文字と、文字列定数以外で使用されるスペースをカウントして計算されます。The size is computed by counting all characters, excluding UNICODE control characters (segments C0 and C1) and spaces that are outside of string constants.

ドキュメントのサイズが上述の制限を超えると、IoT Hub はすべての操作を拒否して、エラーを返します。IoT Hub rejects with an error all operations that would increase the size of those documents above the limit.

モジュール ツインのメタデータModule twin metadata

IoT Hub は、各 JSON オブジェクトが最後に更新されたときのタイムスタンプを、モジュール ツインの必要なプロパティと報告されるプロパティに保持します。IoT Hub maintains the timestamp of the last update for each JSON object in module twin desired and reported properties. タイムスタンプは UTC であり、ISO8601 形式の YYYY-MM-DDTHH:MM:SS.mmmZ でエンコードされます。The timestamps are in UTC and encoded in the ISO8601 format YYYY-MM-DDTHH:MM:SS.mmmZ. 例: For example:

{
    ...
    "properties": {
        "desired": {
            "telemetryConfig": {
                "sendFrequency": "5m"
            },
            "$metadata": {
                "telemetryConfig": {
                    "sendFrequency": {
                        "$lastUpdated": "2016-03-30T16:24:48.789Z"
                    },
                    "$lastUpdated": "2016-03-30T16:24:48.789Z"
                },
                "$lastUpdated": "2016-03-30T16:24:48.789Z"
            },
            "$version": 23
        },
        "reported": {
            "telemetryConfig": {
                "sendFrequency": "5m",
                "status": "success"
            },
            "batteryLevel": "55%",
            "$metadata": {
                "telemetryConfig": {
                    "sendFrequency": "5m",
                    "status": {
                        "$lastUpdated": "2016-03-31T16:35:48.789Z"
                    },
                    "$lastUpdated": "2016-03-31T16:35:48.789Z"
                },
                "batteryLevel": {
                    "$lastUpdated": "2016-04-01T16:35:48.789Z"
                },
                "$lastUpdated": "2016-04-01T16:24:48.789Z"
            },
            "$version": 123
        }
    }
    ...
}

この情報は、オブジェクトのキーによって削除される更新を保持するために、JSON の構造のリーフだけでなくすべてのレベルで保持されます。This information is kept at every level (not just the leaves of the JSON structure) to preserve updates that remove object keys.

オプティミスティック コンカレンシーOptimistic concurrency

タグ、必要なプロパティ、報告されたプロパティはすべて、オプティミスティック コンカレンシーをサポートします。Tags, desired, and reported properties all support optimistic concurrency. タグは、RFC7232 に従って ETag を持ちます。これは、タグの JSON 表現を表します。Tags have an ETag, as per RFC7232, that represents the tag's JSON representation. ETag を使用すると、条件付き更新操作をソリューション バックエンドから実行し、一貫性を保持できます。You can use ETags in conditional update operations from the solution back end to ensure consistency.

モジュール ツインの必要なプロパティと報告されるプロパティには ETag はありませんが、$version の値によって確実に増分されます。Module twin desired and reported properties do not have ETags, but have a $version value that is guaranteed to be incremental. ETag と同様、更新側がバージョンを使用することで更新プログラムの一貫性を確保することができます。Similarly to an ETag, the version can be used by the updating party to enforce consistency of updates. たとえば、報告されたプロパティ用のモジュール アプリ、または目的のプロパティのソリューション バックエンドです。For example, a module app for a reported property or the solution back end for a desired property.

バージョンは、監視エージェント (必要なプロパティを監視するモジュール アプリなど) が取得操作に関する結果と更新の通知の間の競合を調整する場合に便利です。Versions are also useful when an observing agent (such as the module app observing the desired properties) must reconcile races between the result of a retrieve operation and an update notification. 詳細については、「デバイスの再接続フロー」セクションを参照してください。The section Device reconnection flow provides more information.

次の手順Next steps

この記事で説明した概念を試すには、次の IoT Hub のチュートリアルをご覧ください。To try out some of the concepts described in this article, see the following IoT Hub tutorials: