Inviare messaggi da cloud a dispositivo dall'hub IoTSend cloud-to-device messages from IoT Hub

Per inviare notifiche unidirezionali all'app del dispositivo dal back-end della soluzione, inviare messaggi da cloud a dispositivo dall'hub IoT al dispositivo.To send one-way notifications to the device app from your solution back end, send cloud-to-devices messages from your IoT hub to your device. Per una descrizione delle altre opzioni da cloud a dispositivo supportate dall'hub IoT, vedere Indicazioni sulle comunicazioni da cloud a dispositivo.For a discussion of other cloud-to-devices options supported by IoT Hub, see Cloud-to-device communications guidance.

È possibile inviare messaggi da cloud a dispositivo tramite un endpoint per il servizio (/messages/servicebound).You send cloud-to-device messages through a service-facing endpoint (/messages/devicebound). Il dispositivo li riceve tramite un endpoint specifico per il dispositivo (/devices/{deviceId}/messages/devicebound).A device then receives the messages through a device-specific endpoint (/devices/{deviceId}/messages/devicebound).

Ogni messaggio da cloud a dispositivo è destinato a un singolo dispositivo, tramite la proprietà to impostata su /devices/{deviceId}/messages/devicebound.To target each cloud-to-device message at a single device, IoT Hub sets the to property to /devices/{deviceId}/messages/devicebound.

Ogni coda di dispositivo può contenere un massimo di 50 messaggi da cloud a dispositivo.Each device queue holds at most 50 cloud-to-device messages. Se si prova a inviare più messaggi allo stesso dispositivo, si verificherà un errore.Trying to send more messages to the same device results in an error.

Ciclo di vita dei messaggi da cloud a dispositivoThe cloud-to-device message lifecycle

Per garantire il recapito di almeno un messaggio, l'hub IoT salva in modo permanente i messaggi da cloud a dispositivo nelle code dei singoli dispositivi.To guarantee at-least-once message delivery, IoT Hub persists cloud-to-device messages in per-device queues. I dispositivi devono confermare esplicitamente il completamento per consentire all'hub IoT di rimuoverli dalla coda.Devices must explicitly acknowledge completion for IoT Hub to remove them from the queue. Questo approccio garantisce la resilienza rispetto a errori di connettività e del dispositivo.This approach guarantees resiliency against connectivity and device failures.

Il diagramma seguente illustra il grafico sullo stato del ciclo di vita per un messaggio da cloud a dispositivo nell'hub IoT.The following diagram shows the lifecycle state graph for a cloud-to-device message in IoT Hub.

Ciclo di vita dei messaggi da cloud a dispositivo

Quando il servizio hub IoT invia un messaggio a un dispositivo, lo stato del messaggio viene impostato su Enqueued (Accodato).When the IoT Hub service sends a message to a device, the service sets the message state to Enqueued. Quando un dispositivo accetta di ricevere un messaggio, l'hub IoT blocca il messaggio, impostandone lo stato su Invisibile, per consentire ad altri thread nel dispositivo di iniziare a ricevere altri messaggi.When a device wants to receive a message, IoT Hub locks the message (by setting the state to Invisible), which allows other threads on the device to start receiving other messages. Quando un thread del dispositivo termina l'elaborazione di un messaggio, invia una notifica all'hub IoT completando il messaggio.When a device thread completes the processing of a message, it notifies IoT Hub by completing the message. L'hub IoT quindi imposta lo stato Completato.IoT Hub then sets the state to Completed.

Un dispositivo può anche scegliere di:A device can also choose to:

  • Rifiutare il messaggio. In questo caso, l'hub IoT ne imposta lo stato su Non recapitabile.Reject the message, which causes IoT Hub to set it to the Deadlettered state. I dispositivi che si connettono tramite il protocollo MQTT non possono rifiutare i messaggi da cloud a dispositivo.Devices that connect over the MQTT protocol cannot reject cloud-to-device messages.
  • Abbandonare il messaggio. In questo caso, l'hub IoT inserisce di nuovo il messaggio nella coda con lo stato impostato su Accodato.Abandon the message, which causes IoT Hub to put the message back in the queue, with the state set to Enqueued. I dispositivi che si connettono tramite il protocollo MQTT non possono rifiutare i messaggi da cloud a dispositivo.Devices that connect over the MQTT protocol cannot abandon cloud-to-device messages.

Un thread potrebbe non riuscire a elaborare un messaggio senza inviare una notifica all'hub IoT.A thread could fail to process a message without notifying IoT Hub. In questo caso i messaggi passano automaticamente dallo stato Invisibile allo stato Accodato dopo un timeout di visibilità o di blocco.In this case, messages automatically transition from the Invisible state back to the Enqueued state after a visibility (or lock) timeout. Il valore predefinito di questo timeout è un minuto.The default value of this timeout is one minute.

