IoT Hub を使用したクラウドからデバイスへのメッセージの送信 (Java)

[アーティクル]
06/07/2023

Azure IoT Hub は、何百万ものデバイスとソリューションバックエンドの間に信頼性のある保護された双方向通信を確立するのに役立つ、フルマネージドのサービスです。

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

ソリューションバックエンドから IoT Hub 経由で単一のデバイスに cloud-to-device (C2D) メッセージを送信する
cloud-to-device メッセージをデバイスで受信する
ソリューションバックエンドから、IoT Hub からデバイスに送信されたメッセージの配信確認 ("フィードバック") を要求する

注意

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

この記事の最後に、次の 2 つの Java コンソールアプリを実行します。

HandleMessages: Microsoft Azure IoT SDK for Java に含まれているサンプルデバイスアプリ。これは、IoT ハブに接続し、cloud-to-device メッセージを受信します。
SendCloudToDevice: cloud-to-device メッセージを IoT Hub を介してデバイスアプリに送信し、その配信確認を受け取ります。

Note

IoT Hub には、Azure IoT device SDK を介して、多数のデバイスプラットフォームと言語 (C、Java、Python、JavaScript) に対する SDK サポートがあります。

cloud-to-device メッセージの詳細については、「IoT ハブから cloud-to-device メッセージを送信する」を参照してください。

前提条件

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

デバイスの接続文字列を取得する

この記事では、デバイスをシミュレートするサンプルアプリを実行します。これは、IoT Hub 経由で送信された cloud-to-device メッセージを受信します。 Microsoft Azure IoT SDK for Java に含まれる HandleMessages サンプルアプリは、IoT ハブに接続し、シミュレートされたデバイスとして動作します。このサンプルは、IoT ハブに登録されているデバイスのプライマリ接続文字列を使用します。

IoT ハブに登録されているデバイスのプライマリ接続文字列を取得するには、次の手順に従います。

Azure portal で、 [リソースグループ] を選択します。ハブが配置されているリソースグループを選択し、リソースの一覧からハブを選択します。
IoT ハブの左側ペインの [デバイス管理] の下にある [デバイス] を選択します。
デバイスの一覧から、該当するデバイスを選択します。
[プライマリ接続文字列] をコピーし、値を保存します。

デバイスアプリでメッセージを受信する

このセクションでは、HandleMessages サンプルデバイスアプリを実行して、IoT ハブ経由で送信された C2D メッセージを受信します。新しいコマンドプロンプトを開き、Azure IoT Java SDK を解凍したフォルダーの下の azure-iot-sdk-java\iothub\device\iot-device-samples\handle-messages フォルダーに移動します。 {Your device connection string} プレースホルダーの値を IoT ハブに登録されているデバイスからコピーしたデバイス接続文字列に置き換えて、次のコマンドを実行します。

mvn clean package -DskipTests
java -jar ./target/handle-messages-1.0.0-with-deps.jar "{Your device connection string}"

サンプルデバイスアプリが正常に起動して IoT ハブに接続すると、次のように出力されます。

5/22/2023 11:13:18 AM> Press Control+C at any time to quit the sample.
     
