cloud-to-device メッセージを送受信する

cloud-to-device メッセージを受信する

このセクションでは、Azure IoT SDK for .NET の DeviceClient クラスを使用して、cloud-to-device メッセージを受信する方法について説明します。

デバイス クライアント アプリケーションがメッセージの受信に使用できるオプションは 2 つあります。

• ポーリング: デバイス アプリケーションは、コード ループ (たとえば、while または for ループ) を使用して新しい IoT Hub メッセージをチェックします。 ループは継続的に実行され、メッセージがチェックされます。
• コールバック: デバイス アプリケーションは、メッセージが到着するとすぐに呼び出される非同期メッセージ ハンドラー メソッドを設定します。

DeviceClient オブジェクトを宣言する

DeviceClient には、IoT Hub からメッセージを受信するために必要なメソッドとプロパティが含まれています。

次に例を示します。

static DeviceClient deviceClient;

接続パラメーターを指定する

CreateFromConnectionString メソッドを使用して、IoT Hub のプライマリ接続文字列とデバイス ID を DeviceClient に指定します。 必要な IoT Hub プライマリ接続文字列に加えて、CreateFromConnectionString メソッドをオーバーロードして、次の "省略可能な" パラメーターを含めることができます。

• transportType - トランスポート プロトコル: HTTP バージョン 1、AMQP、または MQTT のバリエーション。 AMQP は既定値です。 使用可能なすべての値を表示するには、「TransportType 列挙型」を参照してください。
• transportSettings - DeviceClient と ModuleClient のさまざまなトランスポート固有の設定を定義するために使用されるインターフェイス。 詳細については、「ITransportSettings インターフェイス」を参照してください。
• ClientOptions - 初期化中にデバイスまたはモジュール クライアント インスタンスの構成を許可するオプション。

この例では、CreateFromConnectionString を呼び出して、DeviceClient 接続 IoT ハブとデバイス ID の設定を定義します。

static string connectionString = "{your IoT hub connection string}";
static string deviceID = "{your device ID}";
deviceClient = DeviceClient.CreateFromConnectionString(connectionString,deviceID);

ポーリング

ポーリングでは、ReceiveAsync を使用してメッセージをチェックします。

ReceiveAsync の呼び出しには、次の形式を使用できます。

• ReceiveAsync() - メッセージの既定のタイムアウト期間を待機してから続行します。
• ReceiveAsync (Timespan) - 特定のタイムアウトを使用して、デバイス キューからメッセージを受信します。
• ReceiveAsync (CancellationToken) - キャンセル トークンを使用して、デバイス キューからメッセージを受信します。 キャンセル トークンを使用する場合、既定のタイムアウト期間は使用されません。

MQTT または AMQP の代わりに HTTP 1 のトランスポート型を使用すると、ReceiveAsync メソッドはすぐに返されます。 HTTP 1 を使用する cloud-to-device メッセージに関してサポートされているパターンは、メッセージを低頻度 (最小 25 分の間隔) でチェックする、断続的に接続されるデバイスです。 HTTP 1 受信の発行が多くなれば、IoT Hub で要求が調整されます。 MQTT、AMQP、および HTTP 1 のサポートの相違点の詳細については、「cloud-to-device 通信に関するガイダンス」と「通信プロトコルの選択」を参照してください。

CompleteAsync メソッド

デバイスがメッセージを受信すると、デバイス アプリケーションは CompleteAsync メソッドを呼び出して、メッセージが正常に処理され、メッセージを IoT Hub デバイス キューから安全に削除できることを IoT Hub に通知します。 デバイスは、使用しているトランスポート プロトコルに関係なく、処理が正常に完了したときに、このメソッドを呼び出す必要があります。

メッセージの破棄、拒否、またはタイムアウト

MQTT プロトコルではできませんが、AMQP および HTTP バージョン 1 プロトコルでは、デバイスは次のこともできます。

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

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

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

ポーリング ループ

ポーリングを使用するアプリケーションでは、ReceiveAsync メソッドを繰り返し呼び出すコード ループを使用して、停止するまで新しいメッセージを確認します。

タイムアウト値または既定のタイムアウトで ReceiveAsync を使用する場合は、ループ内の ReceiveAsync の呼び出しごとに、指定されたタイムアウト期間を待機します。 ReceiveAsync がタイムアウトすると、null 値が返され、ループが続行されます。

メッセージを受信すると、Task オブジェクトが ReceiveAsync によって返され、CompleteAsync に渡されます。 CompleteAsync の呼び出しは、Task パラメーターに基づいて、指定したメッセージをメッセージ キューから削除するよう IoT Hub に通知します。

この例では、メッセージを受信するか、ポーリング ループが停止するまで、ループが ReceiveAsync を呼び出します。

static bool stopPolling = false;

while (!stopPolling)
{
   // Check for a message. Wait for the default DeviceClient timeout period.
   using Message receivedMessage = await _deviceClient.ReceiveAsync();

   // Continue if no message was received
   if (receivedMessage == null)
   {
      continue;
   }
   else  // A message was received
   {
      // Print the message received
      Console.WriteLine($"{DateTime.Now}> Polling using ReceiveAsync() - received message with Id={receivedMessage.MessageId}");
      PrintMessage(receivedMessage);

      // Notify IoT Hub that the message was received. IoT Hub will delete the message from the message queue.
      await _deviceClient.CompleteAsync(receivedMessage);
      Console.WriteLine($"{DateTime.Now}> Completed C2D message with Id={receivedMessage.MessageId}.");
   }

   // Check to see if polling loop should end
   stopPolling = ShouldPollingstop ();
}

Callback