Un messaggio può passare dallo stato Accodato allo stato Invisibile e viceversa per il numero massimo di volte specificato nella proprietà maxdeliverycount dell'hub IoT.The max delivery count property on IoT Hub determines the maximum number of times a message can transition between the Enqueued and Invisible states. Dopo il numero di transizioni specificato, l'hub IoT imposta lo stato del messaggio su Non recapitabile.After that number of transitions, IoT Hub sets the state of the message to Deadlettered. Analogamente, l'hub IoT imposta lo stato di un messaggio su Non recapitabile dopo la relativa scadenza. Vedere la sezione Scadenza del messaggio (durata).Similarly, IoT Hub sets the state of a message to Deadlettered after its expiration time (see Time to live).

L'esercitazione Come inviare i messaggi da cloud a dispositivo con l'hub IoT illustra come inviare messaggi da cloud a dispositivo dal cloud e riceverli su un dispositivo.The How to send cloud-to-device messages with IoT Hub shows you how to send cloud-to-device messages from the cloud and receive them on a device.

Generalmente, un dispositivo completa i messaggi da cloud a dispositivo quando la perdita del messaggio non influisce sulla logica dell'applicazione.Typically, a device completes a cloud-to-device message when the loss of the message does not affect the application logic. Ad esempio, quando il dispositivo ha salvato in modo permanente il contenuto del messaggio in locale o ha eseguito correttamente un'operazione.For example, when the device has persisted the message content locally or has successfully executed an operation. Il messaggio potrebbe anche includere informazioni temporanee la cui perdita non influirebbe sulla funzionalità dell'applicazione.The message could also carry transient information, whose loss would not impact the functionality of the application. In alcuni casi, per le attività con esecuzione prolungata è possibile:Sometimes, for long-running tasks, you can:

  • Completare il messaggio da cloud a dispositivo dopo aver salvato in modo permanente la descrizione dell'attività nell'archivio locale.Complete the cloud-to-device message after persisting the task description in local storage.
  • Inviare al back-end della soluzione una notifica con uno o più messaggi da dispositivo a cloud in diverse fasi di avanzamento dell'attività.Notify the solution back end with one or more device-to-cloud messages at various stages of progress of the task.

Scadenza del messaggio (durata)Message expiration (time to live)

Ogni messaggio da cloud a dispositivo ha una scadenza.Every cloud-to-device message has an expiration time. Tale scadenza viene impostata da uno degli elementi seguenti:This time is set by one of:

  • La proprietà ExpiryTimeUtc nel servizio.The ExpiryTimeUtc property in the service.
  • Lo hub IoT che usa il valore TTL predefinito specificato come proprietà dello hub IoT.IoT Hub using the default time to live specified as an IoT Hub property.

Vedere Opzioni di configurazione da cloud a dispositivo.See Cloud-to-device configuration options.

Un modo comune per usare la scadenza del messaggio a proprio vantaggio ed evitare l'invio di messaggi a dispositivi disconnessi consiste nell'impostare valori di durata brevi.A common way to take advantage of message expiration and avoid sending messages to disconnected devices, is to set short time to live values. Questo approccio permette di ottenere lo stesso risultato che si ottiene mantenendo connesso il dispositivo, ma è più efficiente.This approach achieves the same result as maintaining the device connection state, while being more efficient. Quando si richiede l'acknowledgement dei messaggi, lo hub IoT informa che i dispositivi:When you request message acknowledgements, IoT Hub notifies you which devices are:

  • sono abilitati a ricevere messaggi.Able to receive messages.
  • sono offline, oppure l'operazione non è riuscita.Are not online or have failed.

Commenti sui messaggiMessage feedback

Durante l'invio di messaggi da cloud a dispositivo, il servizio può richiedere il recapito di commenti specifici per ogni messaggio in merito allo stato finale del messaggio.When you send a cloud-to-device message, the service can request the delivery of per-message feedback regarding the final state of that message.

Proprietà AckAck property ComportamentoBehavior
positivepositive Se il messaggio da cloud a dispositivo ha raggiunto lo stato Completato, l'hub IoT genera un messaggio con commenti.If the cloud-to-device message reaches the Completed state, IoT Hub generates a feedback message.
negativenegative Se il messaggio da cloud a dispositivo ha raggiunto lo stato Deadlettered (Recapitato), l'hub IoT genera un messaggio con commenti.If the cloud-to-device message reaches the Deadlettered state, IoT Hub generates a feedback message.
fullfull L'hub IoT genera un messaggio di commenti in entrambi i casi.IoT Hub generates a feedback message in either case.

Se la proprietà Ack è impostata su full e non si riceve un messaggio con commenti, significa che il messaggio è scaduto.If Ack is full, and you don't receive a feedback message, it means that the feedback message expired. Il servizio non può sapere cosa è successo al messaggio originale.The service can't know what happened to the original message. In pratica, un servizio deve garantire che sia possibile elaborare i commenti prima della scadenza.In practice, a service should ensure that it can process the feedback before it expires. Il periodo di scadenza massimo è di due giorni ed è quindi disponibile un tempo sufficiente per ripristinare il servizio in caso di errore.The maximum expiry time is two days, which leaves time to get the service running again if a failure occurs.

