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

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

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

Note

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

前提条件

Azure サブスクリプション内の IoT ハブ。ハブがまだない場合は、「IoT ハブの作成」の手順に従うことができます。
お使いの IoT ハブに登録されているデバイス。 IoT ハブにデバイスがない場合は、「デバイスを登録する」の手順に従います。
Java SE Development Kit 8。 JDK 8 のダウンロードを利用するには、「長期サポート」の「Java 8」を選択します。
Maven 3
ポート 8883 がファイアウォールで開放されていることを確認してください。この記事のデバイスサンプルでは、ポート 8883 を介して通信する MQTT プロトコルを使用しています。このポートは、企業や教育用のネットワーク環境によってはブロックされている場合があります。この問題の詳細と対処方法については、「IoT Hub への接続 (MQTT)」を参照してください。

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

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

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

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

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

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

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

コマンドプロンプトで次のコマンドを使用して、iot-java-twin-getstarted フォルダー内に simulated-device という名前の Maven プロジェクトを作成します。
```
mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=simulated-device -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
```
コマンドプロンプトで、simulated-device フォルダーに移動します。
テキストエディターを使用して、simulated-device フォルダー内の pom.xml ファイルを開き、次の依存関係を dependencies ノードに追加します。この依存関係により、アプリの iot-device-client パッケージを使用して IoT ハブと通信できるようになります。
```
<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-device-client</artifactId>
  <version>1.17.5</version>
</dependency>
```
注意

Maven 検索を使用して、iot-device-client の最新バージョンを確認できます。
dependencies ノードに、次の依存関係を追加します。この依存関係によって、Apache SLF4J ログ記録ファサード用の NOP が構成され、ログ記録を実装するためにデバイスクライアント SDK によって使用されます。この構成は省略可能ですが、省略した場合、アプリの実行時にコンソールに警告が表示される可能性があります。デバイスクライアント SDK でのログ記録の詳細については、Samples for the Azure IoT device SDK for Java readme ファイルに含まれているログ記録を参照してください。
```
<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-nop</artifactId>
  <version>1.7.28</version>
</dependency>
```

dependencies ノードの後に、次の build ノードを追加します。この構成では、Java 1.8 を使用してアプリをビルドするように Maven に指示しています。

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-compiler-plugin</artifactId>
      <version>3.3</version>
      <configuration>
        <source>1.8</source>
        <target>1.8</target>
      </configuration>
    </plugin>
  </plugins>
</build>

pom.xml ファイルを保存して閉じます。
テキストエディターを使用して、simulated-device\src\main\java\com\mycompany\app\App.java ファイルを開きます。

ファイルに次の import ステートメントを追加します。

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.DeviceTwin.*;

import java.io.IOException;
import java.net.URISyntaxException;
import java.util.Scanner;

次のクラスレベル変数を App クラスに追加します。 {yourdeviceconnectionstring} を、「IoT ハブにデバイスを登録する」で表示されたデバイス接続文字列に置き換えます。
```
private static String connString = "{yourdeviceconnectionstring}";
private static IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
private static String deviceId = "myDeviceId";
```
このサンプルアプリでは、DeviceClient オブジェクトをインスタンス化するときに protocol 変数が使用されます。

デバイスツインの更新に関する情報を出力するには、次のメソッドを App クラスに追加します。

protected static class DeviceTwinStatusCallBack implements IotHubEventCallback {
    @Override
    public void execute(IotHubStatusCode status, Object context) {
      System.out.println("IoT Hub responded to device twin operation with status " + status.name());
    }
  }

main メソッドのコードを次のコードに置き換えます。

IoT Hub と通信するデバイスクライアントを作成します。
デバイスツインのプロパティを格納する Device オブジェクトを作成します。

DeviceClient client = new DeviceClient(connString, protocol);

