IoT Hub エンドポイント
Azure IoT Hub では、関係のあるデバイスとサービスをサポートするために、さまざまなエンドポイントが公開されています。
Note
この記事で言及されている一部の機能 (cloud-to-device メッセージング、デバイス ツイン、デバイス管理など) は、IoT Hub の Standard レベルだけで使用することができます。 Basic および Standard または Free の IoT Hub のレベルの詳細については、「ソリューションに適した IoT Hub のレベルを選択する」を参照してください。
IoT Hub 名
IoT ハブのホスト名は、Azure portal で、お使いの IoT ハブの [概要] 作業ペインから確認できます。 既定では、IoT ハブの DNS 名は次の例のようになります。
{your iot hub name}.azure-devices.net
開発と管理のための IoT Hub エンドポイント
Azure IoT Hub は、さまざまなアクターに機能を公開するマルチテナント サービスです。 次の図は、IoT Hub が公開しているさまざまなエンドポイントを示します。
次の一覧では、エンドポイントについて説明します。
リソース プロバイダー: Azure Resource Manager インターフェイス。 Azure サブスクリプションの所有者は、IoT Hub の作成と削除や IoT Hub プロパティの更新などを、このインターフェイスで行うことができます。 IoT Hub のプロパティでは、ハブレベルの共有アクセス ポリシー (デバイスレベルのアクセス制御ではありません) と、Cloud-to-device (クラウドからデバイス) と Device-to-cloud (デバイスからクラウド) のメッセージング機能のオプションを管理します。 また、IoT Hub リソースプロバイダーにより、デバイス ID をエクスポートすることもできます。
デバイス ID 管理: デバイス ID の管理 (作成、取得、更新、削除) を行うための、一連の HTTPS REST エンドポイント。 デバイス IDは、デバイスの認証とアクセス制御に使用されます。
デバイス ツイン管理: デバイス ツインのクエリと更新 (タグとプロパティの更新) を実行するための、サービスに接続する一連の HTTPS REST エンドポイント。
ジョブ管理: ジョブのクエリと管理を実行するための、サービスに接続する一連の HTTPS REST エンドポイント。
デバイス エンドポイント: ID レジストリ内の各デバイスに対する一連のエンドポイント。 明記されている場合を除き、これらのエンドポイントは、MQTT v3.1.1、HTTPS 1.1、および AMQP 1.0 の各プロトコルを使用して公開されます。 AMQP および MQTT は、ポート 443 で WebSockets 経由で使用することもできます。 これらのデバイス エンドポイントには、次のものが含まれます。
device-to-cloud メッセージを送信する
cloud-to-device メッセージを受信する
ファイル アップロードを開始
デバイス ツインのプロパティを取得して更新する (HTTPS はサポートされていません)
ダイレクト メソッドの要求を受信します (HTTPS はサポートされていません)
サービス エンドポイント: デバイスと通信するための、ソリューション バックエンドに対する一連のエンドポイント。 唯一の例外は、これらのエンドポイントが、AMQP および WebSockets プロトコル経由の AMQP を使用して、公開されるのみの場合です。 ダイレクト メソッド呼び出しのエンドポイントは、HTTPS プロトコル経由で公開されます。
device-to-cloud メッセージを受信する: このエンドポイントは、メッセージ ルーティングの概念で説明されている組み込みのエンドポイントです。 バックエンド サービスはこのエンドポイントを使用して、デバイスによって送信されたデバイスからクラウドへのメッセージを読み取ることができます。 この組み込みのエンドポイントに加え、IoT Hub のカスタム エンドポイントを作成することもできます。
cloud-to-device メッセージを送信し、配信の肯定応答を受信する
ファイル アップロード通知を受信する
ダイレクト メソッドを呼び出す
Azure IoT Hub SDK に関する記事で、これらのエンドポイントにアクセスするさまざまな方法が説明されています。
IoT Hub エンドポイントはすべて TLSプロトコルを使用しており、暗号化/セキュリティ保護されていない経路からエンドポイントが公開されることはありません。
重要
X.509 証明機関 (CA) の認証を使用するデバイスの次の機能は、まだ一般提供されていません。また、プレビュー モードを有効にする必要があります。
- HTTPS、WebSocket 経由の MQTT、WebSockets プロトコル経由の AMQP。
- ファイルのアップロード (すべてのプロトコル)。
これらの機能は、X.509 拇印認証を使用するデバイスで一般提供されています。 IoT Hub での X.509 認証の詳細については、「サポートされている X.509 証明書」を参照してください。
メッセージ ルーティング用のカスタム エンドポイント
Azure サブスクリプション内の既存の Azure サービスを IoT ハブにリンクして、メッセージ ルーティング用のエンドポイントとして機能させることができます。 これらのエンドポイントはサービス エンドポイントとして機能し、メッセージ ルートのシンクとして使用されます。 デバイスからこれらのエンドポイントに直接書き込むことはできません。 メッセージ ルーティングの詳細については、「IoT Hub メッセージ ルーティングを使用して device-to-cloud メッセージを別のエンドポイントに送信する」を参照してください。
IoT Hub では、カスタム エンドポイントとして、次の Azure サービスがサポートされています。
- ストレージ コンテナー
- Event Hubs
- Service Bus キュー
- Service Bus トピック
- Cosmos DB
ハブごとのエンドポイントの制限については、クォータと調整に関する記事をご覧ください。
組み込みのエンドポイント
標準的な Event Hubs 統合と SDK を使用して、組み込みのエンドポイント (messages/events) から device-to-cloud メッセージを受信することができます。 何らかのルートが作成されると、ルートが作成されていない組み込みのエンドポイントには、データが流れなくなります。 ルートが作成されていない場合でも、組み込みのエンドポイントにメッセージをルーティングするために、フォールバック ルートを有効にする必要があります。 ポータルまたは CLI を使用してハブを作成した場合、フォールバックは既定で有効になります。
ルーティング エンドポイントとしての Azure Storage
IoT Hub がメッセージをルーティングできるストレージ サービスとして、Azure Blob Storage アカウントと Azure Data Lake Storage Gen2 (ADLS Gen2) アカウントの 2 つがあります。 これらはどちらも、そのストレージとして BLOB を使用します。 Azure Data Lake Gen2 を使用するには、ストレージ アカウントで階層型名前空間が有効になっている必要があります。 詳細情報については、「Azure Data Lake Storage で使用するストレージ アカウントを作成する」を参照してください。
IoT Hub は、Apache Avro 形式と JSON 形式での Azure Storage へのデータの書き込みをサポートしています。 既定値は AVRO です。 JSON エンコードを使うには、メッセージのシステム プロパティにおいて、contentType プロパティを application/json に設定し、contentEncoding プロパティを UTF-8 に設定します。 これらのどちらの値でも大文字と小文字は区別されません。 コンテンツのエンコードが設定されていない場合、IoT Hub は Base 64 エンコード形式でメッセージを書き込みます。
このエンコード形式は、Blob Storage エンドポイントが構成されている場合にのみ設定できます。既存のエンドポイントについて編集することはできません。
バッチが特定のサイズに達するか、または一定の時間が経過する度に、IoT Hub はメッセージを一括処理し、ストレージにデータを書き込みます。 IoT Hub の既定のファイル名前付け規則は次のとおりです: {iothub}/{partition}/{YYYY}/{MM}/{DD}/{HH}/{mm} ファイルには任意の名前付け規則を使用できますが、一覧で示されているすべてのトークンを使う必要があります。 書き込むデータがない場合、IoT Hub は空の BLOB に書き込みます。
パーティションについてどのような想定も行わずにすべての BLOB またはファイルが確実に読み取られるようにするため、BLOB またはファイルの一覧を取得してから反復処理することをお勧めします。 Microsoft が開始するフェールオーバー中や IoT Hub の手動フェールオーバー中にパーティションの範囲が変わる可能性があります。 List Blobs API を使用して BLOB の一覧を、または List ADLS Gen2 API を使用してファイルの一覧を列挙できます。 次に例を示します。
public void ListBlobsInContainer(string containerName, string iothub)
{
var storageAccount = CloudStorageAccount(Microsoft.Azure.Storage.Auth.StorageCredentials storageCredentials, bool useHttps);
var cloudBlobContainer = storageAccount.CreateCloudBlobClient().GetContainerReference(containerName);
if (cloudBlobContainer.Exists())
{
var results = cloudBlobContainer.ListBlobs(prefix: $"{iothub}/");
foreach (IListBlobItem item in results)
{
Console.WriteLine(item.Uri);
}
}
}
ルーティング エンドポイントとしての Service Bus キューと Service Bus トピック
IoT Hub エンドポイントとして使用される Service Bus のキューおよびトピックでは、セッションも重複データ検出も有効にしないでください。 これらのオプションのいずれかが有効になっている場合、エンドポイントは Azure Portal に到達不能として表示されます。
ルーティング エンドポイントとしての Event Hubs
組み込みの Event Hubs 互換エンドポイントとは別に、Event Hubs タイプのカスタム エンドポイントにデータをルーティングすることもできます。
ルーティング エンドポイントとしての Azure Cosmos DB
IoT Hub から Azure Cosmos DB にデータを直接送信できます。 IoT Hub では、JSON での (メッセージのコンテンツ タイプで指定されている場合)、または base 64 でエンコードされたバイナリとしての、Cosmos DB への書き込みがサポートされています。
大規模なシナリオをサポートするには、Cosmos DB エンドポイントの合成パーティション キーを有効にできます。 Cosmos DB はハイパースケール データストアであるため、書き込まれるすべてのデータ/ドキュメントには、論理パーティションを表すフィールドが含まれている必要があります。 各論理パーティションの最大サイズは 20 GB です。 パーティション キーのプロパティ名は、[パーティション キー名] で指定できます。 パーティション キーのプロパティ名はコンテナー レベルで定義され、更新することはできません。
合成パーティション キーの値を構成するには、推定データ ボリュームに基づいて [パーティション キー テンプレート] でテンプレートを指定します。 たとえば、製造シナリオでは、論理パーティションが 1 か月以内にその上限である 20 GB に近づくと予想される場合があります。 その場合は、デバイス ID と月の組み合わせとして合成パーティション キーを定義できます。 生成されたパーティション キーの値は、新しい Cosmos DB レコードごとにパーティション キー プロパティに自動的に追加され、デバイスごとに毎月論理パーティションが作成されます。
注意事項
Cosmos DB への認証にシステム割り当て済みのマネージド ID を使用している場合は、Azure CLI または Azure PowerShell を使用して、Cosmos DB Built-in Data Contributor ロール定義を ID に割り当てる必要があります。 Azure portal からの Cosmos DB のロールの割り当ては、現在サポートされていません。 さまざまなロールの詳細については、Azure Cosmos DB のロールベース アクセスの構成に関するページを参照してください。 CLI を使用したロールの割り当てについては、Azure Cosmos DB SQL ロール リソースの管理に関するページを参照してください。
エンドポイントの正常性
REST API の Get Endpoint Health を使用して、エンドポイントの正常性状態を取得できます。 エンドポイントの正常性が停止または異常である場合、エンドポイントがこれらの状態にあるときは待機時間が長くなることが予測されるため、ルーティング メッセージ待機時間に関連した IoT Hub ルーティング メトリックを使用して、エラーを識別およびデバッグすることをお勧めします。 IoT Hub メトリックの使用に関する詳細については、IoT Hub の監視に関する記事を参照してください。
| 正常性状態 | 説明 |
|---|---|
| healthy | エンドポイントは想定どおりにメッセージを受け付けています。 |
| unhealthy | エンドポイントはメッセージを受け付けておらず、IoT Hub はこのエンドポイントへのメッセージ送信を再試行しています。 |
| unknown | IoT Hub はこのエンドポイントにメッセージを配信しようとしていません。 |
| degraded | エンドポイントは、想定より遅くメッセージを受け入れているか、異常な状態から回復中です。 |
| dead | IoT Hub は、このエンドポイントにメッセージを配信しなくなりました。 このエンドポイントへのメッセージ送信の再試行に失敗しました。 |
次のステップ
これらのトピックについて詳しくは、以下をご覧ください。