Come illustrato nella sezione Endpoint, l'hub IoT recapita commenti sotto forma di messaggi tramite un endpoint per servizio (/messages/servicebound/feedback).As explained in Endpoints, IoT Hub delivers feedback through a service-facing endpoint (/messages/servicebound/feedback) as messages. La semantica di ricezione per i commenti è uguale a quella dei messaggi da cloud a dispositivo e ha lo stesso ciclo di vita dei messaggi.The semantics for receiving feedback are the same as for cloud-to-device messages, and have the same Message lifecycle. Quando è possibile, i commenti sui messaggio vengono riuniti in batch in un unico messaggio con il formato seguente:Whenever possible, message feedback is batched in a single message, with the following format:

ProprietàProperty DescrizioneDescription
EnqueuedTimeEnqueuedTime Timestamp che indica quando è stato creato il messaggio.Timestamp indicating when the message was created.
UserIdUserId {iot hub name}
ContentTypeContentType application/vnd.microsoft.iothub.feedback.json

Il corpo è una matrice serializzata con JSON dei record, ognuno con le proprietà seguenti:The body is a JSON-serialized array of records, each with the following properties:

ProprietàProperty DescrizioneDescription
EnqueuedTimeUtcEnqueuedTimeUtc Timestamp che indica quando è stato creato il risultato del messaggio.Timestamp indicating when the outcome of the message happened. Ad esempio, il dispositivo ha completato l'operazione o il messaggio è scaduto.For example, the device completed or the message expired.
OriginalMessageIdOriginalMessageId MessageId del messaggio da cloud a dispositivo correlato a queste informazioni sui commenti.MessageId of the cloud-to-device message to which this feedback information relates.
StatusCodeStatusCode Stringa obbligatoria.Required string. Usato nei messaggi con commenti generati dall'hub IoT.Used in feedback messages generated by IoT Hub.
'Operazione riuscita''Success'
'Scaduto''Expired'
'Numero di distribuzioni superato''DeliveryCountExceeded'
'Rifiutato''Rejected'
'Eliminato definitivamente''Purged'
DescrizioneDescription Valori stringa per StatusCode.String values for StatusCode.
deviceIdDeviceId DeviceId del messaggio da cloud a dispositivo correlato a questi commenti e suggerimenti.DeviceId of the target device of the cloud-to-device message to which this piece of feedback relates.
DeviceGenerationIdDeviceGenerationId DeviceGenerationId del dispositivo di destinazione del messaggio da cloud a dispositivo correlato a questi commenti e suggerimenti.DeviceGenerationId of the target device of the cloud-to-device message to which this piece of feedback relates.

Il servizio deve specificare un valore MessageId per il messaggio da cloud a dispositivo per poter correlare i commenti al messaggio originale.The service must specify a MessageId for the cloud-to-device message to be able to correlate its feedback with the original message.

L'esempio seguente illustra il corpo di un messaggio con commenti.The following example shows the body of a feedback message.

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

Opzioni di configurazione da cloud a dispositivoCloud-to-device configuration options

Ogni hub IoT espone le opzioni di configurazione seguenti per la messaggistica da cloud a dispositivo:Each IoT hub exposes the following configuration options for cloud-to-device messaging:

ProprietàProperty DescrizioneDescription Intervallo e valore predefinitoRange and default
defaultTtlAsIso8601defaultTtlAsIso8601 Durata (TTL) predefinita per messaggi da cloud a dispositivo.Default TTL for cloud-to-device messages. Intervallo ISO_8601 fino a 2D (almeno 1 minuto).ISO_8601 interval up to 2D (minimum 1 minute). Predefinito: 1 ora.Default: 1 hour.
maxDeliveryCountmaxDeliveryCount Numero massimo di recapiti per code da cloud a dispositivo per i singoli dispositivi.Maximum delivery count for cloud-to-device per-device queues. Da 1 a 100.1 to 100. Predefinito: 10.Default: 10.
feedback.ttlAsIso8601feedback.ttlAsIso8601 Conservazione per messaggi con commenti diretti al servizio.Retention for service-bound feedback messages. Intervallo ISO_8601 fino a 2D (almeno 1 minuto).ISO_8601 interval up to 2D (minimum 1 minute). Predefinito: 1 ora.Default: 1 hour.
feedback.maxDeliveryCountfeedback.maxDeliveryCount Numero massimo di recapiti per la coda di commenti.Maximum delivery count for feedback queue. Da 1 a 100.1 to 100. Predefinito: 100.Default: 100.

Per altre informazioni su come impostare queste opzioni di configurazione, vedere Creare hub IoT.For more information about how to set these configuration options, see Create IoT hubs.

Passaggi successiviNext steps

Per informazioni sugli SDK che è possibile usare per ricevere i messaggi da cloud a dispositivo, vedere Azure IoT SDK.For information about the SDKs you can use to receive cloud-to-device messages, see Azure IoT SDKs.

Per provare a ricevere i messaggi da cloud a dispositivo, vedere l'esercitazione Invio da cloud a dispositivo.To try out receiving cloud-to-device messages, see the Send cloud-to-device tutorial.