// Create a Device object to store the device twin properties
Device dataCollector = new Device() {
  // Print details when a property value changes
  @Override
  public void PropertyCall(String propertyKey, Object propertyValue, Object context) {
    System.out.println(propertyKey + " changed to " + propertyValue);
  }
};

報告されるプロパティ connectivityType を作成して IoT Hub に送信する次のコードを main メソッドに追加します。

try {
  // Open the DeviceClient and start the device twin services.
  client.open();
  client.startDeviceTwin(new DeviceTwinStatusCallBack(), null, dataCollector, null);

  // Create a reported property and send it to your IoT hub.
  dataCollector.setReportedProp(new Property("connectivityType", "cellular"));
  client.sendReportedProperties(dataCollector.getReportedProp());
}
catch (Exception e) {
  System.out.println("On exception, shutting down \n" + " Cause: " + e.getCause() + " \n" + e.getMessage());
  dataCollector.clean();
  client.closeNow();
  System.out.println("Shutting down...");
}

次のコードを main メソッドの末尾に追加します。 Enter キーが押されるまで待機することで、IoT Hub がデバイスツイン操作の状態を報告するための時間を取ることができます。
```
System.out.println("Press any key to exit...");

Scanner scanner = new Scanner(System.in);
scanner.nextLine();

dataCollector.clean();
client.close();
```
main メソッドのシグネチャを変更し、下の例外を追加します。
```
public static void main(String[] args) throws URISyntaxException, IOException
```
simulated-device\src\main\java\com\mycompany\app\App.java ファイルを保存して閉じます。
simulated-device アプリをビルドし、エラーを修正します。コマンドプロンプトで simulated-device フォルダーに移動し、次のコマンドを実行します。
```
mvn clean package -DskipTests
```

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

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

開発用コンピューターで、iot-java-twin-getstarted という名前の空のフォルダーを作成します。
コマンドプロンプトで次のコマンドを使用して、iot-java-twin-getstarted フォルダー内に add-tags-query という名前の Maven プロジェクトを作成します。
```
mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=add-tags-query -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
```
コマンドプロンプトで、add-tags-query フォルダーに移動します。
テキストエディターを使用して、add-tags-query フォルダー内の pom.xml ファイルを開き、次の依存関係を dependencies ノードに追加します。この依存関係により、アプリで iot-service-client パッケージを使用して IoT Hub と通信できるようになります。
```
<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-service-client</artifactId>
  <version>1.17.1</version>
  <type>jar</type>
</dependency>
```
注意

Maven 検索を使用して、iot-service-client の最新バージョンを確認できます。

dependencies ノードの後に、次の build ノードを追加します。この構成では、Java 1.8 を使用してアプリをビルドするように Maven に指示しています。

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-compiler-plugin</artifactId>
      <version>3.3</version>
      <configuration>
        <source>1.8</source>
        <target>1.8</target>
      </configuration>
    </plugin>
  </plugins>
</build>

pom.xml ファイルを保存して閉じます。
テキストエディターを使用して、add-tags-query\src\main\java\com\mycompany\app\App.java ファイルを開きます。

ファイルに次の import ステートメントを追加します。

import com.microsoft.azure.sdk.iot.service.devicetwin.*;
import com.microsoft.azure.sdk.iot.service.exceptions.IotHubException;

import java.io.IOException;
import java.util.HashSet;
import java.util.Set;

次のクラスレベル変数を App クラスに追加します。 {youriothubconnectionstring} を、「IoT ハブ接続文字列を取得する」でコピーしておいた IoT ハブ接続文字列に置き換えます。

public static final String iotHubConnectionString = "{youriothubconnectionstring}";
public static final String deviceId = "myDeviceId";

public static final String region = "US";
public static final String plant = "Redmond43";

