IoT ハブから cloud-to-device メッセージを送信するSend cloud-to-device messages from an IoT hub

ソリューション バックエンドから、デバイス アプリに一方向の通知を送信するには、IoT ハブからデバイスに cloud-to-device メッセージを送信します。To send one-way notifications to a device app from your solution back end, send cloud-to-device messages from your IoT hub to your device. Azure IoT Hub でサポートされるその他の cloud-to-device オプションの詳細については、「cloud-to-device 通信に関するガイダンス」を参照してください。For a discussion of other cloud-to-device options supported by Azure IoT Hub, see Cloud-to-device communications guidance.

注意

この記事で説明されている機能は、Standard レベルの IoT Hub でのみ使用できます。The features described in this article are available only in the standard tier of IoT Hub. Basic および Standard または Free レベルの IoT Hub の詳細については、適切な IoT Hub レベルの選択に関するページを参照してください。For more information about the basic and standard/free IoT Hub tiers, see Choose the right IoT Hub tier.

cloud-to-device メッセージはサービス向けエンドポイントの /messages/devicebound を介して送信します。You send cloud-to-device messages through a service-facing endpoint, /messages/devicebound. その後、デバイスではそのメッセージを、デバイス固有のエンドポイントの /devices/{deviceId}/messages/devicebound を介して受信します。A device then receives the messages through a device-specific endpoint, /devices/{deviceId}/messages/devicebound.

各 cloud-to-device メッセージのターゲットを単一のデバイスにするために、IoT ハブでは、to プロパティが /devices/{deviceId}/messages/devicebound に設定されます。To target each cloud-to-device message at a single device, your IoT hub sets the to property to /devices/{deviceId}/messages/devicebound.

各デバイスのキューでは、最大 50 個の cloud-to-device メッセージが保持されます。Each device queue holds, at most, 50 cloud-to-device messages. 同じデバイスにそれ以上のメッセージを送信しようとすると、エラーが発生します。To try to send more messages to the same device results in an error.

cloud-to-device メッセージのライフ サイクルThe cloud-to-device message life cycle

少なくとも 1 回のメッセージ配信を保証するために、IoT ハブでは cloud-to-device メッセージがデバイスごとのキューに保持されます。To guarantee at-least-once message delivery, your IoT hub persists cloud-to-device messages in per-device queues. IoT ハブでキューからメッセージを削除するためには、デバイスで明示的に完了 を確認する必要があります。For the IoT hub to remove the messages from the queue, the devices must explicitly acknowledge completion. このような方法で、接続とデバイスの障害に対する復元性が保証されます。This approach guarantees resiliency against connectivity and device failures.

次の図には、ライフ サイクルの状態グラフが示されています。The life-cycle state graph is displayed in the following diagram:

cloud-to-device メッセージのライフ サイクル

IoT ハブ サービスでは、デバイスにメッセージを送信するときに、メッセージの状態がエンキュー に設定されます。When the IoT hub service sends a message to a device, the service sets the message state to Enqueued. デバイスでメッセージを受信する 必要がある場合、IoT ハブで、状態が非表示 に設定されると、メッセージがロック されます。When a device wants to receive a message, the IoT hub locks the message by setting the state to Invisible. この状態では、デバイス上の他のスレッドで他のメッセージの受信を開始することが許可されます。This state allows other threads on the device to start receiving other messages. デバイスのスレッドでは、メッセージの処理を完了するときに、メッセージを完了することで IoT ハブに通知します。When a device thread completes the processing of a message, it notifies the IoT hub by completing the message. その後、IoT ハブで状態が完了に設定されます。The IoT hub then sets the state to Completed.

デバイスは次の動作をすることもあります。A device can also:

  • メッセージの拒否。この場合、IoT ハブによってメッセージの状態が配信不能 に設定されます。Reject the message, which causes the IoT hub to set it to the Dead lettered state. Message Queuing Telemetry Transport (MQTT) プロトコル経由で接続するデバイスでは、cloud-to-device メッセージを拒否することはできません。Devices that connect over the Message Queuing Telemetry Transport (MQTT) Protocol can't reject cloud-to-device messages.

  • メッセージの破棄。この場合、IoT ハブによってメッセージがキューに戻され、状態がエンキュー に設定されます。Abandon the message, which causes the IoT hub to put the message back in the queue, with the state set to Enqueued. MQTT プロトコル経由で接続するデバイスでは、cloud-to-device メッセージを破棄することはできません。Devices that connect over the MQTT Protocol can't abandon cloud-to-device messages.