デバイス アプリケーションでコールバック cloud-to-device メッセージを受信するには、アプリケーションが IoT Hub に接続し、受信メッセージを処理するためのコールバック リスナーを設定する必要があります。 デバイスへの受信メッセージは、IoT Hub メッセージ キューから受信されます。

コールバックを使用して、デバイス アプリケーションは、SetReceiveMessageHandlerAsync を使用してメッセージ ハンドラー メソッドを設定します。 メッセージ ハンドラーが呼び出され、メッセージが受信されます。 メッセージを受信するコールバック メソッドを作成すると、受信したメッセージを継続的にポーリングする必要がなくなります。

コールバックは、次のプロトコルでのみ使用可能になります。

• Mqtt
• Mqtt_WebSocket_Only
• Mqtt_Tcp_Only
• Amqp
• Amqp_WebSocket_Only
• Amqp_Tcp_only

Http1 プロトコル オプションはコールバックをサポートしていません。これは、SDK メソッドが受信したメッセージをポーリングする必要があるためで、これによりコールバックの原則が無効になります。

この例で、SetReceiveMessageHandlerAsync は、メッセージを受信するたびに呼び出される OnC2dMessageReceivedAsync という名前のコールバック ハンドラー メソッドを設定します。

// Subscribe to receive C2D messages through a callback (which isn't supported over HTTP).
await deviceClient.SetReceiveMessageHandlerAsync(OnC2dMessageReceivedAsync, deviceClient);
Console.WriteLine($"\n{DateTime.Now}> Subscribed to receive C2D messages over callback.");

メッセージの受信再試行ポリシー

デバイス クライアント メッセージ再試行ポリシーは、DeviceClient.SetRetryPolicy を使用して定義できます。

メッセージ再試行タイムアウトは、DeviceClient.OperationTimeoutInMilliseconds プロパティに格納されます。

SDK 受信メッセージのサンプル

.NET/C# SDK には、このセクションで説明する受信メッセージ メソッドを含む Message Receive サンプルが含まれています。

C2D メッセージの送信

このセクションでは、Azure IoT SDK for .NET の ServiceClient クラスを使用して、ソリューション バックエンド アプリケーションから IoT デバイスにメッセージを送信するための重要なコードについて説明します。 前に説明したように、ソリューション バックエンド アプリケーションは IoT Hub に接続し、メッセージは宛先デバイスでエンコードされて IoT Hub に送信されます。 IoT Hub は受信メッセージをメッセージ キューに格納し、メッセージは IoT Hub メッセージ キューからターゲット デバイスに配信されます。

ソリューション バックエンド アプリケーションは、メッセージ キューを介したデバイス配信を宛先とする、IoT Hub に送信されたメッセージの配信フィードバックを要求および受信することもできます。

ServiceClient オブジェクトを宣言する

ServiceClient には、IoT Hub 経由でアプリケーションからデバイスにメッセージを送信するために必要なメソッドとプロパティが含まれています。

static ServiceClient serviceClient;

接続文字列を指定する

CreateFromConnectionString メソッドを使用して、IoT Hub のプライマリ接続文字列を ServiceClient に指定します。 必要な IoT Hub プライマリ接続文字列に加えて、CreateFromConnectionString メソッドをオーバーロードして、次の "省略可能な" パラメーターを含めることができます。

• transportType - Amqp または Amqp_WebSocket_Only。
• transportSettings - サービス クライアントの AMQP および HTTP プロキシ設定。
• ServiceClientOptions - 初期化中にサービス クライアント インスタンスの構成を許可するオプション。 詳細については、ServiceClientOptions の説明を参照してください。

この例では、IoT Hub 接続文字列を使用して ServiceClient オブジェクトを作成します。

static string connectionString = "{your iot hub connection string}";
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);

非同期の cloud-to-device メッセージを送信する

sendAsync を使用して、クラウド (IoT Hub) 経由でアプリケーションからデバイスに非同期メッセージを送信します。 呼び出しは AMQP プロトコルを使用して行われます。

sendAsync は次のパラメーターを使用します。

• deviceID - ターゲット デバイスの文字列識別子。
• message - cloud-to-device メッセージ。 メッセージは Message 型であり、適宜書式設定できます。
• timeout - "省略可能な" タイムアウト値。 既定値は、指定しない場合は 1 分です。

この例では、10 秒のタイムアウト値を持つテスト メッセージをターゲット デバイスに送信します。

string targetDevice = "Device-1";
static readonly TimeSpan operationTimeout = TimeSpan.FromSeconds(10);
var commandMessage = new
Message(Encoding.ASCII.GetBytes("Cloud to device message."));
await serviceClient.SendAsync(targetDevice, commandMessage, operationTimeout);

配信フィードバックの受信

送信プログラムは、各 cloud-to-device メッセージに対して IoT Hub からの配信 (または有効期限) 確認を要求できます。 このオプションを使用すると、送信プログラムで通知、再試行、または補正ロジックを使用できます。 メッセージのフィードバック操作とプロパティの詳細については、「メッセージのフィードバック」を参照してください。

メッセージ配信フィードバックを受け取る方法:

• feedbackReceiver オブジェクトを作成する
• Ack パラメーターを使用してメッセージを送信する
• フィードバックの受信を待機する

feedbackReceiver オブジェクトを作成する

GetFeedbackReceiver を呼び出して、FeedbackReceiver オブジェクトを作成します。 FeedbackReceiver には、フィードバック受信操作を実行するためにサービスが使用できるメソッドが含まれています。

var feedbackReceiver = serviceClient.GetFeedbackReceiver();

Ack パラメーターを使用してメッセージを送信する

