デバイスツインの概要 (Python)

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

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

Note

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

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

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

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

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

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

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

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

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

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

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

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

この記事では、次の 2 つの Python コンソールアプリを作成します。

AddTagsAndQuery.py: タグの追加とデバイスツインのクエリを実行するバックエンドアプリ。
ReportConnectivity.py: IoT ハブに接続してその接続状態を報告するシミュレートされたデバイスアプリ。

Note

デバイスとバックエンドアプリの両方の構築に使用できる SDK ツールに関する詳細については、「Azure IoT SDK」を参照してください。

前提条件

アクティブな Azure アカウントアカウントがない場合、Azure 試用版にサインアップして、最大 10 件の無料 Mobile Apps を入手できます。 (アカウントがない場合は、無料アカウントを数分で作成できます)。
Azure サブスクリプション内の IoT ハブ。ハブがまだない場合は、「IoT ハブの作成」の手順に従うことができます。
お使いの IoT ハブに登録されているデバイス。 IoT ハブにデバイスがない場合は、「デバイスを登録する」の手順に従います。
Python バージョン 3.7 以降をお勧めします。必ず、セットアップに必要な 32 ビットまたは 64 ビットのインストールを使用してください。インストール中に求められた場合は、プラットフォーム固有の環境変数に Python を追加します。
ポート 8883 がファイアウォールで開放されていることを確認してください。この記事のデバイスサンプルでは、ポート 8883 を介して通信する MQTT プロトコルを使用しています。このポートは、企業や教育用のネットワーク環境によってはブロックされている場合があります。この問題の詳細と対処方法については、「IoT Hub への接続 (MQTT)」を参照してください。

IoT ハブ接続文字列を取得する

この記事では、デバイスツインに必要なプロパティを追加した後、ID レジストリに対してクエリを実行し、適切に更新された報告されるプロパティを持つデバイスをすべて検索するバックエンドサービスを作成します。そのサービスには、必要なデバイスツインのプロパティを変更するためのサービス接続アクセス許可と、ID レジストリに対してクエリを実行するためのレジストリ読み取りアクセス許可が必要となります。その 2 つのアクセス許可だけを含んだ既定の共有アクセスポリシーは存在しないため、共有アクセスポリシーを独自に作成する必要があります。

サービス接続とレジストリ読み取りのアクセス許可を付与する共有アクセスポリシーを作成し、そのポリシーの接続文字列を取得するには、次の手順を実行します。

Azure portal で、 [リソースグループ] を選択します。ハブが配置されているリソースグループを選択し、リソースの一覧からハブを選択します。
ハブの左側のウィンドウで、 [共有アクセスポリシー] を選択します。
ポリシー一覧の上にある最初のメニューから、[共有アクセスポリシーの追加] を選びます。
右側の [共有アクセスポリシーの追加] ウィンドウで、serviceAndRegistryRead などのポリシーのわかりやすい名前を入力します。 [アクセス許可] で [レジストリ読み取り] と [サービス接続] を選び、[追加] を選びます。
ポリシーの一覧から、新しいポリシーを選択します。
[プライマリ接続文字列] のコピーアイコンを選び、その値を保存します。

IoT Hub の共有アクセスポリシーとアクセス許可の詳細については、「アクセス制御とアクセス許可」を参照してください。

目的のプロパティおよびクエリツインを更新するサービスアプリを作成する

このセクションでは、{Device ID} に関連付けられたデバイスツインに場所のメタデータを追加する Python コンソールアプリを作成します。このアプリは、IoT ハブで米国内にあるデバイスのクエリを実行した後、携帯ネットワーク接続を報告しているデバイスのクエリを実行します。

作業ディレクトリでコマンドプロンプトを開き、Azure IoT Hub Service SDK for Python をインストールします。
```
pip install azure-iot-hub
```
テキストエディターを使用して、新しい AddTagsAndQuery.py ファイルを作成します。

Service SDK から必要なモジュールをインポートする次のコードを追加します。

import sys
from time import sleep
from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import Twin, TwinProperties, QuerySpecification, QueryResult

次のコードを追加します。 [IoTHub Connection String] を、「IoT ハブ接続文字列を取得する」でコピーしておいた IoT ハブ接続文字列に置き換えます。 [Device Id] を、IoT ハブの登録済みデバイスのデバイス ID (名前) に置き換えます。
```
IOTHUB_CONNECTION_STRING = "[IoTHub Connection String]"
DEVICE_ID = "[Device Id]"
```

次のコードを AddTagsAndQuery.py ファイルに追加します。

def iothub_service_sample_run():
    try:
        iothub_registry_manager = IoTHubRegistryManager(IOTHUB_CONNECTION_STRING)

        new_tags = {
                'location' : {
                    'region' : 'US',
                    'plant' : 'Redmond43'
                }
            }

        twin = iothub_registry_manager.get_twin(DEVICE_ID)
        twin_patch = Twin(tags=new_tags, properties= TwinProperties(desired={'power_level' : 1}))
        twin = iothub_registry_manager.update_twin(DEVICE_ID, twin_patch, twin.etag)

        # Add a delay to account for any latency before executing the query
        sleep(1)

        query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'")
        query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
        print("Devices in Redmond43 plant: {}".format(', '.join([twin.device_id for twin in query_result.items])))

        print()

        query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity = 'cellular'")
        query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
        print("Devices in Redmond43 plant using cellular network: {}".format(', '.join([twin.device_id for twin in query_result.items])))

    except Exception as ex:
        print("Unexpected error {0}".format(ex))
        return
    except KeyboardInterrupt:
        print("IoT Hub Device Twin service sample stopped")