スレッドでは、IoT ハブに通知することなく、メッセージの処理に失敗することもあります。A thread could fail to process a message without notifying the IoT hub. この場合、表示 がタイムアウト (またはロック がタイムアウト) になった後で、メッセージの状態が自動的に非表示 からエンキュー に戻ります。In this case, messages automatically transition from the Invisible state back to the Enqueued state after a visibility time-out (or lock time-out). このタイムアウトの値は 1 分であり、変更することはできません。The value of this time-out is one minute and cannot be changed.

IoT ハブの最大配信数プロパティによって、メッセージの状態をエンキュー非表示 の間で切り替えることができる最大数が決まります。The max delivery count property on the IoT hub determines the maximum number of times a message can transition between the Enqueued and Invisible states. その切り替えの回数に達した後、IoT ハブによってメッセージの状態が配信不能 に設定されます。After that number of transitions, the IoT hub sets the state of the message to Dead lettered. 同様に、有効期限が切れた後も、IoT ハブによってメッセージの状態が配信不能 に設定されます。Similarly, the IoT hub sets the state of a message to Dead lettered after its expiration time. 詳細については、有効期限に関する記述を参照してください。For more information, see Time to live.

cloud-to-device メッセージを IoT Hub で送信する方法に関する記事では、cloud-to-device メッセージを、クラウドから送信してデバイスで受信する方法が示されています。The How to send cloud-to-device messages with IoT Hub article shows you how to send cloud-to-device messages from the cloud and receive them on a device.

メッセージの損失がアプリケーション ロジックに影響しない場合は、通常、デバイスで cloud-to-device メッセージが完了されます。A device ordinarily completes a cloud-to-device message when the loss of the message doesn't affect the application logic. たとえば、デバイスでメッセージの内容がローカルに保持された場合や、正常に操作が実行された場合などです。An example of this might be when the device has persisted the message content locally or has successfully executed an operation. また、メッセージには、メッセージの損失がアプリケーションの機能に影響しないことを示す一時的な情報が含まれている場合もあります。The message could also carry transient information, whose loss wouldn't impact the functionality of the application. タスクの実行時間が長いときに、場合によっては次の操作を実行できます。Sometimes, for long-running tasks, you can:

  • デバイスでタスクの説明がローカル ストレージに保持された後で、cloud-to-device メッセージを完了する。Complete the cloud-to-device message after the device has persisted the task description in local storage.

  • タスクの進行状況のさまざまな段階で、1 つ以上の D2C メッセージによりソリューション バックエンドに通知するNotify the solution back end with one or more device-to-cloud messages at various stages of progress of the task.

メッセージの有効期限Message expiration (time to live)

すべての C2D メッセージに有効期限があります。Every cloud-to-device message has an expiration time. この期限は、次のいずれかで設定されます。This time is set by either of the following:

  • サービスの ExpiryTimeUtc プロパティThe ExpiryTimeUtc property in the service
  • IoT ハブ。IoT ハブ プロパティとして指定された既定の有効期限 を使用しますThe IoT hub, by using the default time to live that's specified as an IoT hub property

C2D の構成オプション」を参照してください。See Cloud-to-device configuration options.

メッセージの有効期限を利用し、接続されていないデバイスにメッセージが送信されないようにする一般的な方法は、短い有効期限 の値を設定することです。A common way to take advantage of a message expiration and to avoid sending messages to disconnected devices is to set short time to live values. この方法を使用すると、デバイスの接続状態を維持するのと同じ結果が得られますが、より効率的です。This approach achieves the same result as maintaining the device connection state, but it is more efficient. メッセージの受信確認を要求すると、IoT ハブによって、どのデバイスが次の状態であるかが通知されます。When you request message acknowledgments, the IoT hub notifies you which devices are:

  • メッセージを受信できるAble to receive messages.
  • オンラインでないか、失敗したAre not online or have failed.

メッセージのフィードバックMessage feedback

cloud-to-device メッセージを送信するときに、サービスでは、そのメッセージの最終状態についてのメッセージごとのフィードバックの配信を要求できます。When you send a cloud-to-device message, the service can request the delivery of per-message feedback about the final state of that message. これを行うには、以下の 4 つの値のいずれかに、送信される cloud-to-device メッセージの iothub-ack アプリケーション プロパティを設定します。You do this by setting the iothub-ack application property in the cloud-to-device message that's being sent to one of the following four values:

Ack プロパティ値Ack property value 動作Behavior
なしnone IoT ハブでは、フィードバック メッセージは生成されません (既定の動作)。The IoT hub doesn't generate a feedback message (default behavior).
ポジティブpositive cloud-to-device メッセージの状態が完了 に達した場合に、IoT ハブによってフィードバック メッセージが生成されます。If the cloud-to-device message reaches the Completed state, the IoT hub generates a feedback message.
ネガティブnegative cloud-to-device メッセージの状態が配信不能 に達した場合に、IoT ハブによってフィードバック メッセージが生成されます。If the cloud-to-device message reaches the Dead lettered state, the IoT hub generates a feedback message.
フルfull IoT ハブでは、いずれの場合もフィードバック メッセージが生成されます。The IoT hub generates a feedback message in either case.

Ack 値がフル のときに、フィードバック メッセージを受信しなかった場合、フィードバック メッセージの有効期限が切れていることを意味します。If the Ack value is full, and you don't receive a feedback message, it means that the feedback message has expired. このとき、元のメッセージがどうなったかをサービスが認識することはできません。The service can't know what happened to the original message. 実際には、有効期限切れになる前にフィードバックをサービスが確実に処理できることが必要です。In practice, a service should ensure that it can process the feedback before it expires. 有効期限は最長 2 日間であるため、障害が発生した場合も、サービスを再び稼働させる時間はあります。The maximum expiration time is two days, which leaves time to get the service running again if a failure occurs.

エンドポイントに関するページで説明されているように、IoT ハブではサービス向けエンドポイントの /messages/servicebound/feedback 経由でメッセージとしてフィードバックを配信します。As explained in Endpoints, the IoT hub delivers feedback through a service-facing endpoint, /messages/servicebound/feedback, as messages. フィードバックを受信するためのセマンティクスは C2D メッセージの場合と同様です。The semantics for receiving feedback are the same as for cloud-to-device messages. 可能な限り、メッセージのフィードバックは、次の形式で 1 つのメッセージのバッチとして処理します。Whenever possible, message feedback is batched in a single message, with the following format:

プロパティProperty 説明Description
EnqueuedTimeEnqueuedTime フィードバック メッセージがハブで受信された日時を示すタイムスタンプA timestamp that indicates when the feedback message was received by the hub
UserIdUserId {iot hub name}
ContentTypeContentType application/vnd.microsoft.iothub.feedback.json

本文はシリアル化された JSON レコードの配列で、それぞれ次のプロパティを持っています。The body is a JSON-serialized array of records, each with the following properties:

プロパティProperty 説明Description
EnqueuedTimeUtcEnqueuedTimeUtc メッセージの結果が発生した日時を示すタイムスタンプ (たとえば、ハブでフィードバック メッセージが受信されたときや、元のメッセージの期限が切れたとき)A timestamp that indicates when the outcome of the message happened (for example, the hub received the feedback message or the original message expired)
OriginalMessageIdOriginalMessageId このフィードバック情報が関連する cloud-to-device メッセージの MessageIdThe MessageId of the cloud-to-device message to which this feedback information relates
StatusCodeStatusCode IoT ハブによって生成されるフィードバック メッセージで使用される、必須の文字列。A required string, used in feedback messages that are generated by the IoT hub:
SuccessSuccess
ExpiredExpired
DeliveryCountExceededDeliveryCountExceeded
RejectedRejected
PurgedPurged
説明Description StatusCode の文字列値String values for StatusCode
deviceIdDeviceId フィードバックのこの要素が関連する cloud-to-device メッセージのターゲット デバイスの DeviceIdThe DeviceId of the target device of the cloud-to-device message to which this piece of feedback relates
DeviceGenerationIdDeviceGenerationId フィードバックのこの要素が関連する cloud-to-device メッセージのターゲット デバイスの DeviceGenerationIdThe DeviceGenerationId of the target device of the cloud-to-device message to which this piece of feedback relates

cloud-to-device メッセージのフィードバックを元のメッセージと関連付けるには、サービスで MessageId を指定する必要があります。For the cloud-to-device message to correlate its feedback with the original message, the service must specify a MessageId.

次のコードには、フィードバック メッセージの本文が示されています。The body of a feedback message is shown in the following code:

[
  {
    "OriginalMessageId": "0987654321",
    "EnqueuedTimeUtc": "2015-07-28T16:24:48.789Z",
    "StatusCode": 0,
    "Description": "Success",
    "DeviceId": "123",
    "DeviceGenerationId": "abcdefghijklmnopqrstuvwxyz"
  },
  {
    ...
  },
  ...
]

削除されたデバイスに対する保留中のフィードバックPending feedback for deleted devices