配信フィードバックを受信するには、各メッセージに配信確認の Ack プロパティの値を含める必要があります。 Ack プロパティには、次の値のいずれかを指定することができます。

• none (既定値): フィードバック メッセージは生成されません。

• Positive: メッセージが完了した場合は、フィードバック メッセージを受信します。

• Negative: デバイスが完了せずにメッセージの有効期限が切れた (または最大配信数に達した) 場合は、フィードバック メッセージを受信します。

• Full: Positive と Negative の両方の結果に関するフィードバック。

この例では、Ack プロパティが Full に設定され、1 つのメッセージに対して肯定的または否定的なメッセージ配信フィードバックの両方が要求されます。

var commandMessage = new
Message(Encoding.ASCII.GetBytes("Cloud to device message."));
commandMessage.Ack = DeliveryAcknowledgement.Full;
await serviceClient.SendAsync(targetDevice, commandMessage);

フィードバックの受信を待機する

CancellationToken を定義します。 次に、ループ内で ReceiveAsync を繰り返し呼び出し、配信フィードバック メッセージを確認します。 ReceiveAsync の各呼び出しは、ServiceClient オブジェクトに対して定義されたタイムアウト期間待機します。

• ReceiveAsync タイムアウトがメッセージを受信せず期限切れになった場合、ReceiveAsync は null を返し、ループは続行されます。
• フィードバック メッセージを受信すると、ReceiveAsync によって Task オブジェクトが返されます。これは、キャンセル トークンと共に CompleteAsync に渡す必要があります。 CompleteAsync を呼び出すと、Task パラメーターに基づいて、指定した送信済みメッセージがメッセージ キューから削除されます。
• 必要に応じて、受信コードは AbandonAsync を呼び出して送信メッセージをキューに戻すことができます。

var feedbackReceiver = serviceClient.GetFeedbackReceiver();

// Define the cancellation token.
CancellationTokenSource source = new CancellationTokenSource();
CancellationToken token = source.Token;
// Call ReceiveAsync, passing the token. Wait for the timout period.
var feedbackBatch = await feedbackReceiver.ReceiveAsync(token);
if (feedbackBatch == null) continue;

この例では、次の手順を含むメソッドを示します。

private async static void ReceiveFeedbackAsync()
{
      var feedbackReceiver = serviceClient.GetFeedbackReceiver();

      Console.WriteLine("\nReceiving c2d feedback from service");
      while (true)
      {
         // Check for messages, wait for the timeout period.
         var feedbackBatch = await feedbackReceiver.ReceiveAsync();
         // Continue the loop if null is received after a timeout.
         if (feedbackBatch == null) continue;

         Console.ForegroundColor = ConsoleColor.Yellow;
         Console.WriteLine("Received feedback: {0}",
            string.Join(", ", feedbackBatch.Records.Select(f => f.StatusCode)));
         Console.ResetColor();

         await feedbackReceiver.CompleteAsync(feedbackBatch);
      }
   }

このフィードバック受信パターンは、デバイス アプリケーションで cloud-to-device メッセージを受信するために使用されるパターンに似ています。

サービス クライアントの再接続

例外が発生すると、サービス クライアントはその情報を呼び出し元のアプリケーションに中継します。 その時点で、例外の詳細を調べて、必要なアクションを実行することをお勧めします。

次に例を示します。

• ネットワーク例外の場合は、操作を再試行できます。
• セキュリティ例外 (未承認の例外) の場合は、資格情報を調べて、最新の状態であることを確認します。
• 調整/クォータ超過の例外の場合は、要求の送信頻度を監視および変更、またはそのいずれかを実行するか、ハブ インスタンス スケール ユニットを更新します。 詳細については、「IoT Hub のクォータと調整」を参照してください。

メッセージ送信再試行ポリシー

ServiceClient メッセージ再試行ポリシーは、ServiceClient.SetRetryPolicy を使用して定義できます。

SDK 送信メッセージのサンプル

.NET/C# SDK には、このセクションで説明するメッセージ送信メソッドを含むサービス クライアント サンプルが含まれています。

cloud-to-device メッセージを受信する

このセクションでは、Azure IoT SDK for Java から DeviceClient クラスを使用して、cloud-to-device メッセージを受信する方法について説明します。

Java ベースのデバイス アプリケーションが cloud-to-device メッセージを受信するには、IoT Hub に接続してから、IoT Hub からの受信メッセージを処理するためのコールバック リスナーとメッセージ ハンドラーを設定する必要があります。 また、デバイスから IoT Hub へのメッセージ接続が切断された場合に備えて、デバイス アプリケーションで切断を検出して処理できる必要があります。

Azure IoT Java SDK ライブラリをインポートする

この記事で参照されているコードでは、次の SDK ライブラリを使用します。

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.exceptions.IotHubClientException;
import com.microsoft.azure.sdk.iot.device.transport.IotHubConnectionStatus;

DeviceClient オブジェクトを宣言する

DeviceClient オブジェクトのインスタンス化には、次のパラメーターが必要です。

• connString - IoT デバイス接続文字列。 接続文字列は、";" で区切られたキーと値のペアのセットであり、キーと値は "=" で区切られています。 次のキーの値が含まれている必要があります: HostName, DeviceId, and SharedAccessKey。
• トランスポート プロトコル - DeviceClient 接続では、次の IoTHubClientProtocol トランスポート プロトコルのいずれかを使用できます。 AMQP は最も汎用性が高く、メッセージを頻繁にチェックでき、メッセージの拒否と取り消しができます。 MQTT では、メッセージの拒否または破棄のメソッドはサポートされていません。
  • AMQPS
  • AMQPS_WS
  • HTTPS
  • MQTT
  • MQTT_WS