Starting...
Beginning setup.
Successfully read input parameters.
Using communication protocol MQTT.
2023-05-23 09:51:06,062 INFO (main) [com.microsoft.azure.sdk.iot.device.transport.ExponentialBackoffWithJitter] - NOTE: A new instance of ExponentialBackoffWithJitter has been created with the following properties. Retry Count: 2147483647, Min Backoff Interval: 100, Max Backoff Interval: 10000, Max Time Between Retries: 100, Fast Retry Enabled: true
2023-05-23 09:51:06,187 DEBUG (main) [com.microsoft.azure.sdk.iot.device.ClientConfiguration] - Device configured to use software based SAS authentication provider
2023-05-23 09:51:06,187 INFO (main) [com.microsoft.azure.sdk.iot.device.transport.ExponentialBackoffWithJitter] - NOTE: A new instance of ExponentialBackoffWithJitter has been created with the following properties. Retry Count: 2147483647, Min Backoff Interval: 100, Max Backoff Interval: 10000, Max Time Between Retries: 100, Fast Retry Enabled: true
2023-05-23 09:51:06,202 DEBUG (main) [com.microsoft.azure.sdk.iot.device.DeviceClient] - Initialized a DeviceClient instance using SDK version 2.1.5
Successfully created an IoT Hub client.
Successfully set message callback.
2023-05-23 09:51:06,205 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.MqttIotHubConnection] - Opening MQTT connection...
2023-05-23 09:51:06,218 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sending MQTT CONNECT packet...
2023-05-23 09:51:07,308 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sent MQTT CONNECT packet was acknowledged
2023-05-23 09:51:07,308 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sending MQTT SUBSCRIBE packet for topic devices/US60536-device/messages/devicebound/#
2023-05-23 09:51:07,388 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sent MQTT SUBSCRIBE packet for topic devices/US60536-device/messages/devicebound/# was acknowledged
2023-05-23 09:51:07,388 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.MqttIotHubConnection] - MQTT connection opened successfully
2023-05-23 09:51:07,388 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - The connection to the IoT Hub has been established
2023-05-23 09:51:07,404 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Updating transport status to new status CONNECTED with reason CONNECTION_OK
2023-05-23 09:51:07,404 DEBUG (main) [com.microsoft.azure.sdk.iot.device.DeviceIO] - Starting worker threads
2023-05-23 09:51:07,408 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Invoking connection status callbacks with new status details

CONNECTION STATUS UPDATE: CONNECTED
CONNECTION STATUS REASON: CONNECTION_OK
CONNECTION STATUS THROWABLE: null

The connection was successfully established. Can send messages.
2023-05-23 09:51:07,408 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Client connection opened successfully
2023-05-23 09:51:07,408 INFO (main) [com.microsoft.azure.sdk.iot.device.DeviceClient] - Device client opened successfully
Opened connection to IoT Hub. Messages sent to this device will now be received.
Press any key to exit...

AppMessageCallback クラスの execute メソッドは、IotHubMessageResult.COMPLETE を返します。この状態によって、メッセージが正常に処理されたこと、およびメッセージはデバイスのキューから安全に削除できることが IoT Hub に通知されます。デバイスは、使用しているプロトコルに関係なく、処理が正常に完了したときに、この値を返す必要があります。

MQTT ではなく AMQP と HTTPS を使用する場合、デバイスは次の処理もできます。

メッセージを破棄します。この場合、IoT Hub は将来の使用に備えてメッセージをデバイスのキュー内に保持します。
メッセージを拒否します。この場合、メッセージはデバイスのキューから完全に削除されます。

デバイスがメッセージを完了、破棄、または拒否することを妨げる問題が発生した場合、IoT Hub は一定のタイムアウト期間が経過した後で、メッセージの配信をキューに入れます。このような理由から、同じメッセージを複数回受信した場合に生成される結果が毎回同じになるように、デバイスアプリ内のメッセージ処理ロジックをべき等にする必要があります。

cloud-to-device メッセージのライフサイクルと、IoT Hub が cloud-to-device メッセージを処理する方法の詳細については、「IoT ハブから cloud-to-device メッセージを送信する」を参照してください。

注意

トランスポートとして AMQP の代わりに HTTPS を使用した場合、DeviceClient インスタンスが IoT Hub からのメッセージをチェックする頻度は低くなります (最小 25 分の間隔)。 MQTT、AMQP、および HTTPS のサポートの相違点の詳細については、「cloud-to-device 通信に関するガイダンス」と「通信プロトコルの選択」を参照してください。

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

この記事では、IoT Hub を介して cloud-to-device メッセージを送信するバックエンドサービスを作成します。 cloud-to-device メッセージを送信するサービスには、サービス接続のアクセス許可が必要となります。既定では、どの IoT Hub も、このアクセス許可を付与する service という名前の共有アクセスポリシーがある状態で作成されます。

サービス ポリシーの IoT Hub 接続文字列を取得するには、次の手順を実行します。

Azure portal で、 [リソースグループ] を選択します。ハブが配置されているリソースグループを選択し、リソースの一覧からハブを選択します。
IoT ハブの左側のウィンドウで、 [共有アクセスポリシー] を選択します。
ポリシーの一覧から、サービス ポリシーを選択します。
[プライマリ接続文字列] をコピーし、値を保存します。

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

C2D メッセージを送信する

このセクションでは、クラウドからデバイスへのメッセージを、シミュレーション済みデバイスアプリに送信する Java コンソールアプリを作成します。デバイスからのデバイス ID と IoT ハブの接続文字列が必要です。

