次の方法で共有

Azure CLI を使用してルートとエンドポイントを作成および削除する

  • [アーティクル]

この記事では、Azure CLI を使って Azure IoT Hub のルートとエンドポイントを管理する方法について説明します。 Azure CLI を使って、Azure Event Hubs、Azure Service Bus のキューとトピック、Azure Storage、Cosmos DB に対してルートとエンドポイントを作成する方法について説明します。

IoT Hub のルーティングのしくみについては、「IoT Hub メッセージ ルーティングを使用して device-to-cloud メッセージを別のエンドポイントに送信する」を参照してください。 ストレージにメッセージを送信するルートを設定し、シミュレートされたデバイスでテストする手順については、「チュートリアル: IoT Hub メッセージ ルーティングを使用してデバイス データを Azure Storage に送信する」を参照してください。

前提条件

この記事で説明する手順では、次のリソースを使用します。

  • Azure CLI
  • IoT ハブ
  • Azure のエンドポイント サービス

Azure CLI

この記事では、Azure CLI を使って IoT Hub や他の Azure サービスを操作します。 Azure CLI へのアクセス方法を選択できます。

  • Azure Cloud Shell で Bash 環境を使用します。 詳細については、「Azure Cloud Shell の Bash のクイックスタート」を参照してください。

  • CLI リファレンス コマンドをローカルで実行する場合、Azure CLI をインストールします。 Windows または macOS で実行している場合は、Docker コンテナーで Azure CLI を実行することを検討してください。 詳細については、「Docker コンテナーで Azure CLI を実行する方法」を参照してください。

    • ローカル インストールを使用する場合は、az login コマンドを使用して Azure CLI にサインインします。 認証プロセスを完了するには、ターミナルに表示される手順に従います。 その他のサインイン オプションについては、Azure CLI でのサインインに関するページを参照してください。

    • 初回使用時にインストールを求められたら、Azure CLI 拡張機能をインストールします。 拡張機能の詳細については、Azure CLI で拡張機能を使用する方法に関するページを参照してください。

    • az version を実行し、インストールされているバージョンおよび依存ライブラリを検索します。 最新バージョンにアップグレードするには、az upgrade を実行します。

IoT Hub

Azure サブスクリプション内に IoT ハブを持っていること。 ハブがまだない場合は、「IoT ハブの作成」の手順に従うことができます。

エンドポイント サービス

ルートへのエンドポイントとして使う他の Azure サービスが少なくとも 1 つ必要です。 エンドポイントは、デバイス メッセージとイベント ログを受信します。

ルーティングされたデバイスとイベントのデータを受信するエンドポイントとして使う Azure サービスを決めます。つまり、イベント ハブ、サービスのキューまたはトピック、ストレージ アカウント、または Cosmos DB コンテナーです。 使用することを選択したサービスについて、エンドポイント サービスを作成する手順を完了します。

  1. Event Hubs 名前空間とイベント ハブを作成します。 詳細については、「クイック スタート: Azure CLI を使用したイベント ハブの作成」を参照してください。

  2. イベント ハブにデータを送信するアクセス許可を IoT Hub に付与するために使う認可規則を作成します。

    ヒント

    name パラメーターの値 RootManageSharedAccessKey は、管理、送信、リッスンの要求 (アクセス) を許可する既定の名前です。 要求を制限する場合は、name パラメーターに一意の名前を付けて、--rights フラグの後に 1 つの要求を含めます。 たとえば、「 --name my-name --rights Send 」のように入力します。

    az eventhubs eventhub authorization-rule create --resource-group my-resource-group --namespace-name my-routing-namespace --eventhub-name my-event-hubs --name RootManageSharedAccessKey

    詳細については、「Azure Event Hubs へのアクセスを承認する」を参照してください。

エンドポイントの作成

すべての IoT Hub ルートは、ルーティングされたデバイスとイベント データを受信するエンドポイントを指します。 複数のルートが同じエンドポイントを指すことができます。 現在、IoT Hub は、イベント ハブ、Service Bus のキューまたはトピック、ストレージ、Cosmos DB のエンドポイントをサポートしています。 エンドポイントに使うサービスのインスタンスは、エンドポイントを作成する前に、Azure サブスクリプションに存在している必要があります。

注意

この記事では、Azure CLI 用の azure-iot 拡張機能のバージョン 0.19.0 で導入された az iot hub message-endpoint コマンド グループを使います。 azure-iot 拡張機能の以前のバージョンでは、az iot hub routing-endpoint コマンド グループを使っていました。これは同様のものであり、まだサポートされていますが、Cosmos DB エンドポイントの作成はサポートされていません。

次のコマンドを使って、最新バージョンの azure-iot 拡張機能に更新してください。

az extension update --name azure-iot

Event Hubs エンドポイントを作成するには、前提条件で作成した認可規則を使います。

  1. az eventhubs eventhub authorization-rule keys list コマンドを使って、認可規則を一覧表示します。 プレースホルダーのパラメーターに次の値を指定します。

    パラメーター (parameter) value
    eventhub_group イベント ハブのリソース グループ。
    eventhub_namespace Event Hubs 名前空間の名前。
    eventhub_name イベント ハブの名前。
    rule_name イベント ハブの認可規則の名前。 前提条件の例をコピーした場合、この名前は RootManageSharedAccessKey です。 
    az eventhubs eventhub authorization-rule keys list --resource-group {eventhub_group} --namespace-name {eventhub_namespace} --eventhub-name my-event-hubs --name {rule_name}

  2. 出力からイベント ハブの接続文字列をコピーします。

  3. az iot hub message-endpoint create eventhub コマンドを使って、カスタム エンドポイントを作成します。 プレースホルダーのパラメーターに次の値を指定します。

    パラメーター (parameter) value
    iothub_name このエンドポイントが作成される IoT ハブの名前。
    endpoint_name 新しいエンドポイントの一意な名前。
    eventhub_subscription イベント ハブのサブスクリプション ID。 イベント ハブが IoT ハブと同じサブスクリプションにある場合は、この引数を省略できます。
    eventhub_group イベント ハブのリソース グループ。 イベント ハブが IoT ハブと同じリソース グループにある場合は、この引数を省略できます。
    eventhub_connection_string イベント ハブの認可規則からコピーした接続文字列。 
    az iot hub message-endpoint create eventhub --hub-name {iothub_name} --endpoint-name {endpoint_name}  --connection-string "{eventhub_connection_string}" --endpoint-subscription-id {eventhub_subscription} --endpoint-resource-group {eventhub_group}