次に例を示します。

static string connectionString = "{a device connection string}";
static protocol = IotHubClientProtocol.AMQPS;
DeviceClient client = new DeviceClient(connectionString, protocol);

メッセージ コールバック メソッドを設定する

setMessageCallback メソッドを使用して、IoT Hub からメッセージを受信したときに通知されるメッセージ ハンドラー メソッドを定義します。

setMessageCallback には、次のパラメーターが含まれています。

• callback - コールバック メソッド名。 null の可能性があります。
• context - object 型の "省略可能な" コンテキスト。 指定されていない場合は、null を使用します。

この例では、コンテキスト パラメーターのない MessageCallback という名前の callback メソッドが setMessageCallback に渡されます。

client.setMessageCallback(new MessageCallback(), null);

メッセージ コールバック ハンドラーを作成する

コールバック メッセージ ハンドラーは、IoT Hub メッセージ キューから渡された受信メッセージを受信して処理します。

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

  protected static class MessageCallback implements com.microsoft.azure.sdk.iot.device.MessageCallback
  {
      public IotHubMessageResult onCloudToDeviceMessageReceived(Message msg, Object context)
      {
          System.out.println(
                  "Received message with content: " + new String(msg.getBytes(), Message.DEFAULT_IOTHUB_MESSAGE_CHARSET));
          // Notify IoT Hub that the message
          return IotHubMessageResult.COMPLETE;
      }
  }

メッセージの破棄と拒否のオプション

デバイスへの膨大な数の受信メッセージを正常に受信し、結果として IotHubMessageResult.COMPLETE になる必要がありますが、メッセージを破棄または拒否することが必要な場合があります。

• MQTT ではなく、AMQP と HTTPS では、アプリケーションで次のことができます。
  • メッセージの IotHubMessageResult.ABANDON。 IoT ハブは、これをキューに再登録し、後でもう一度送信します。
  • メッセージの IotHubMessageResult.REJECT。 IoT ハブはメッセージをキューに再登録せず、メッセージ キューからメッセージを完全に削除します。
• MQTT または MQTT_WS を使用しているクライアントは、メッセージを ABANDON または REJECT できません。

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

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

メッセージ状態コールバック メソッドを作成する

アプリケーションでは、registerConnectionStatusChangeCallback を使用して、デバイスの接続状態が変更されたときに実行されるコールバック メソッドを登録できます。 これにより、アプリケーションは切断されたメッセージ接続を検出し、再接続を試みることができます。

この例では、IotHubConnectionStatusChangeCallbackLogger は接続状態変更コールバック メソッドとして登録されます。

client.registerConnectionStatusChangeCallback(new IotHubConnectionStatusChangeCallbackLogger(), new Object());

コールバックが発生し、ConnectionStatusChangeContext オブジェクトが渡されます。

connectionStatusChangeContext.getNewStatus() を呼び出して、現在の接続状態を取得します。

IotHubConnectionStatus status = connectionStatusChangeContext.getNewStatus();

返される接続状態は、次のいずれかの値になる可能性があります。

• IotHubConnectionStatus.DISCONNECTED
• IotHubConnectionStatus.DISCONNECTED_RETRYING
• IotHubConnectionStatus.CONNECTED

connectionStatusChangeContext.getNewStatusReason() を呼び出して、接続状態の変更の理由を取得します。

IotHubConnectionStatusChangeReason statusChangeReason = connectionStatusChangeContext.getNewStatusReason();

connectionStatusChangeContext.getCause() を呼び出して、接続状態の変更の理由を確認します。 利用できる情報がない場合、getCause() は null を返す可能性があります。

Throwable throwable = connectionStatusChangeContext.getCause();
if (throwable != null)
    throwable.printStackTrace();

状態変更コールバック メソッドの接続状態変更の状態、デバイスの状態が変更された理由、およびコンテキストを抽出する方法を示す完全なサンプルについては、この記事の「SDK 受信メッセージのサンプル」セクションに記載されている HandleMessages サンプルを参照してください。

デバイスと IoT Hub の間の接続を開く

open を使用して、デバイスと IoT Hub の間に接続を作成します。 これで、デバイスは IoT Hub との間でメッセージを非同期的に送受信できるようになります。 クライアントが既に開いている場合、メソッドは何も行いません。

client.open(true);

SDK 受信メッセージのサンプル

HandleMessages: Microsoft Azure IoT SDK for Java に含まれているサンプル デバイス アプリ。これは、IoT ハブに接続し、cloud-to-device メッセージを受信します。

C2D メッセージの送信

このセクションでは、Azure IoT SDK for Java から ServiceClient クラスを使用して、cloud-to-device メッセージを送信する方法について説明します。 ソリューション バックエンド アプリケーションが IoT Hub に接続すると、メッセージは宛先デバイスでエンコードされて IoT Hub に送信されます。 IoT Hub は受信メッセージをメッセージ キューに格納し、メッセージは IoT Hub メッセージ キューからターゲット デバイスに配信されます。

ソリューション バックエンド アプリケーションは、メッセージ キューを介したデバイス配信を宛先とする、IoT Hub に送信されたメッセージの配信フィードバックを要求および受信することもできます。

依存関係ステートメントを追加する

依存関係を追加することにより、アプリケーションの iothub-java-service-client パッケージを使用して、IoT ハブ サービスと通信できます。

<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-service-client</artifactId>
  <version>1.7.23</version>
</dependency>

import ステートメントを追加する

次の import ステートメントを追加して、Azure IoT Java SDK と例外ハンドラーを使用します。

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

接続プロトコルを定義する

