デバイスツインの使用 (Node.js)

[アーティクル]
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 つの Node.js コンソールアプリを作成します。

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

Note

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

前提条件

この記事を完了するには、以下が必要です。

IoT Hub。 CLI または Azure portal を使って作成します。
登録済みのデバイス。 Azure portal に登録してください。
Node.js バージョン 10.0.x 以降。
ポート 8883 がファイアウォールで開放されていることを確認してください。この記事のデバイスサンプルでは、ポート 8883 を介して通信する MQTT プロトコルを使用しています。このポートは、企業や教育用のネットワーク環境によってはブロックされている場合があります。この問題の詳細と対処方法については、「IoT Hub への接続 (MQTT)」を参照してください。

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

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

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

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

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

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

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

reportconnectivity という名前の新しい空のフォルダーを作成します。 reportconnectivity フォルダー内に、コマンドプロンプトで次のコマンドを使用して新しい package.json ファイルを作成します。 --yes パラメーターではすべての既定値を使用できます。
```
npm init --yes
```
reportconnectivity フォルダーのコマンドプロンプトで、次のコマンドを実行して、azure-iot-device パッケージと azure-iot-device-mqtt パッケージをインストールします。
```
npm install azure-iot-device azure-iot-device-mqtt --save
```
テキストエディターを使用して、reportconnectivity フォルダーに新しいReportConnectivity.js ファイルを作成します。

次のコードを ReportConnectivity.js ファイルに追加します。 {device connection string} を、「IoT ハブにデバイスを登録する」で表示されたデバイス接続文字列に置き換えます。

    'use strict';
    var Client = require('azure-iot-device').Client;
    var Protocol = require('azure-iot-device-mqtt').Mqtt;

    var connectionString = '{device connection string}';
    var client = Client.fromConnectionString(connectionString, Protocol);

    client.open(function(err) {
    if (err) {
        console.error('could not open IotHub client');
    }  else {
        console.log('client opened');

        client.getTwin(function(err, twin) {
        if (err) {
            console.error('could not get twin');
        } else {
            var patch = {
                connectivity: {
                    type: 'cellular'
                }
            };

            twin.properties.reported.update(patch, function(err) {
                if (err) {
                    console.error('could not update twin');
                } else {
                    console.log('twin state reported');
                    process.exit();
                }
            });
        }
        });
    }
    });

Client オブジェクトに、デバイスからデバイスツインとやりとりするのに必要なすべてのメソッドが表示されます。前のコードでは、Client オブジェクトを初期化した後、myDeviceId のデバイスツインを取得して、報告されるプロパティに接続情報を含めるよう更新します。

デバイスアプリを実行する
```
    node ReportConnectivity.js
```
twin state reported というメッセージが表示されます。
これで、デバイスが接続情報を報告したため、両方のクエリで表示されるようになります。 addtagsandqueryapp フォルダーに戻り、クエリを再度実行します。
```
    node AddTagsAndQuery.js
```
今回は、myDeviceId が両方のクエリ結果に表示されるはずです。

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

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

addtagsandqueryapp という名前の新しい空のフォルダーを作成します。 addtagsandqueryapp フォルダー内に、コマンドプロンプトで次のコマンドを使用して新しい package.json ファイルを作成します。 --yes パラメーターではすべての既定値を使用できます。
```
npm init --yes
```
コマンドプロンプトで、addtagsandqueryapp フォルダーに移動し、次のコマンドを実行して、azure-iothub パッケージをインストールします。
```
npm install azure-iothub --save
```
テキストエディターを使用して、addtagsandqueryapp フォルダーに新しい AddTagsAndQuery.js ファイルを作成します。

次のコードを AddTagsAndQuery.js ファイルに追加します。 {iot hub connection string} を、「IoT ハブ接続文字列を取得する」でコピーしておいた IoT ハブ接続文字列に置き換えます。

     'use strict';
     var iothub = require('azure-iothub');
     var connectionString = '{iot hub connection string}';
     var registry = iothub.Registry.fromConnectionString(connectionString);

     registry.getTwin('myDeviceId', function(err, twin){
         if (err) {
             console.error(err.constructor.name + ': ' + err.message);
         } else {
             var patch = {
                 tags: {
                     location: {
                         region: 'US',
                         plant: 'Redmond43'
                   }
                 }
             };

             twin.update(patch, function(err) {
               if (err) {
                 console.error('Could not update twin: ' + err.constructor.name + ': ' + err.message);
               } else {
                 console.log(twin.deviceId + ' twin updated successfully');
                 queryTwins();
               }
             });
         }
     });

Registry オブジェクトに、サービスからデバイスツインとやりとりするのに必要なすべてのメソッドが表示されます。前のコードでは、まず Registry オブジェクトを初期化し、myDeviceId のデバイスツインを取得して、最後にタグを目的の位置情報で更新します。

タグの更新後、queryTwins 関数を呼び出します。

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

     var queryTwins = function() {
         var query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
         query.nextAsTwin(function(err, results) {
             if (err) {
                 console.error('Failed to fetch the results: ' + err.message);
             } else {
                 console.log("Devices in Redmond43: " + results.map(function(twin) {return twin.deviceId}).join(','));
             }
         });

         query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
         query.nextAsTwin(function(err, results) {
             if (err) {
                 console.error('Failed to fetch the results: ' + err.message);
             } else {
                 console.log("Devices in Redmond43 using cellular network: " + results.map(function(twin) {return twin.deviceId}).join(','));
             }
         });
     };

前のコードは 2 つのクエリを実行します。1 つ目では、Redmond43 工場にあるデバイスのデバイスツインのみを選択し、2 つ目のクエリで携帯ネットワーク経由で接続しているデバイスのみを選択するよう絞り込みます。

コードでクエリ オブジェクトが作成されると、2 番目のパラメーターで返されるドキュメントの最大数が指定されます。 query オブジェクトには、nextAsTwin メソッドを複数回呼び出してすべての結果を取得する際に使用できる hasMoreResults のブール型プロパティが含まれます。 next というメソッドは、集計クエリの結果など、デバイスツインではない結果で使用できます。

以下を使用してアプリケーションを実行します。
```
    node AddTagsAndQuery.js
```
Redmond43 にあるすべてのデバイスを照会するクエリの結果には、1 件のデバイスが表示され、携帯ネットワークを使用するデバイスに絞り込んだ結果には 0 件のデバイスが表示されます。

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

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

次のステップ

参照:

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

デバイス ツインの使用 (Node.js)

前提条件

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

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

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

次のステップ

その他のリソース

デバイスツインの使用 (Node.js)

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

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