エンドポイントの削除

IoT ハブからエンドポイントを削除する場合は、az iot hub message-endpoint delete コマンドを使います。 このコマンドを使うと、1 つのエンドポイントの削除、1 つの種類のすべてのエンドポイントの削除、または 1 つのハブからのすべてのエンドポイントの削除を行うことができます。

たとえば、次のコマンドを使うと、ストレージ リソースを指す IoT ハブ内のすべてのエンドポイントを削除することができます。

az iot hub message-endpoint delete --hub-name {iothub_name} --endpoint-type storage-container

IoT Hub ルートを作成する

IoT Hub では、メッセージを送信する、またはイベントをキャプチャするルートを作成できます。 各ルートには、データ ソースとエンドポイントがあります。 データ ソースは、メッセージまたはイベント ログが生成される場所です。 エンドポイントは、メッセージまたはイベント ログが最終的に到達する場所です。 IoT ハブで新しいルートを作成するときに、データ ソースとエンドポイントの場所を選択します。 必要に応じて、メッセージ ルートにクエリを追加し、エンドポイントに到達する前にメッセージやイベントをフィルター処理できます。

注意

この記事では、Azure CLI 用の azure-iot 拡張機能のバージョン 0.19.0 で導入された az iot hub message-route コマンド グループを使います。 azure-iot 拡張機能の以前のバージョンでは、az iot hub route コマンド グループを使っていました。これは同様のものであり、まだサポートされています。

次のコマンドを使って、最新バージョンの azure-iot 拡張機能に更新してください。

az extension update --name azure-iot

  1. az iot hub message-route create コマンドを使い、そのエンドポイントを使って新しい IoT ハブ ルートを作成します。 プレースホルダーのパラメーターに次の値を指定します。

    パラメーター (parameter) value
    iothub_name このルートが作成される IoT ハブの名前。
    route_name 新しいルートの一意の名前。
    endpoint_name ルートがデータを送信するエンドポイントの名前。
    data_source ルートのソース。 指定できる値は deviceconnectionstateevents、devicejoblifecycleevents、devicelifecycleevents、devicemessages、digitaltwinchangeevents、invalid、または twinchangeevents です。 
    az iot hub message-route create --hub-name {iothub_name} --route-name {route_name} --endpoint-name {endpoint_name} --source {data_source}

  2. 新しいルートが IoT ハブにあることを確認するには、az iot hub message-route list コマンドを使って、IoT ハブのすべてのルートを表示します。

    az iot hub message-route list --hub-name {iothub_name}

    次の例のような応答が Azure CLI に表示されます。

    [
   {
     "condition": "true",
     "endpointNames": [
       "endpoint_name"
     ],
     "isEnabled": true,
     "name": "route_name",
     "source": "DeviceConnectionStateEvents"
   }
]

IoT Hub ルートを更新する

ルートの作成後に、一部のプロパティを更新できます。 既存のルートのソース、エンドポイント、条件、または有効な状態を変更できます。

ルートの詳細を確認するには、az iot hub message-route show コマンドを使います。

az iot hub message-route show --hub-name {iothub_name} --route-name {route_name}

ルートのプロパティを更新するには、az iot hub message-route update コマンドを使います。 たとえば、次のコマンドを使ってルートのソースを更新することができます。

az iot hub message-route update --hub-name {iothub_name} --route-name {route_name} --source devicejoblifecycleevents

IoT Hub ルートを削除する

IoT ハブからルートを削除するには、az iot hub message-route delete コマンドを使います。

ルートを削除しても、そのエンドポイントは削除されません。これは、他のルートが同じエンドポイントを指している可能性があるためです。 エンドポイントを削除する場合は、ルートの削除とは別に行うことができます。

az iot hub message-route delete --hub-name {iothub_name} --route-name {route_name}

フォールバック ルートを管理する

フォールバック ルートは、既存のルートのいずれかでクエリ条件を満たさないすべてのメッセージを devicemessages ソースから組み込みのエンドポイントに送信します。

IoT ハブのフォールバック ルートの状態を確認するには、az iot hub message-route fallback show コマンドを使います。

az iot hub message-route fallback show --hub-name {iothub_name}

IoT ハブのフォールバック ルートを有効または無効にするには、az iot hub message-route fallback set コマンドを使います。

az iot hub message-route fallback set --hub-name {iothub_name} --enabled {true_false}

次の手順

このハウツー記事では、Event Hubs、Service Bus キューとトピック、Azure Storage に対してルートとエンドポイントを作成する方法について説明しました。

メッセージ ルーティングの詳細については、「チュートリアル: IoT Hub メッセージ ルーティングを使用してデバイス データを Azure Storage に送信する」を参照してください。 このチュートリアルでは、ストレージ ルートを作成し、IoT ハブでデバイスを使ってテストします。