IotHubServiceClientProtocol を使用して、サービス クライアントが IoT Hub と通信するために使用するアプリケーション層プロトコルを定義します。

IotHubServiceClientProtocol は、AMQPS または AMQPS_WS 列挙型のみを受け入れます。

private static final IotHubServiceClientProtocol protocol =    
    IotHubServiceClientProtocol.AMQPS;

ServiceClient オブジェクトを作成する

IoT Hub 接続文字列とプロトコルを指定して、ServiceClient オブジェクトを作成します。

private static final String connectionString = "{yourhubconnectionstring}";
private static final ServiceClient serviceClient (connectionString, protocol);

アプリケーションと IoT Hub の間の接続を開く

AMQP 送信側接続を開きます。 このメソッドは、アプリケーションと IoT Hub の間の接続を作成します。

serviceClient.open();

メッセージ配信フィードバック用のフィードバック レシーバーを開く

FeedbackReceiver を使用して、IoT Hub フィードバックに送信されたメッセージ配信を取得できます。 FeedbackReceiver は、Receive メソッドが Message ではなく FeedbackBatch を返す特殊なレシーバーです。

この例では、FeedbackReceiver オブジェクトが作成され、フィードバックを待機するために open() ステートメントが呼び出されます。

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

メッセージのプロパティを追加する

必要に応じて、setProperties を使用してメッセージのプロパティを追加できます。 これらのプロパティは、デバイスに送信されるメッセージに含まれており、受信時にデバイス アプリケーションによって抽出できます。

Map<String, String> propertiesToSend = new HashMap<String, String>();
propertiesToSend.put(messagePropertyKey,messagePropertyKey);
messageToSend.setProperties(propertiesToSend);

非同期メッセージを作成して送信する

Message オブジェクトは、送信するメッセージを格納します。 この例では、"クラウドからデバイスへのメッセージ" が配信されます。

setDeliveryAcknowledgement を使用して、IoT Hub メッセージ キューへの配信済み/未配信の受信確認を要求します。 この例では、要求された受信確認は Full で、配信済みか未配信のいずれかになります。

SendAsync を使用して、クライアントからデバイスに非同期メッセージを送信します。 または、Send (非同期ではない) メソッドを使用することもできますが、この機能は内部的に同期されるため、一度に許可される送信操作は 1 つだけです。 メッセージは、アプリケーションから IoT Hub に配信されます。 IoT Hub によってメッセージがメッセージ キューに格納され、ターゲット デバイスに配信される準備が整います。

Message messageToSend = new Message("Cloud to device message.");
messageToSend.setDeliveryAcknowledgementFinal(DeliveryAcknowledgement.Full);
serviceClient.sendAsync(deviceId, messageToSend);

メッセージ配信フィードバックを受信する

アプリケーションからメッセージが送信された後、アプリケーションはタイムアウト値を指定して、または指定せずに、receive を呼び出すことができます。 タイムアウト値が指定されていない場合は、既定のタイムアウトが使用されます。 これにより、調べることができるメッセージ配信フィードバック プロパティを含む FeedbackBatch オブジェクトが返されます。

この例では、FeedbackBatch レシーバーを作成し、getEnqueuedTimeUtc を呼び出して、メッセージのエンキュー時間を出力します。

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

SDK 送信メッセージのサンプル

• サービス クライアントのサンプル - メッセージの送信の例、#1。

• サービス クライアントのサンプル - メッセージの送信の例、#2。

Azure IoT SDK ライブラリをインストールする

関連するコードを呼び出す前に、開発マシンに azure-iot-device SDK ライブラリをインストールします。

pip install azure-iot-device

IoT デバイスとの間でメッセージを送受信するために、2 つの Python SDK クラスを使用します。 これらのクラスのメッセージ処理メソッドについては、このページのセクションで説明します。

• IoTHubDeviceClient クラスには、デバイスから Azure IoT Hub への同期接続を作成し、IoT Hub からメッセージを受信するメソッドが含まれています。

• IoTHubRegistryManager クラスには、IoT Hub Registry Manager 操作用の API が含まれています。 この記事では、このクラスのメソッドで IoT Hub に接続し、デバイスにメッセージを送信する方法を示します。

cloud-to-device メッセージを受信する

このセクションでは、Azure IoT SDK for Python の IoTHubDeviceClient クラスを使用して、cloud-to-device メッセージを受信する方法について説明します。

Python ベースのデバイス アプリケーションが cloud-to-device メッセージを受信するには、IoT Hub に接続し、IoT Hub からの受信メッセージを処理するコールバック メッセージ ハンドラーを設定する必要があります。

IoTHubDeviceClient オブジェクトをインポートする

azure.iot.device SDK から IoTHubDeviceClient 関数をインポートするコード行を追加します。

from azure.iot.device import IoTHubDeviceClient

デバイス クライアントを接続する

IoTHubDeviceClient をインスタンス化し、IoT Hub 接続文字列を create_from_connection_string に渡します。 これにより、デバイスから IoT Hub への接続が作成されます。

または、次のいずれかの方法を使用して、IoTHubDeviceClient をデバイスに接続することもできます。

• SAS トークン文字列
• 対称キー認証
• X.509 証明書認証

deviceConnectionString = "{your IoT hub connection string}";
client = IoTHubDeviceClient.create_from_connection_string ({deviceConnectionString})

再接続を処理する

IoTHubDeviceClient は、既定で、切断された接続の再確立を試みます。 再接続の動作は、IoTHubDeviceClient connection_retry パラメーターと connection_retry_interval パラメーターによって制御されます。

メッセージ ハンドラーを作成する

