デバイスツインの使用 (Azure CLI)

[アーティクル]
03/17/2023

デバイスツインは、デバイスに関する情報 (メタデータ、構成、状態など) を格納する JSON ドキュメントです。 IoT Hub は、IoT Hub に接続する各デバイスにデバイスツインを保持します。

Note

この記事で説明されている機能は、Standard レベルの IoT Hub でのみ使用できます。 Basic および Standard または Free レベルの IoT Hub の詳細については、ソリューションに適した IoT Hub のレベルの選択に関するページを参照してください。

次の場合にデバイスツインを使用します。

ソリューションバックエンドからデバイスメタデータを格納する。
デバイスアプリで利用できる機能や状態 (たとえば、使用される接続方法) などの現在の状態に関する情報をレポートする。
デバイスアプリとバックエンドアプリの間で実行時間の長いワークフロー (ファームウェアや構成の更新など) の状態を同期する。
デバイスメタデータ、構成、または状態を照会する。

デバイスツインは、同期のほか、デバイスの構成と状態の照会に対応しています。デバイスツインの使用方法など、デバイスツインの詳細については、デバイスツインの理解に関するページを参照してください。

IoT ハブには、次の要素を含むデバイスツインが格納されます。

タグ。ソリューションバックエンドからのみアクセスできるデバイスメタデータです。
必要なプロパティ。ソリューションバックエンドから変更でき、デバイスアプリから監視できる JSON オブジェクトです。
報告されるプロパティ。デバイスアプリから変更でき、ソリューションバックエンドから読み取り可能な JSON オブジェクトです。

タグとプロパティには配列を含めることはできませんが、入れ子になったオブジェクトを含めることができます。

次の図は、デバイスツイン組織を示しています。

デバイスツインの概念図のスクリーンショット。

さらに、ソリューションバックエンドは、上記のすべてのデータに基づいてデバイスツインに対してクエリを実行できます。デバイスツインの詳細については、デバイスツインの理解に関するページを参照してください。クエリ実行の詳細については、IoT Hub クエリ言語に関するページを参照してください。

この記事で取り上げるテクニック:

シミュレートされたデバイスを使用して、その接続チャネルをデバイスツイン上の報告されるプロパティとして報告します。
以前に作成したタグとプロパティのフィルターを使用して、デバイスに対してクエリを実行します。

デバイスツインの報告されるプロパティの使用の詳細については、「device-to-cloud 通信に関するガイダンス」を参照してください。

この記事では、次の 2 つの Azure CLI セッションを作成する方法について説明します。

シミュレートされたデバイスを作成するセッション。シミュレートされたデバイスは、初期化時に、デバイスの対応するデバイスツインの報告されたプロパティとして、その接続チャネルを報告します。
シミュレートされたデバイスのデバイスツインのタグを更新し、IoT ハブからデバイスに対してクエリを実行するセッション。このクエリでは、両方のセッションで以前に更新されたタグとプロパティに基づくフィルターが使用されます。

前提条件

Azure CLI。この記事のコマンドは、ブラウザーまたは (Windows Terminal などの) アプリで実行されるインタラクティブ CLI シェルである Azure Cloud Shell を使用して実行することもできます。 Cloud Shell を使用する場合は、何もインストールする必要はありません。 CLI をローカルで使用する場合、この記事では、Azure CLI バージョン 2.36 以降が必要です。バージョンを確認するには、az --version を実行します。 Azure CLI をローカルにインストールまたはアップグレードするには、Azure CLI のインストールに関する記事を参照してください。
Azure サブスクリプション内の IoT ハブ。ハブがまだない場合は、「IoT ハブの作成」の手順に従うことができます。
ポート 8883 がファイアウォールで開放されていることを確認してください。この記事のサンプルでは、ポート 8883 を介して通信する MQTT プロトコルを使用しています。このポートは、企業や教育用のネットワーク環境によってはブロックされている可能性があります。この問題の詳細と対処方法については、「IoT Hub への接続 (MQTT)」を参照してください。

Cloud Shell を準備する

Azure Cloud Shell を使用する場合は、まずそれを起動して構成する必要があります。 CLI をローカルで使用する場合は、「2 つの CLI セッションを準備する」のセクションに進んでください。

Azure portal のページヘッダーから Cloud Shell アイコンを選択します。