デバイスが削除されると、保留中のフィードバックも削除されます。When a device is deleted, any pending feedback is deleted as well. デバイスのフィードバックはバッチで送信されます。Device feedback is sent in batches. デバイスがメッセージの受信を確認してから次のフィードバック バッチが準備されるまでの短い期間 (多くの場合、1 秒未満) の間にデバイスが削除された場合、フィードバックは発生しません。If a device is deleted in the narrow window (often less than 1 second) between when the device confirms receipt of the message and when the next feedback batch is prepared, the feedback will not occur.

デバイスを削除する前に、保留中のフィードバックが到着するまでしばらく待つことによって、この動作に対処できます。You can address this behavior by waiting a period of time for pending feedback to arrive before deleting your device. デバイスが削除されると、関連するメッセージ フィードバックは失われたと見なされます。Related message feedback should be assumed lost once a device is deleted.

C2D の構成オプションCloud-to-device configuration options

各 IoT hub では、cloud-to-device メッセージング用に次の構成オプションを公開しています。Each IoT hub exposes the following configuration options for cloud-to-device messaging:

プロパティProperty 説明Description 範囲と既定値Range and default
defaultTtlAsIso8601defaultTtlAsIso8601 cloud-to-device メッセージの既定の TTLDefault TTL for cloud-to-device messages 最大 2 日の ISO_8601 書式による間隔 (最小 1 分); 既定値:1 時間ISO_8601 interval up to 2 days (minimum 1 minute); default: 1 hour
maxDeliveryCountmaxDeliveryCount デバイスごとの cloud-to-device キューの最大配信数Maximum delivery count for cloud-to-device per-device queues 1 から 100; 既定値:101 to 100; default: 10
feedback.ttlAsIso8601feedback.ttlAsIso8601 サービス宛てのフィードバック メッセージの保有期間Retention for service-bound feedback messages 最大 2 日の ISO_8601 書式による間隔 (最小 1 分); 既定値:1 時間ISO_8601 interval up to 2 days (minimum 1 minute); default: 1 hour
feedback.maxDeliveryCountfeedback.maxDeliveryCount フィードバック キューの最大配信数Maximum delivery count for the feedback queue 1 から 100; 既定値:101 to 100; default: 10
feedback.lockDurationAsIso8601feedback.lockDurationAsIso8601 フィードバック キューの最大配信数Maximum delivery count for the feedback queue 5 から 300 秒の ISO_8601 書式による間隔 (最短 5 秒)。既定値:60 秒。ISO_8601 interval from 5 to 300 seconds (minimum 5 seconds); default: 60 seconds.

構成オプションは、次のいずれかの方法で設定できます。You can set the configuration options in one of the following ways:

  • Azure ポータル:IoT ハブの [設定] で、 [組み込みのエンドポイント] を選択し、 [cloud-to-device メッセージング] を展開します。Azure portal: Under Settings on your IoT hub, select Built-in endpoints and expand Cloud to device messaging. (feedback.maxDeliveryCount および feedback.lockDurationAsIso8601 プロパティの設定は、Azure portal では現在サポートされていません。)(Setting the feedback.maxDeliveryCount and feedback.lockDurationAsIso8601 properties is not currently supported in Azure portal.)

    ポータルでの cloud-to-device メッセージングの構成オプションの設定

  • Azure CLI:az iot hub update コマンドを使用します。Azure CLI: Use the az iot hub update command:

    az iot hub update --name {your IoT hub name} \
        --set properties.cloudToDevice.defaultTtlAsIso8601=PT1H0M0S
    
    az iot hub update --name {your IoT hub name} \
        --set properties.cloudToDevice.maxDeliveryCount=10
    
    az iot hub update --name {your IoT hub name} \
        --set properties.cloudToDevice.feedback.ttlAsIso8601=PT1H0M0S
    
    az iot hub update --name {your IoT hub name} \
        --set properties.cloudToDevice.feedback.maxDeliveryCount=10
    
    az iot hub update --name {your IoT hub name} \
        --set properties.cloudToDevice.feedback.lockDurationAsIso8601=PT0H1M0S
    

次のステップNext steps

cloud-to-device メッセージの受信に使用できる SDK については、Azure IoT SDK に関する記事をご覧ください。For information about the SDKs that you can use to receive cloud-to-device messages, see Azure IoT SDKs.

cloud-to-device メッセージへの受信を試すには、クラウドからデバイスへの送信 に関するチュートリアルをご覧ください。To try out receiving cloud-to-device messages, see the Send cloud-to-device tutorial.