デバイスへの受信メッセージを処理するメッセージ ハンドラー関数を作成します。

この例では、メッセージを受信したときに message_handler が呼び出されます。 メッセージのプロパティ (.items) は、ループを使用してコンソールに出力されます。

def message_handler(message):
    global RECEIVED_MESSAGES
    RECEIVED_MESSAGES += 1
    print("")
    print("Message received:")

    # print data from both system and application (custom) properties
    for property in vars(message).items():
        print ("    {}".format(property))

    print("Total calls received: {}".format(RECEIVED_MESSAGES))

メッセージ ハンドラーを割り当てる

on_message_received メソッドを使用して、メッセージ ハンドラー メソッドを IoTHubDeviceClient オブジェクトに割り当てます。

この例では、message_handler という名前のメッセージ ハンドラー メソッドが IoTHubDeviceClientclient オブジェクトにアタッチされています。 client オブジェクトは、IoT Hub から cloud-to-device メッセージの受信を待機します。 このコードは、メッセージを最大 300 秒 (5 分) 待機するか、キーボード キーが押されると終了します。

try:
    # Attach the handler to the client
    client.on_message_received = message_handler

    while True:
        time.sleep(300)
except KeyboardInterrupt:
    print("IoT Hub C2D Messaging device sample stopped")
finally:
    # Graceful exit
    print("Shutting down IoT Hub Client")
    client.shutdown()

SDK 受信メッセージのサンプル

メッセージの受信 - Azure IoT Hub からデバイスに送信された cloud-to-device (C2D) メッセージを受信します。

C2D メッセージの送信

このセクションでは、Azure IoT SDK for Python から IoTHubRegistryManager クラスを使用して、cloud-to-device メッセージを送信する方法について説明します。 ソリューション バックエンド アプリケーションが IoT Hub に接続すると、メッセージは宛先デバイスでエンコードされて IoT Hub に送信されます。 IoT Hub は受信メッセージをメッセージ キューに格納し、メッセージは IoT Hub メッセージ キューからターゲット デバイスに配信されます。

IoTHubRegistryManager オブジェクトをインポートする

次の import ステートメントを追加します。 IoTHubRegistryManager には、IoT Hub Registry Manager 操作用の API が含まれています。

from azure.iot.hub import IoTHubRegistryManager

IoT Hub レジストリ マネージャーを接続する

IoT ハブに接続する IoTHubRegistryManager オブジェクトをインスタンス化し、IoT Hub 接続文字列を from_connection_string に渡します。

IoTHubConnectionString = "{Primary connection string to an IoT hub}"
registry_manager = IoTHubRegistryManager.from_connection_string(IoTHubConnectionString)

メッセージをビルドして送信する

send_c2d_message を使用して、クラウド (IoT Hub) 経由でデバイスにメッセージを送信します。

send_c2d_message は次のパラメーターを使用します。

• deviceID - ターゲット デバイスの文字列識別子。
• message - cloud-to-device メッセージ。 メッセージの種類は str (string) です。
• properties - dict 型のプロパティの "省略可能な" コレクション。 プロパティには、アプリケーション プロパティとシステム プロパティを含めることができます。 既定値は {} です。

この例では、ターゲット デバイスにテスト メッセージを送信します。

# define the device ID
deviceID = "Device-1"

# define the message
message = "{\"c2d test message\"}"

# include optional properties
props={}
props.update(messageId = "message1")
props.update(prop1 = "test property-1")
props.update(prop1 = "test property-2")
prop_text = "Test message"
props.update(testProperty = prop_text)

# send the message through the cloud (IoT Hub) to the device
registry_manager.send_c2d_message(deviceID, message, properties=props)

SDK 送信メッセージのサンプル

send_message.py - cloud-to-device メッセージを送信する方法を示します。

Node.js メッセージング パッケージをインストールする

次のコマンドを実行して、開発用コンピューターに azure-iot-device パッケージと azure-iothub パッケージをインストールします。

npm install azure-iot-device --save
npm install azure-iothub --save

azure-iot-device パッケージには、IoT デバイスとやり取りするオブジェクトが含まれています。 この記事では、IoT Hub からメッセージを受信する Client クラス コードについて説明します。

azure-iothub パッケージには、IoT Hub とやり取りするオブジェクトが含まれています。 この記事では、IoT Hub 経由でアプリケーションからデバイスにメッセージを送信する Client クラス コードについて説明します。

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

このセクションでは、Azure IoT SDK for Node.js の azure-iot-device パッケージを使用して、cloud-to-device メッセージを受信する方法について説明します。

Node.js ベースのデバイス アプリケーションが cloud-to-device メッセージを受信するには、IoT Hub に接続してから、IoT Hub からの受信メッセージを処理するためのコールバック リスナーとメッセージ ハンドラーを設定する必要があります。 また、デバイスから IoT Hub へのメッセージ接続が切断された場合に備えて、デバイス アプリケーションで切断を検出して処理できる必要があります。

クライアント モジュールを作成する

azure-iot-device パッケージから、Client クラスを使用して Client を作成します。 Client クラスには、デバイスが IoT Hub との間で送受信するために使用できるメソッドが含まれています。

const Client = require('azure-iot-device').Client;

トランスポート プロトコルを選択する

Client オブジェクトでは、次のプロトコルがサポートされます。

• Amqp
• Http - Http を使用する場合、Client インスタンスは IoT Hub からのメッセージを頻繁にはチェックしません (少なくとも 25 分ごと)。
• Mqtt
• MqttWs
• AmqpWs

MQTT、AMQP、および HTTPS のサポートの相違点の詳細については、「cloud-to-device 通信に関するガイダンス」と「通信プロトコルの選択」を参照してください。