注意

Cloud Shell を初めて使用する場合は、Cloud Shell を使用するために必要なストレージを作成するように求められます。ストレージアカウントと Microsoft Azure ファイル共有を作成するためのサブスクリプションを選択します。
Cloud Shell ツールバーの環境セレクターを使用して、希望する CLI 環境を選択します。この記事では、Bash 環境を使用します。 PowerShell 環境を使うこともできます。

注意

一部のコマンドは、Bash および PowerShell 環境では異なる構文または書式が必要です。詳細については、「Azure CLI を正しく使用するためのヒント」を参照してください。

2 つの CLI セッションを準備する

次に、2 つの Azure CLI セッションを準備する必要があります。 Cloud Shell を使用している場合は、これらのセッションを別々の Cloud Shell タブで実行します。ローカル CLI クライアントを使用している場合は、別々の CLI インスタンスを実行します。次のタスクには、別々の CLI セッションを使用します。

最初のセッションでは、IoT ハブと通信する IoT デバイスをシミュレートします。
2 番目のセッションでは、シミュレートされたデバイスが更新され、IoT ハブに対してクエリが実行されます。

Cloud Shell を使用している場合は、次の手順に進みます。それ以外の場合は、最初の CLI セッションで az login コマンドを実行して、Azure アカウントにサインインします。

Cloud Shell を使用している場合は、Azure アカウントに自動的にサインインします。 Azure CLI セッションと IoT hub の間のすべての通信は認証および暗号化されます。そのため、この記事では、接続文字列などの実際のデバイスで使用する追加の認証は必要ありません。 Azure CLI を使用したサインインについて詳しくは、「Azure CLI を使用してサインインする」をご覧ください。
```
az login
```
最初の CLI セッションで、 az extension add コマンドを実行します。このコマンドにより、Azure CLI 用の Microsoft Azure IoT 拡張機能が CLI シェルにインストールされます。この拡張機能により、IoT Hub、IoT Edge、IoT Device Provisioning Service (DPS) 固有のコマンドが Azure CLI に追加されます。この拡張機能をインストールした後は、Cloud Shell セッションで再度インストールする必要はありません。
```
az extension add --name azure-iot
```
注意

この記事では、azure-iot と呼ばれる、Azure IoT 拡張機能の最新バージョンを使用します。従来のバージョンは azure-cli-iot-ext と呼ばれます。一度にインストールできるバージョンは 1 つだけです。コマンド az extension list を使用すると、現在インストールされている拡張機能を確認できます。

拡張機能の従来のバージョンを削除するには、az extension remove --name azure-cli-iot-ext を使用します。

拡張機能の新しいバージョンを追加するには、az extension add --name azure-iot を使用します。

インストール済みの拡張機能を表示するには、az extension list を使用してください。
2 つ目の CLI セッションを開きます。ブラウザーで Cloud Shell を使用している場合は、最初の CLI セッションのツールバーにある [新しいセッションを開く] アイコンを選択します。 CLI をローカルで使用している場合は、2 つ目の CLI インスタンスを開きます。

デバイスを作成してシミュレートする

このセクションでは、最初の CLI セッションで IoT ハブのデバイス ID を作成し、そのデバイス ID を使用してデバイスをシミュレートします。シミュレートされたデバイスは、2 番目の CLI セッションでスケジュールするジョブに応答します。

シミュレートされたデバイスを作成し開始するには以下を行います。

最初の CLI セッションで、az iot hub device-identity create コマンドを実行し、以下のプレースホルダーを対応する値に置き換えます。このコマンドは、シミュレートされたデバイスのデバイス ID を作成します。

{DeviceName}。シミュレートされたデバイスの名前。

{HubName}。 IoT Hub の名前です。
```
az iot hub device-identity create --device-id {DeviceName} --hub-name {HubName} 
```
最初の CLI セッションで、az iot device simulate コマンドを実行し、以下のプレースホルダーを対応する値に置き換えます。このコマンドは、前の手順で作成したデバイスをシミュレートします。さらに、このコマンドにより、シミュレートされたデバイスは、初期化時に、デバイスの対応するデバイスツインの報告されたプロパティとして、その接続チャネルを報告するように構成されます。

{DeviceName}。シミュレートされたデバイスの名前。

