IoT Hub の ID レジストリを理解する
すべての IoT ハブには、その IoT ハブへの接続が許可されたデバイスおよびモジュールに関する情報を保存する ID レジストリがあります。 デバイスまたはモジュールを IoT ハブに接続できるようにするには、そのデバイスまたはモジュールのエントリが IoT ハブの ID レジストリに存在する必要があります。 さらに、ID レジストリに保存されている資格情報に基づいて、デバイスまたはモジュールが IoT ハブで認証される必要があります。
ID レジストリに保存されているデバイスまたはモジュール ID は、大文字と小文字が区別されます。
大まかに言うと、ID レジストリは、デバイスまたはモジュール ID リソースの REST 対応コレクションです。 この ID レジストリにエントリを追加すると、転送中の Cloud-to-device メッセージが含まれるキューなどの、デバイス単位のリソースが IoT Hub によって作成されます。
ID レジストリは、以下が必要な場合に使用します。
- IoT ハブに接続するデバイスまたはモジュールをプロビジョニングする。
- ハブのデバイスまたはモジュール向けエンドポイントに対するデバイスまたはモジュールごとのアクセスを制御する。
ID レジストリの操作
IoT Hub の ID レジストリでは、次の操作が公開されています。
- デバイスまたはモジュール ID の作成
- デバイスまたはモジュール ID の更新
- ID ごとのデバイスまたはモジュール ID の取得
- デバイスまたはモジュール ID の削除
- 最大 1000 個の ID の一覧表示
- Azure Blob Storage へのデバイス ID のエクスポート
- Azure Blob Storage からのデバイス ID のインポート
これらすべての操作で、RFC7232 に指定されているオプティミスティック同時実行制御を使用できます。
重要
IoT Hub の ID レジストリにあるすべての ID を取得する唯一の方法は、エクスポート機能を使用することです。
IoT Hub の ID レジストリの特徴は次のとおりです。
- アプリケーションのメタデータは含まれていません。
重要
ID レジストリは、デバイスの管理およびプロビジョニング操作でのみ使用します。 実行時の高スループット操作が、ID レジストリに対する操作の影響を受けないようにする必要があります。 たとえば、コマンドを送信する前に、デバイスの接続状態を確認するやり方は、サポートされていないパターンです。 ID レジストリに関するレートの調整を必ず確認してください。
注意
デバイスまたはモジュールの ID を作成した後、取得できるようになるまでに数秒かかることがあります。 障害が発生した場合は、デバイスまたはモジュールの ID の get 操作を再試行してください。
デバイスの無効化
ID レジストリで ID の status プロパティを更新することにより、デバイスを無効にすることができます。 通常、このプロパティは次の 2 つのシナリオで使用します。
オーケストレーション プロセスのプロビジョニング中。 詳細については、デバイスのプロビジョニングに関するページを参照してください。
何らかの理由で、デバイスが侵害されているか、未承認の状態になっていると考えられる場合。
重要
IoT Hub では、証明書ベースの認証を使用してデバイスを認証するときに、証明書失効リストは確認されません。 証明書が侵害された可能性があるために IoT Hub への接続をブロックする必要があるデバイスがある場合は、ID レジストリでそのデバイスを無効にする必要があります。
この機能は、モジュールでは使用できません。
詳細については、「IoT ハブでデバイスを無効化または削除する」を参照してください。
デバイス ID のインポートとエクスポート
IoT ハブの ID レジストリからデバイス ID を一括エクスポートするには、IoT Hub リソース プロバイダー エンドポイントに対する非同期操作を使用します。 エクスポートは、顧客が指定した BLOB コンテナーを使用して、デバイス ID レジストリから読み取ったデバイス ID データを保存する、長時間実行されるジョブです。
IoT ハブの ID レジストリにデバイス ID を一括インポートするには、IoT Hub リソース プロバイダー エンドポイントに対する非同期操作を使用します。 インポートは、顧客が指定した BLOB コンテナー内のデータを使用してデバイス ID データを ID レジストリに書き込む、長時間実行ジョブです。
インポート API とエクスポート API の詳細については、IoT Hub のリソースプロバイダー REST API に関する記事を参照してください。 インポートおよびエクスポート ジョブの実行方法の詳細については、IoT Hub デバイス ID の一括管理に関するページを参照してください。
REST API、またはいずれかの IoT Hub サービス SDK のどちらかを介して Service API を使用して、デバイス ID を IoT ハブからエクスポートおよびインポートすることもできます。
デバイス プロビジョニング
特定の IoT ソリューションに格納されるデバイス データは、そのソリューションの具体的な要件によって異なりますが、 ソリューションには少なくともデバイスの ID と認証キーを格納する必要があります。 Azure IoT Hub には、各デバイスの ID、認証キー、状態コードなどの値を保存できる ID レジストリがあります。 ソリューションでは、Table Storage、Blob Storage、Azure Cosmos DB などの他の Azure サービスを使って、その他のデバイス データを保存できます。
デバイス プロビジョニング とは、最初のデバイス データをソリューション内のストアに追加するプロセスです。 新しいデバイスをハブに接続できるようにするには、デバイスの ID とキーを IoT Hub ID レジストリに追加する必要があります。 プロビジョニング プロセスの一環として、他のソリューション ストアにあるデバイス固有データの初期化が必要になる場合があります。 また、Azure IoT Hub Device Provisioning サービスを使用して、1 つまたは複数の IoT ハブに対してノータッチの Just-In-Time プロビジョニングを実現できるため、人の手を介する必要がなくなります。 詳しくは、Provisioning Service のドキュメントをご覧ください。
デバイスまたはモジュールのライフサイクルの通知
IoT Hub では、ライフサイクルの通知を送信して、デバイス ID が作成または削除されたときに IoT ソリューションに通知できます。 そのためには、IoT ソリューションでルートを作成し、DeviceLifecycleEvents と同じデータ ソースを設定する必要があります。 既定では、ライフサイクルの通知は送信されません。つまり、このようなルートは事前に存在しません。 データ ソースを DeviceLifecycleEvents に設定してルートを作成することにより、デバイス ID とモジュール ID の両方に対してライフサイクル イベントが送信されます。ただし、モジュール ID とデバイス ID のどちらに対してイベントが生成されたかによって、メッセージの内容は異なります。 IoT Edge モジュールの場合、モジュール ID の作成フローは他のモジュールとは異なることに注意してください。その結果として、IoT Edge モジュールの場合は、更新された IoT Edge モジュール ID に対応する IoT Edge デバイスが実行されている場合にのみ作成通知が送信されます。 他のすべてのモジュールについては、IoT Hub 側でモジュール ID が更新されるたびに、ライフサイクル通知が送信されます。 通知メッセージで返されるプロパティと本文の詳細については、非テレメトリ イベント スキーマに関するページを参照してください。
デバイス ID のプロパティ
デバイス ID は、次のプロパティを持つ JSON ドキュメントとして表されます。
| プロパティ | オプション | 説明 |
|---|---|---|
| deviceId | 必須、読み取り専用 (更新時) | ASCII 7 ビット英数字の大文字と小文字が区別される文字列 (最大 128 文字) と、特定の特殊文字 (- . % _ * ? ! ( ) , : = @ $ ')。 特殊文字 + # はサポートされていません。 |
| generationId | 必須、読み取り専用 | IoT Hub によって生成された、大文字と小文字が区別される文字列 (最大 128 文字)。 この値は、デバイスが削除されて再作成された場合に、同じ deviceId を持つデバイスを区別するために使用します。 |
| etag | 必須、読み取り専用 | RFC7232 に準拠した、デバイス ID の弱い ETag を表す文字列。 |
| 認証 | オプション | 認証情報とセキュリティのマテリアルを含む複合オブジェクト。 詳細については、REST API ドキュメントの「AuthenticationMechanism」を参照してください。 |
| capabilities | 省略可能 | デバイスの一連の機能。 たとえば、デバイスがエッジ デバイスかどうか、など。 詳細については、REST API ドキュメントの「Device Capabilities」を参照してください。 |
| deviceScope | 省略可能 | デバイスのスコープ。 エッジ デバイスでは、自動生成され、変更できません。 非エッジ デバイスでは、非推奨とされます。 ただし、子 (リーフ) デバイスでは、以前のバージョンの API との下位互換性を維持するため、このプロパティを parentScopes プロパティ (親デバイスの deviceScope) と同じ値に設定します。 詳細については、「ゲートウェイとしての IoT Edge: 親と子のリレーションシップ」を参照してください。 |
| parentScopes | 省略可能 | 子デバイスの直接の親のスコープ (親デバイスの deviceScope プロパティの値)。 エッジ デバイスでは、デバイスに親がない場合、値は空です。 非エッジ デバイスでは、デバイスに親がない場合、このプロパティは存在しません。 詳細については、「ゲートウェイとしての IoT Edge: 親と子のリレーションシップ」を参照してください。 |
| status | 必須 | アクセス インジケーター。 [有効] または [無効] のいずれか。 [有効]の場合、デバイスからの接続が許可されます。 [無効] の場合、このデバイスからデバイス向けのエンドポイントにアクセスできません。 |
| statusReason | オプション | デバイス ID の状態の理由を格納する、長さが 128 文字の文字列。 すべての UTF-8 文字を使用できます。 |
| statusUpdateTime | 読み取り専用 | 状態が最後に更新された日時を示す時間のインジケーター。 |
| connectionState | 読み取り専用 | 接続状態を示すフィールド。Connected または Disconnected のいずれか。 このフィールドは、デバイスの接続状態に関する IoT Hub ビューを表します。 重要: このフィールドは、開発およびデバッグ専用として使用してください。 接続状態は、MQTT または AMQP を使用するデバイスについてのみ更新されます。 また、この更新はプロトコル レベルの ping (MQTT ping または AMQP ping) に基づいており、遅延は最大でもわずか 5 分です。 このため、接続状態にあると報告されているが切断状態にあるデバイスのように、偽陽性を示す可能性があります。 |
| connectionStateUpdatedTime | 読み取り専用 | 前回接続状態が更新された日時を示す時間のインジケーター。 |
| lastActivityTime | 読み取り専用 | 前回デバイスが接続された日時またはメッセージを送受信した日時を示す時間のインジケーター。 このプロパティの一貫性は最終的には保たれますが、最大で 5 ～ 10 分遅れる可能性があります。 このため、運用環境のシナリオでは使用しないでください。 |
Note
接続状態が表すのは、その接続状態を示す IoT Hub ビューのみです。 ネットワークの状態と構成によっては、この状態の更新が遅延することがあります。
Note
現在、デバイス SDK では、deviceId に + および # 文字の使用はサポートされていません。
モジュール ID のプロパティ
モジュール ID は、次のプロパティを持つ JSON ドキュメントとして表されます。
| プロパティ | オプション | 説明 |
|---|---|---|
| deviceId | 必須、読み取り専用 (更新時) | ASCII 7 ビット英数字の大文字と小文字が区別される文字列 (最大 128 文字) と、特定の特殊文字 (- . + % _ # * ? ! ( ) , : = @ $ ')。 |
| moduleId | 必須、読み取り専用 (更新時) | ASCII 7 ビット英数字の大文字と小文字が区別される文字列 (最大 128 文字) と、特定の特殊文字 (- . + % _ # * ? ! ( ) , : = @ $ ')。 |
| generationId | 必須、読み取り専用 | IoT Hub によって生成された、大文字と小文字が区別される文字列 (最大 128 文字)。 この値は、デバイスが削除されて再作成された場合に、同じ deviceId を持つデバイスを区別するために使われます。 |
| etag | 必須、読み取り専用 | RFC7232 に準拠した、デバイス ID の弱い ETag を表す文字列。 |
| 認証 | オプション | 認証情報とセキュリティのマテリアルを含む複合オブジェクト。 詳細については、REST API ドキュメントの「AuthenticationMechanism」を参照してください。 |
| managedBy | 省略可能 | このモジュールを管理している主体を識別します。 たとえば、エッジ ランタイムによってこのモジュールが所有されている場合、この値は "IoT Edge" になります。 |
| cloudToDeviceMessageCount | 読み取り専用 | モジュールに送信するために現在キューに登録されている、クラウドからモジュールへのメッセージの数。 |
| connectionState | 読み取り専用 | 接続状態を示すフィールド。Connected または Disconnected のいずれか。 このフィールドは、デバイスの接続状態に関する IoT Hub ビューを表します。 重要: このフィールドは、開発およびデバッグ専用として使用してください。 接続状態は、MQTT または AMQP を使用するデバイスについてのみ更新されます。 また、この更新はプロトコル レベルの ping (MQTT ping または AMQP ping) に基づいており、遅延は最大でもわずか 5 分です。 このため、接続状態にあると報告されているが切断状態にあるデバイスのように、偽陽性を示す可能性があります。 |
| connectionStateUpdatedTime | 読み取り専用 | 前回接続状態が更新された日時を示す時間のインジケーター。 |
| lastActivityTime | 読み取り専用 | 前回デバイスが接続された日時またはメッセージを送受信した日時を示す時間のインジケーター。 |
Note
現在、デバイス SDK では、deviceId および moduleId に、+ および # 文字の使用はサポートされていません。
参考資料
IoT Hub 開発者ガイドには、他に次のような参照記事があります。
IoT Hub エンドポイント: 各 IoT Hub でランタイムと管理の操作のために公開される、さまざまなエンドポイントについて説明します。
スロットルとクォータ: IoT Hub サービスに適用されるクォータとスロットルの動作について説明します。
Azure IoT device SDK とサービス SDK: IoT Hub とやりとりするデバイスとサービス アプリの両方を開発する際に使用できるさまざまな言語の SDK を紹介します。
IoT Hub のクエリ言語: IoT Hub からデバイス ツインとジョブに関する情報を取得する際に使用できるクエリ言語について説明します。
IoT Hub の MQTT サポート: IoT Hub での MQTT プロトコルのサポートについて詳しく説明します。
次のステップ
IoT Hub の ID レジストリの使用方法がわかったら、IoT Hub 開発者ガイドの次の記事もご覧ください。
IoT Hub Device Provisioning サービスを使用してノータッチの Just-In-Time プロビジョニングを実現する方法については、次を参照してください。