この例では、AMQP プロトコルを Protocol 変数に割り当てます。 このプロトコル変数は、この記事の接続文字列の追加に関するセクションの Client.fromConnectionString メソッドに渡されます。

const Protocol = require('azure-iot-device-mqtt').Amqp;

メッセージの完了、拒否、破棄の機能

選択したプロトコルに応じて、メッセージの完了、拒否、破棄の方法を使用できます。

AMQP および HTTP

AMQP および HTTP トランスポートは、メッセージを完了、拒否、または破棄できます。

• 完了 - メッセージを完了するために、cloud-to-device メッセージを送信したサービスに、メッセージが受信されたことを通知します。 IoT Hub は、メッセージ キューからメッセージを削除します。 この方法は、client.complete(message, callback function) の形式をとります。
• 拒否 - メッセージを拒否するために、cloud-to-device メッセージを送信したサービスに、メッセージがデバイスによって処理されないことが通知されます。 IoT Hub は、デバイス キューからメッセージを完全に削除します。 この方法は、client.reject(message, callback function) の形式をとります。
• 破棄 - メッセージを破棄するために、IoT Hub はすぐに再送信を試みます。 IoT Hub は、今後使用するためにデバイス キューにメッセージを保持します。 この方法は、client.abandon(message, callback function) の形式をとります。

MQTT

MQTT では、メッセージの完了、拒否、または破棄の機能はサポートされていません。 代わりに、MQTT は既定でメッセージを受け入れ、メッセージは IoT Hub メッセージ キューから削除されます。

再配信の試行

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

IoT Hub の文字列とトランスポート プロトコルを追加する

fromConnectionString を呼び出して、次のパラメーターを使用してデバイスから IoT ハブへの接続を確立します。

• connStr - IoT ハブの "デバイス接続" アクセス許可をカプセル化する接続文字列。 接続文字列には、ホスト名、デバイス ID、共有アクセス キーが次の形式で含まれます: "HostName=<iothub_host_name>;DeviceId=<device_id>;SharedAccessKey=<device_key>"
• transportCtor - トランスポート プロトコル。

const Protocol = require('azure-iot-device-mqtt').Amqp;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);

受信メッセージ ハンドラーを作成する

メッセージ ハンドラーは、受信メッセージごとに呼び出されます。

メッセージが正常に受信された後、AMQP または HTTP トランスポートを使用している場合は、client.complete メソッドを呼び出して、メッセージ キューからメッセージを削除できることを IoT Hub に通知します。

たとえば、このメッセージ ハンドラーは、メッセージ ID とメッセージ本文をコンソールに出力し、client.complete を呼び出して、メッセージを処理し、デバイス キューから安全に削除できることを IoT Hub に通知します。 MQTT トランスポートを使用している場合は、complete の呼び出しは必要なく、省略できます。 AMQP または HTTPS トランスポートには complete の呼び出しが必要です。

function messageHandler(msg) {
  console.log('Id: ' + msg.messageId + ' Body: ' + msg.data);
  client.complete(msg, printResultFor('completed'));
}

接続切断ハンドラーを作成する

接続が切断されると、切断ハンドラーが呼び出されます。 切断ハンドラーは、再接続コードを実装するのに役立ちます。

次の使用例は、切断エラー メッセージをキャッチしてコンソールに表示します。

function disconnectHandler() {
  clearInterval(sendInterval);
  sendInterval = null;
  client.open().catch((err) => {
    console.error(err.message);
  });
}

イベント リスナーを追加する

次のイベント リスナーを .on メソッドを使用して指定できます。

• 接続ハンドラー
• エラー ハンドラー
• 切断ハンドラー
• メッセージ ハンドラー

この例には、前に定義したメッセージ ハンドラーと切断ハンドラーが含まれています。

client.on('connect', connectHandler);
client.on('error', errorHandler);
client.on('disconnect', disconnectHandler);
client.on('message', messageHandler);

IoT Hub への接続を開く

open メソッドを使用して、IoT デバイスと IoT Hub の間の接続を開きます。 .catch(err) を使用してエラーをキャッチし、ハンドラー コードを呼び出します。

次に例を示します。

client.open()
.catch((err) => {
  console.error('Could not connect: ' + err.message);
});

SDK 受信メッセージのサンプル

simple_sample_device - IoT ハブに接続し、cloud-to-device メッセージを受信するデバイス アプリ。

C2D メッセージの送信

このセクションでは、Azure IoT SDK for Node.js から azure-iothub パッケージを使用して、cloud-to-device メッセージを送信する方法について説明します。 前に説明したように、ソリューション バックエンド アプリケーションは IoT Hub に接続し、メッセージは宛先デバイスでエンコードされて IoT Hub に送信されます。 IoT Hub は受信メッセージをメッセージ キューに格納し、メッセージは IoT Hub メッセージ キューからターゲット デバイスに配信されます。

ソリューション バックエンド アプリケーションは、メッセージ キューを介したデバイス配信を宛先とする、IoT Hub に送信されたメッセージの配信フィードバックを要求および受信することもできます。

クライアント モジュールとメッセージ モジュールを読み込む

azure-iothub パッケージの Client クラスを使用して、Client オブジェクトを宣言します。

azure-iot-common パッケージの Message クラスを使用して、Message オブジェクトを宣言します。

'use strict';
var Client = require('azure-iothub').Client;
var Message = require('azure-iot-common').Message;

クライアント オブジェクトを作成する

次のパラメーターを使用して、fromConnectionString で Client を作成します。

• IoT Hub 接続文字列
• トランスポートの種類