{HubName}。 IoT Hub の名前です。
```
az iot device simulate --device-id {DeviceName} --hub-name {HubName} \
                       --init-reported-properties '{"connectivity":{"type": "cellular"}}'
```
ヒント

az iot device simulate コマンドは、既定では、device-to-cloud メッセージを 3 秒のメッセージ間隔で 100 件送信します。シミュレーションは、すべてのメッセージが送信されると終了します。シミュレーションの実行時間を長くする場合は、--msg-count パラメーターを使用して、指定するメッセージ数を増やすか、--msg-interval パラメーターを使用して、より長いメッセージ間隔を指定できます。コマンドをもう一度実行して、シミュレートされたデバイスを再起動することもできます。

デバイスツインを更新する

デバイス ID が作成されると、IoT Hub 内でデバイスツインが暗黙的に作成されます。このセクションでは、2 番目の CLI セッションを使用して、前のセクションで作成したデバイス ID に関連付けられたデバイスツインの一連のタグを更新します。デバイスツインタグを使用して、IoT ソリューション内のデバイスを整理および管理できます。タグを使用したデバイスの管理の詳細については、「Azure IoT Hub でデバイスツインタグを使用してデバイスを管理する方法」を参照してください。

最初の CLI セッションでシミュレートされたデバイスが実行されていることを確認します。そうでない場合は、「デバイスを作成してシミュレートする」に記載されている az iot device simulate コマンドをもう一度実行して再起動します。
2 番目の CLI セッションで、az iot hub device-twin update コマンドを実行し、以下のプレースホルダーを対応する値に置き換えます。この例では、前のセクションで作成したデバイス ID のデバイスツインで複数のタグを更新しています。

{DeviceName}。デバイスの名前。

{HubName}。 IoT Hub の名前です。
```
az iot hub device-twin update --device-id {DeviceName} --hub-name {HubName} \
                              --tags '{"location":{"region":"US","plant":"Redmond43"}}'
```

2 番目の CLI セッションで、JSON 応答に更新操作の結果が表示されていることを確認します。次の JSON 応答の例では、az iot hub device-twin update CLI コマンドの {DeviceName} プレースホルダーに SampleDevice を使用しています。

{
  "authenticationType": "sas",
  "capabilities": {
    "iotEdge": false
  },
  "cloudToDeviceMessageCount": 0,
  "connectionState": "Connected",
  "deviceEtag": "MTA2NTU1MDM2Mw==",
  "deviceId": "SampleDevice",
  "deviceScope": null,
  "etag": "AAAAAAAAAAI=",
  "lastActivityTime": "0001-01-01T00:00:00+00:00",
  "modelId": "",
  "moduleId": null,
  "parentScopes": null,
  "properties": {
    "desired": {
      "$metadata": {
        "$lastUpdated": "2023-02-21T10:40:10.5062402Z"
      },
      "$version": 1
    },
    "reported": {
      "$metadata": {
        "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
        "connectivity": {
          "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
          "type": {
            "$lastUpdated": "2023-02-21T10:40:43.8539917Z"
          }
        }
      },
      "$version": 2,
      "connectivity": {
        "type": "cellular"
      }
    }
  },
  "status": "enabled",
  "statusReason": null,
  "statusUpdateTime": "0001-01-01T00:00:00+00:00",
  "tags": {
    "location": {
      "plant": "Redmond43",
      "region": "US"
    }
  },
  "version": 4,
  "x509Thumbprint": {
    "primaryThumbprint": null,
    "secondaryThumbprint": null
  }
}

IoT ハブでデバイスツインのクエリを実行する

IoT Hub は、IoT Hub のデバイスツインを devices という名前のドキュメントコレクションとして公開します。このセクションでは、2 番目の CLI セッションを使用して、IoT ハブの一連のデバイスツインに対して 2 つのクエリを実行します。1 番目のクエリでは、Redmond43 工場にあるデバイスのデバイスツインのみを選択し、2 番目のクエリでは携帯ネットワーク経由で接続しているデバイスのみを選択します。どちらのクエリも、結果セット内の最初の 100 台のデバイスのみを返します。デバイスツインクエリの詳細については、「IoT Hub デバイスツインとモジュールツインのクエリ」を参照してください。