main メソッドのシグネチャを、次の throws 句を含むように更新します。
```
public static void main( String[] args ) throws IOException
```
main メソッドのコードを、DeviceTwin オブジェクトと DeviceTwinDevice オブジェクトを作成する次のコードに置き換えます。 DeviceTwin オブジェクトは、IoT Hub との通信を処理します。 DeviceTwinDevice オブジェクトは、プロパティとタグを使用してデバイスツインを表現します。
```
// Get the DeviceTwin and DeviceTwinDevice objects
DeviceTwin twinClient = DeviceTwin.createFromConnectionString(iotHubConnectionString);
DeviceTwinDevice device = new DeviceTwinDevice(deviceId);
```

次の try/catch ブロックを main メソッドに追加します。

try {
  // Code goes here
} catch (IotHubException e) {
  System.out.println(e.getMessage());
} catch (IOException e) {
  System.out.println(e.getMessage());
}

デバイスツインの region タグと plant タグを更新するには、次のコードを try ブロックに追加します。

// Get the device twin from IoT Hub
System.out.println("Device twin before update:");
twinClient.getTwin(device);
System.out.println(device);

// Update device twin tags if they are different
// from the existing values
String currentTags = device.tagsToString();
if ((!currentTags.contains("region=" + region) && !currentTags.contains("plant=" + plant))) {
  // Create the tags and attach them to the DeviceTwinDevice object
  Set<Pair> tags = new HashSet<Pair>();
  tags.add(new Pair("region", region));
  tags.add(new Pair("plant", plant));
  device.setTags(tags);

  // Update the device twin in IoT Hub
  System.out.println("Updating device twin");
  twinClient.updateTwin(device);
}

// Retrieve the device twin with the tag values from IoT Hub
System.out.println("Device twin after update:");
twinClient.getTwin(device);
System.out.println(device);

IoT hub でデバイスツインのクエリを実行するには、前の手順で追加した try ブロックの後ろに次のコードを追加します。このコードは、2 つのクエリを実行します。各クエリでは、最大 100 台のデバイスが返されます。

// Query the device twins in IoT Hub
System.out.println("Devices in Redmond:");

// Construct the query
SqlQuery sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43'", null);

// Run the query, returning a maximum of 100 devices
Query twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 100);
while (twinClient.hasNextDeviceTwin(twinQuery)) {
  DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
  System.out.println(d.getDeviceId());
}

System.out.println("Devices in Redmond using a cellular network:");

// Construct the query
sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43' AND properties.reported.connectivityType = 'cellular'", null);

// Run the query, returning a maximum of 100 devices
twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 3);
while (twinClient.hasNextDeviceTwin(twinQuery)) {
  DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
  System.out.println(d.getDeviceId());
}

add-tags-query\src\main\java\com\mycompany\app\App.java ファイルを保存して閉じます。
add-tags-query アプリをビルドし、エラーを修正します。コマンドプロンプトで add-tags-query フォルダーに移動し、次のコマンドを実行します。
```
mvn clean package -DskipTests
```

アプリの実行

これで、コンソールアプリを実行する準備が整いました。

add-tags-query フォルダーのコマンドプロンプトで、次のコマンドを実行して、add-tags-query サービスアプリを実行します。
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
デバイスツインに plant タグと region タグが追加されていることを確認できます。最初のクエリはデバイスを返しますが、2 つ目のクエリは返しません。
simulated-device フォルダーのコマンドプロンプトで、次のコマンドを実行して、報告されるプロパティ connectivityType をデバイスツインに追加します。
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
add-tags-query フォルダーのコマンドプロンプトで、次のコマンドを実行して、add-tags-query サービスアプリの 2 回目の実行を行います。
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
デバイスによって connectivityType プロパティが IoT Hub に送信されているため、2 回目のクエリではデバイスが返ります。

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

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

次のステップ

参照:

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

次の方法で共有

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

前提条件

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

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

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

アプリの実行

次のステップ

フィードバック

その他のリソース

次の方法で共有

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

前提条件

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

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

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

アプリの実行

次のステップ

フィードバック

その他のリソース

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

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

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