この例では、serviceClient オブジェクトは、Amqp トランスポートの種類で作成されます。

var connectionString = '{IoT Hub connection string}';
var serviceClient = Client.fromConnectionString(connectionString,`Amqp`);

クライアント接続を開く

Client open メソッドを呼び出して、アプリケーションと IoT Hub の間の接続を開きます。

open は、open 操作の完了時に呼び出されるコールバック関数を指定してもしなくても呼び出すことができます。

この例では、open メソッドには、オプションの err オープン接続コールバック関数が含まれています。 開く際にエラーが発生した場合は、エラー オブジェクトが返されます。 接続を正常に開くと、null コールバック値が返されます。

serviceClient.open(function (err)
if (err)
  console.error('Could not connect: ' + err.message);

メッセージを作成する

message オブジェクトには、cloud-to-device 非同期メッセージが含まれます。 メッセージ機能は、AMQP、MQTT、HTTP を介して同じように機能します。

メッセージ オブジェクトは、次のプロパティを含む複数のプロパティをサポートしています。 完全な一覧については、message プロパティを参照してください。

• ack - 配信フィードバック。 次のセクションで説明します。
• properties - カスタム メッセージ プロパティを格納するための文字列キーと値を含むマップ。
• messageId - 双方向通信の関連付けに使用します。

メッセージ オブジェクトがインスタンス化されるときに、メッセージ本文を追加します。 この例では、'Cloud to device message.' メッセージが追加されます。

var message = new Message('Cloud to device message.');
message.ack = 'full';
message.messageId = "My Message ID";

配信確認

送信プログラムは、各 cloud-to-device メッセージに対して IoT Hub からの配信 (または有効期限) 確認を要求できます。 このオプションを使用すると、送信プログラムで通知、再試行、または補正ロジックを使用できます。 メッセージのフィードバック操作とプロパティの詳細については、「メッセージのフィードバック」を参照してください。

メッセージ フィードバックを受信する各メッセージには、配信確認の ack プロパティの値を含める必要があります。 ack プロパティには、次の値のいずれかを指定することができます。

• none (既定値): フィードバック メッセージは生成されません。

• sent: メッセージが完了した場合は、フィードバック メッセージを受信します。

• : デバイスが完了せずにメッセージの有効期限が切れた (または最大配信数に達した) 場合は、フィードバック メッセージを受信します。

• full: 送信された結果と送信されていない結果の両方に対するフィードバック。

この例では、ack プロパティは full に設定され、1 つのメッセージに対する送信済みメッセージ配信フィードバックと送信されていないメッセージ配信フィードバックの両方が要求されます。

message.ack = 'full';

メッセージ フィードバック レシーバーをリンクする

メッセージ フィードバック レシーバー コールバック関数は、getFeedbackReceiver を使用して Client にリンクされます。

メッセージ フィードバック レシーバーは、次の 2 つの引数を受け取ります。

• エラー オブジェクト (null を指定できます)
• AmqpReceiver オブジェクト - クライアントが新しいフィードバック メッセージを受信したときにイベントを生成します。

この例の関数は、配信フィードバック メッセージを受け取ってコンソールに出力します。

function receiveFeedback(err, receiver){
  receiver.on('message', function (msg) {
    console.log('Feedback message:')
    console.log(msg.getData().toString('utf-8'));
  });
}

このコードは、getFeedbackReceiver を使用して、receiveFeedback フィードバック コールバック関数をサービスの Client オブジェクトにリンクします。

serviceClient.getFeedbackReceiver(receiveFeedback);

メッセージ完了結果ハンドラーを定義する

メッセージ送信完了コールバック関数は、各メッセージが送信された後に呼び出されます。

この関数の例では、メッセージ send 操作の結果をコンソールに出力します。 この例では、printResultFor 関数は、次のセクションで説明する send 関数のパラメーターとして指定されます。

function printResultFor(op) {
  return function printResult(err, res) {
    if (err) console.log(op + ' error: ' + err.toString());
    if (res) console.log(op + ' status: ' + res.constructor.name);
  };
}

メッセージの送信

end 関数を使用して、IoT Hub 経由で非同期の cloud-to-device メッセージをデバイス アプリに送信します。

send では、次のパラメーターがサポートされています。

• deviceID - ターゲット デバイスのデバイス ID。
• message - デバイスに送信するメッセージの本文。
• done - 操作が完了したときに呼び出す省略可能な関数。 done は 2 つの引数を指定して呼び出されます。
  • エラー オブジェクト (null を指定できます)。
  • トランスポート固有の応答オブジェクト。ログ記録またはデバッグに役立ちます。

次のコードは、send を呼び出して、IoT Hub 経由で cloud-to-device メッセージをデバイス アプリに送信します。 前のセクションで定義したコールバック関数 printResultFor は、配信確認情報を受け取ります。

var targetDevice = '{device ID}';
serviceClient.send(targetDevice, message, printResultFor('send'));

この例では、デバイスにメッセージを送信し、cloud-to-device メッセージが配信されたことの確認応答がデバイスからあったときにフィードバック メッセージを処理する方法を示します。

serviceClient.open(function (err) {
  if (err) {
    console.error('Could not connect: ' + err.message);
  } else {
    console.log('Service client connected');
    serviceClient.getFeedbackReceiver(receiveFeedback);
    var message = new Message('Cloud to device message.');
    message.ack = 'full';
    message.messageId = "My Message ID";
    console.log('Sending message: ' + message.getData());
    serviceClient.send(targetDevice, message, printResultFor('send'));
  }
});

SDK 送信メッセージのサンプル

send_c2d_message.js - IoT Hub 経由で C2D メッセージをデバイスに送信します。