コマンドプロンプトで次のコマンドを使用して、send-c2d-messages という Maven プロジェクトを作成します。このコマンドが 1 つの長いコマンドであることに注意してください。
```
mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=send-c2d-messages -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
```
コマンドプロンプトで、新しい send-c2d-messages フォルダーに移動します。
テキストエディターを使用して、send-c2d-messages フォルダー内の pom.xml ファイルを開き、次の依存関係を dependencies ノードに追加します。依存関係を追加することにより、アプリケーションの iothub-java-service-client パッケージを使用して、IoT Hub サービスと通信できます。
```
<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-service-client</artifactId>
  <version>1.7.23</version>
</dependency>
```
注意

Maven 検索を使用して、iot-service-client の最新バージョンを確認できます。
pom.xml ファイルを保存して閉じます。
テキストエディターを使用し、send-c2d-messages\src\main\java\com\mycompany\app\App.java ファイルを開きます。

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

import com.microsoft.azure.sdk.iot.service.*;
import java.io.IOException;
import java.net.URISyntaxException;

次のクラスレベルの変数を App クラスに追加し、 {yourhubconnectionstring} と {yourdeviceid} を先にメモした値に置き換えます。

private static final String connectionString = "{yourhubconnectionstring}";
private static final String deviceId = "{yourdeviceid}";
private static final IotHubServiceClientProtocol protocol =    
    IotHubServiceClientProtocol.AMQPS;

main メソッドを次のコードで置き換えます。このコードは、IoT Hub に接続し、デバイスにメッセージを送信して、デバイスがメッセージを受信して処理したことを示す受信確認を受け取るまで待機します。

public static void main(String[] args) throws IOException,
    URISyntaxException, Exception {
  ServiceClient serviceClient = ServiceClient.createFromConnectionString(
    connectionString, protocol);

  if (serviceClient != null) {
    serviceClient.open();
    FeedbackReceiver feedbackReceiver = serviceClient
      .getFeedbackReceiver();
    if (feedbackReceiver != null) feedbackReceiver.open();

    Message messageToSend = new Message("Cloud to device message.");
    messageToSend.setDeliveryAcknowledgement(DeliveryAcknowledgement.Full);

    serviceClient.send(deviceId, messageToSend);
    System.out.println("Message sent to device");

    FeedbackBatch feedbackBatch = feedbackReceiver.receive(10000);
    if (feedbackBatch != null) {
      System.out.println("Message feedback received, feedback time: "
        + feedbackBatch.getEnqueuedTimeUtc().toString());
    }

    if (feedbackReceiver != null) feedbackReceiver.close();
    serviceClient.close();
  }
}

注意

わかりやすくするために、この記事では再試行ポリシーは実装しません。運用環境のコードでは、「一時的な障害の処理」の記事で推奨されているように、再試行ポリシー (指数関数的バックオフなど) を実装することをお勧めします。

Maven を使用して send-c2d-messages アプリをビルドするには、コマンドプロンプトで simulated-device フォルダーに移動し、次のコマンドを実行します。
```
mvn clean package -DskipTests
```

アプリケーションの実行

これで、アプリケーションを実行する準備が整いました。

azure-iot-sdk-java\iothub\device\iot-device-samples\handle-messages フォルダーのコマンドプロンプトで、{Your device connection string} プレースホルダーの値を IoT ハブの登録済みデバイスからコピーしたデバイス接続文字列に置き換えて次のコマンドを実行します。この手順は、IoT ハブにテレメトリを送信し、ハブから送信された cloud-to-device メッセージをリッスンするサンプルデバイスアプリを開始します。
```
java -jar ./target/handle-messages-1.0.0-with-deps.jar "{Your device connection string}"
```
コマンドプロンプトの send-c2d-messages フォルダーで、次のコマンドを実行して cloud-to-device メッセージを送信し、フィードバックの確認を待機します。
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```

次のステップ

この記事では、cloud-to-device メッセージを送受信する方法を学習しました。

cloud-to-device メッセージの詳細については、「IoT ハブから cloud-to-device メッセージを送信する」を参照してください。
IoT Hub メッセージ形式の詳細については、「IoT Hub メッセージを作成し、読み取る」を参照してください。