IoTHubRegistryManager オブジェクトに、サービスからデバイスツインとやりとりするのに必要なすべてのメソッドが表示されます。最初のコードで IoTHubRegistryManager オブジェクトを初期化した後、DEVICE_ID のデバイスツインを更新し、最後に 2 つのクエリを実行します。最初のものでは Redmond43 工場にあるデバイスのデバイスツインのみを選択し、2 番目のものでは携帯ネットワーク経由で接続しているデバイスのみを選択します。

次のコードを AddTagsAndQuery.py の末尾に追加して、iothub_service_sample_run 関数を実装します。

if __name__ == '__main__':
    print("Starting the Python IoT Hub Device Twin service sample...")
    print()

    iothub_service_sample_run()

以下を使用してアプリケーションを実行します。
```
python AddTagsAndQuery.py
```
Redmond43 にあるすべてのデバイスを照会するクエリの結果には、1 件のデバイスが表示され、携帯ネットワークを使用するデバイスに絞り込んだ結果には 0 件のデバイスが表示されます。次のセクションでは、移動体通信ネットワークを使用するデバイスアプリを作成し、このクエリを再実行して、その変更を確認します。

報告されたプロパティを更新するデバイスアプリを作成する

このセクションでは、{Device ID} としてハブに接続される Python コンソールアプリを作成し、報告されたデバイスツインのプロパティを更新して、接続に携帯ネットワークが使用されていることを確認します。

作業ディレクトリのコマンドプロンプトから、Azure IoT Hub Device SDK for Python をインストールします。
```
pip install azure-iot-device
```
テキストエディターを使用して、新しい ReportConnectivity.py ファイルを作成します。
Device SDK から必要なモジュールをインポートする次のコードを追加します。
```
import time
from azure.iot.device import IoTHubModuleClient
```
次のコードを追加します。 [IoTHub Device Connection String] プレースホルダーの値を、IoT Hub でデバイスを登録した時に表示されたデバイス接続文字列に置き換えます。
```
CONNECTION_STRING = "[IoTHub Device Connection String]"
```

次のコードを ReportConnectivity.py ファイルに追加して、クライアントのインスタンスを作成し、デバイスツインの機能を実装します。

def create_client():
    # Instantiate client
    client = IoTHubModuleClient.create_from_connection_string(CONNECTION_STRING)

    # Define behavior for receiving twin desired property patches
    def twin_patch_handler(twin_patch):
        print("Twin patch received:")
        print(twin_patch)

    try:
        # Set handlers on the client
        client.on_twin_desired_properties_patch_received = twin_patch_handler
    except:
        # Clean up in the event of failure
        client.shutdown()

    return client

ReportConnectivity.py の最後に以下のコードを追加して、アプリケーションを実行します。

def main():
    print ( "Starting the Python IoT Hub Device Twin device sample..." )
    client = create_client()
    print ( "IoTHubModuleClient waiting for commands, press Ctrl-C to exit" )

    try:
        # Update reported properties with cellular information
        print ( "Sending data as reported property..." )
        reported_patch = {"connectivity": "cellular"}
        client.patch_twin_reported_properties(reported_patch)
        print ( "Reported properties updated" )

        # Wait for program exit
        while True:
            time.sleep(1000000)
    except KeyboardInterrupt:
        print ("IoT Hub Device Twin device sample stopped")
    finally:
        # Graceful exit
        print("Shutting down IoT Hub Client")
        client.shutdown()

if __name__ == '__main__':
    main()

デバイスアプリを実行する:
```
python ReportConnectivity.py
```
デバイスツインの報告されるプロパティが更新されたこと示す確認メッセージが表示されます。
これで、デバイスが接続情報を報告したため、両方のクエリで表示されるようになります。戻って、クエリをもう一度実行します。
```
python AddTagsAndQuery.py
```
今回は、 {Device ID} が両方のクエリ結果に表示されるはずです。

デバイスアプリで、サービスアプリによって送信された必要なプロパティツインパッチが受信されたことを確認するメッセージが表示されます。

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

バックエンドアプリからタグとしてデバイスメタデータを追加しました
デバイスツインでデバイス接続情報を報告しました
IoT Hub クエリ言語を使用して、デバイスツイン情報のクエリを実行しました

次のステップ

参照:

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

次の方法で共有

デバイスツインの概要 (Python)

前提条件

IoT ハブ接続文字列を取得する

目的のプロパティおよびクエリツインを更新するサービスアプリを作成する

報告されたプロパティを更新するデバイスアプリを作成する

次のステップ

フィードバック

その他のリソース

次の方法で共有

デバイス ツインの概要 (Python)

前提条件

IoT ハブ接続文字列を取得する

目的のプロパティおよびクエリ ツインを更新するサービス アプリを作成する

報告されたプロパティを更新するデバイス アプリを作成する

次のステップ

フィードバック

その他のリソース

デバイスツインの概要 (Python)

目的のプロパティおよびクエリツインを更新するサービスアプリを作成する

報告されたプロパティを更新するデバイスアプリを作成する