最初の CLI セッションでシミュレートされたデバイスが実行されていることを確認します。そうでない場合は、「デバイスを作成してシミュレートする」に記載されている az iot device simulate コマンドをもう一度実行して再起動します。
2 番目の CLI セッションで、az iot hub query コマンドを実行し、以下のプレースホルダーを対応する値に置き換えます。この例では、Redmond43 プラントにあるデバイスのデバイスツインのみを返すようにクエリをフィルター処理しています。

{HubName}。 IoT Hub の名前です。
```
az iot hub query --hub-name {HubName} \
                 --query-command "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'" \
                 --top 100
```

2 番目の CLI セッションで、JSON 応答にクエリの結果が表示されていることを確認します。

{
  "authenticationType": "sas",
  "capabilities": {
    "iotEdge": false
  },
  "cloudToDeviceMessageCount": 0,
  "connectionState": "Connected",
  "deviceEtag": "MTA2NTU1MDM2Mw==",
  "deviceId": "SampleDevice",
  "deviceScope": null,
  "etag": "AAAAAAAAAAI=",
  "lastActivityTime": "0001-01-01T00:00:00+00:00",
  "modelId": "",
  "moduleId": null,
  "parentScopes": null,
  "properties": {
    "desired": {
      "$metadata": {
        "$lastUpdated": "2023-02-21T10:40:10.5062402Z"
      },
      "$version": 1
    },
    "reported": {
      "$metadata": {
        "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
        "connectivity": {
          "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
          "type": {
            "$lastUpdated": "2023-02-21T10:40:43.8539917Z"
          }
        }
      },
      "$version": 2,
      "connectivity": {
        "type": "cellular"
      }
    }
  },
  "status": "enabled",
  "statusReason": null,
  "statusUpdateTime": "0001-01-01T00:00:00+00:00",
  "tags": {
    "location": {
      "plant": "Redmond43",
      "region": "US"
    }
  },
  "version": 4,
  "x509Thumbprint": {
    "primaryThumbprint": null,
    "secondaryThumbprint": null
  }
}

2 番目の CLI セッションで、az iot hub query コマンドを実行し、以下のプレースホルダーを対応する値に置き換えます。この例では、Redmond43 プラントにあり、携帯ネットワーク経由で接続しているデバイスのデバイスツインのみを返すようにクエリをフィルター処理しています。

{HubName}。 IoT Hub の名前です。
```
az iot hub query --hub-name {HubName} \
                 --query-command "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' \
                                  AND properties.reported.connectivity.type = 'cellular'" \
                 --top 100
```
2 番目の CLI セッションで、JSON 応答にクエリの結果が表示されていることを確認します。このクエリの結果は、このセクションの前のクエリの結果と一致している必要があります。

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

Azure CLI セッションからタグとしてデバイスメタデータを追加しました
デバイスツインでデバイス接続情報を報告したデバイスをシミュレートしました
Azure CLI セッションで、SQL に似た IoT Hub クエリ言語を使用して、デバイスツイン情報のクエリを実行しました

次のステップ

参照:

デバイスからテレメトリを送信するには、「クイックスタート: IoT プラグアンドプレイデバイスから Azure IoT Hub にテレメトリを送信する」を参照してください。
デバイスツインの目的のプロパティを使用してデバイスを構成するには、「チュートリアル: バックエンドサービスからデバイスを構成する」を参照してください。
ユーザー制御アプリからファンをオンにするなど、対話形式でデバイスを制御するには、「クイックスタート: IoT ハブに接続されたデバイスを制御する」を参照してください。

次の方法で共有

デバイスツインの使用 (Azure CLI)

前提条件

Cloud Shell を準備する

2 つの CLI セッションを準備する

デバイスを作成してシミュレートする

デバイスツインを更新する

IoT ハブでデバイスツインのクエリを実行する

次のステップ

フィードバック

フィードバック

その他のリソース

次の方法で共有

デバイス ツインの使用 (Azure CLI)

前提条件

Cloud Shell を準備する

2 つの CLI セッションを準備する

デバイスを作成してシミュレートする

デバイス ツインを更新する

IoT ハブでデバイス ツインのクエリを実行する

次のステップ

フィードバック

フィードバック

その他のリソース

デバイスツインの使用 (Azure CLI)

デバイスツインを更新する

IoT ハブでデバイスツインのクエリを実行する