Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
I messaggi da cloud a dispositivo sono notifiche unidirezionale dal back-end della soluzione a un'applicazione del dispositivo. Per una descrizione di altre opzioni da cloud a dispositivo supportate dall'hub IoT di Azure, vedere Linee guida per le comunicazioni da cloud a dispositivo.
Note
Le funzionalità descritte in questo articolo sono disponibili solo nel livello Standard dell'hub IoT. Per altre informazioni sui livelli di hub IoT di base e standard/gratuiti, vedere Scegliere il livello e le dimensioni dell'hub IoT corretti per la soluzione.
È possibile inviare messaggi da cloud a dispositivo tramite un endpoint per il servizio /messages/devicebound. Il dispositivo li riceve tramite un endpoint specifico per il dispositivo /devices/{deviceId}/messages/devicebound.
Per impostare come destinazione ogni messaggio da cloud a dispositivo in un singolo dispositivo, l'hub IoT imposta la proprietà su su /devices/{deviceId}/messages/devicebound.
Ogni coda di dispositivo può contenere massimo di 50 messaggi da cloud a dispositivo. Si verifica un errore se si tenta di inviare altri messaggi allo stesso dispositivo.
Questo articolo illustra i concetti e i processi relativi ai messaggi da cloud a dispositivo. Per indicazioni sullo sviluppo di applicazioni che gestiscono messaggi da cloud a dispositivo, vedere Inviare e ricevere messaggi da cloud a dispositivo.
Ciclo di vita dei messaggi da cloud a dispositivo
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. I dispositivi devono confermare in modo esplicito il completamento di un messaggio prima che l'hub IoT rimuova il messaggio dalla coda. Questo approccio garantisce la resilienza rispetto a errori di connettività e del dispositivo.
Il grafico dello stato del ciclo di vita viene visualizzato nel diagramma seguente:
Quando il servizio hub IoT invia un messaggio a un dispositivo, lo stato del messaggio viene impostato su Accodato. Quando un thread del dispositivo è pronto per ricevere un messaggio, l'hub IoT blocca il messaggio impostando lo stato su Invisibile. Questo stato consente ad altri thread nel dispositivo di iniziare a ricevere altri messaggi. Quando un thread del dispositivo completa l'elaborazione di un messaggio, notifica all'hub IoT completando il messaggio. L'hub IoT imposta quindi lo stato su Completato.
Un dispositivo può anche:
Rifiutare il messaggio. In questo caso, l'hub IoT ne imposta lo stato su Non recapitabile. Non esiste una coda di messaggi non recapitabili per il recupero di questi messaggi. I dispositivi che si connettono tramite il protocollo MQTT (Message Queue Telemetry Transport) non possono rifiutare i messaggi da cloud a dispositivo.
Abbandonare il messaggio, per far sì che l'hub IoT inserisca di nuovo il messaggio nella coda con lo stato impostato su Accodato. I dispositivi che si connettono tramite il protocollo MQTT non possono rifiutare i messaggi da cloud a dispositivo.
Un thread potrebbe non riuscire a elaborare un messaggio senza notificare all'hub IoT. In questo caso, i messaggi passano automaticamente dallo stato Invisibile allo stato Accodato dopo un timeout di visibilità (o timeout di blocco). La durata di questo timeout è di un minuto e non può essere modificata.
Un messaggio può passare dallo stato Accodato allo stato Invisibile e viceversa per il numero massimo di volte specificato nella proprietà numero massimo di recapiti nell'hub IoT. Dopo il numero di transizioni specificato, l'hub IoT imposta lo stato del messaggio su Non recapitabile. Analogamente, l'hub IoT imposta lo stato di un messaggio su Non recapitabile dopo la relativa scadenza.
Un dispositivo in genere completa un messaggio da cloud a dispositivo quando la perdita del messaggio non influisce sulla logica dell'applicazione. Un esempio di questo completamento potrebbe essere quando il dispositivo mantiene il contenuto del messaggio in locale o esegue correttamente un'operazione. Il messaggio potrebbe anche contenere informazioni temporanee, la cui perdita non influisce sulla funzionalità dell'applicazione. In alcuni casi, per le attività con esecuzione prolungata è possibile:
Completare il messaggio da cloud a dispositivo dopo che il dispositivo mantiene la descrizione dell'attività nell'archiviazione locale.
Inviare al back-end della soluzione una notifica con uno o più messaggi da dispositivo a cloud in diverse fasi di avanzamento dell'attività.
Scadenza del messaggio (durata)
Ogni messaggio da cloud a dispositivo ha una scadenza. Una delle opzioni seguenti imposta l'ora di scadenza:
- La proprietà ExpiryTimeUtc nel servizio
- L'hub IoT, usando la durata predefinita specificata come proprietà dell'hub IoT
Per altre informazioni sulla scadenza dei messaggi, vedere Opzioni di configurazione da cloud a dispositivo.
Un modo comune per sfruttare la scadenza di un messaggio e evitare l'invio di messaggi ai dispositivi disconnessi consiste nell'impostare valori brevi di durata. Questo approccio ottiene lo stesso risultato della gestione dello stato di connessione del dispositivo, ma è più efficiente. Quando si richiedono i riconoscimenti dei messaggi, l'hub IoT invia una notifica ai dispositivi:
- Sono in grado di ricevere messaggi.
- Non sono online o hanno avuto esito negativo.
Commenti sui messaggi
Quando si invia un messaggio da cloud a dispositivo, il servizio può richiedere il recapito di commenti e suggerimenti per messaggio sullo stato finale del messaggio. È possibile configurare il feedback dei messaggi impostando la proprietà dell'applicazione iothub-ack nel messaggio da cloud a dispositivo inviato a uno dei quattro valori seguenti:
| Valore proprietà ACK | Comportamento |
|---|---|
| none | Valore predefinito. L'hub IoT non genera un messaggio di feedback. |
| positivo | Se il messaggio da cloud a dispositivo raggiunge lo stato Completato, l'hub IoT genera un messaggio di feedback. |
| negativo | Se il messaggio da cloud a dispositivo raggiunge lo stato Non recapitabile, l'hub IoT genera un messaggio di feedback. |
| completi | L'hub IoT genera un messaggio di feedback in entrambi i casi. |
Se il valore della proprietà Ack è impostato su pieno e non si riceve un messaggio di feedback, significa che il messaggio di feedback è scaduto. Il servizio non può sapere cosa è successo al messaggio originale. In pratica, un servizio deve garantire che sia possibile elaborare i commenti prima della scadenza. La scadenza massima è di due giorni, che lascia il tempo necessario per eseguire di nuovo il servizio in caso di errore.
Come spiegato negli endpoint dell'hub IoT, l'hub IoT fornisce commenti e suggerimenti tramite un endpoint rivolto al servizio, /messages/servicebound/feedback, come messaggi. La semantica di ricezione per i commenti è uguale a quella dei messaggi da cloud a dispositivo. Quando è possibile, i commenti sui messaggio vengono riuniti in batch in un unico messaggio con il formato seguente:
| Proprietà | Descrizione |
|---|---|
| EnqueuedTime | Timestamp che indica quando l'hub ha ricevuto il messaggio di feedback. |
| UserId | {iot hub name} |
| TipoDiContenuto | application/vnd.microsoft.iothub.feedback.json |
Il sistema invia il feedback quando il batch raggiunge 64 messaggi o in 15 secondi dall'ultimo invio, a seconda del primo.
Il corpo è una matrice serializzata con JSON dei record, ognuno con le proprietà seguenti:
| Proprietà | Descrizione |
|---|---|
| enqueuedTimeUtc | Timestamp che indica quando si è verificato il risultato del messaggio. Ad esempio, un timestamp che indica quando l'hub ha ricevuto il messaggio di feedback o il messaggio originale è scaduto. |
| originalMessageId | MessageId del messaggio da cloud a dispositivo a cui sono correlate queste informazioni di feedback. |
| statusCode | Stringa obbligatoria, usata dall'hub IoT durante la generazione di messaggi di feedback: Successo Scaduta DeliveryCountExceeded Rifiutato Eliminato definitivamente |
| description | Valori stringa per StatusCode. |
| deviceId | DeviceId del dispositivo di destinazione del messaggio da cloud a dispositivo a cui si riferisce questo feedback. |
| deviceGenerationId | DeviceGenerationId del dispositivo di destinazione del messaggio da cloud a dispositivo a cui si riferisce questo feedback. |
Il servizio deve specificare un MessageId in modo che il messaggio da cloud a dispositivo possa correlare il feedback con il messaggio originale.
Il corpo di un messaggio di feedback è illustrato nell'esempio di codice seguente:
[
{
"originalMessageId": "0987654321",
"enqueuedTimeUtc": "2015-07-28T16:24:48.789Z",
"statusCode": "Success",
"description": "Success",
"deviceId": "123",
"deviceGenerationId": "abcdefghijklmnopqrstuvwxyz"
},
{
...
},
...
]
Feedback in sospeso per i dispositivi eliminati
Quando un dispositivo viene eliminato, viene eliminato anche qualsiasi feedback in sospeso. Il feedback del dispositivo viene inviato in batch. Una finestra stretta, spesso inferiore a un secondo, può verificarsi tra quando un dispositivo conferma la ricezione del messaggio e quando viene preparato il batch di feedback successivo. Se un dispositivo viene eliminato in tale finestra stretta, il feedback non si verifica.
È possibile risolvere questo comportamento attendendo l'arrivo del feedback in sospeso prima di eliminare il dispositivo. Si presuppone che il feedback del messaggio correlato venga perso dopo l'eliminazione di un dispositivo.
Opzioni di configurazione da cloud a dispositivo
Ogni hub IoT espone le opzioni di configurazione seguenti per la messaggistica da cloud a dispositivo:
| Proprietà | Descrizione | Intervallo e valore predefinito |
|---|---|---|
| defaultTtlAsIso8601 (valore di default per il tempo di scadenza in formato ISO 8601) | Durata (TTL) predefinita per messaggi da cloud a dispositivo | ISO_8601 intervallo fino a due giorni (minimo un minuto); default: un'ora |
| maxDeliveryCount | Numero massimo di recapiti per code da cloud a dispositivo per i singoli dispositivi | Da 1 a 100; valore predefinito: 10 |
| feedback.ttlAsIso8601 | Conservazione per messaggi con commenti diretti al servizio | ISO_8601 intervallo fino a due giorni (minimo un minuto); default: un'ora |
| feedback.maxDeliveryCount | Numero massimo di recapito per la coda di commenti e suggerimenti | Da 1 a 100; valore predefinito: 10 |
| feedback.lockDurationAsIso8601 | Durata blocco per la coda di feedback | ISO_8601 intervallo da 5 a 300 secondi (minimo cinque secondi); valore predefinito: 60 secondi. |
È possibile impostare le opzioni di configurazione nel portale di Azure o nell'interfaccia della riga di comando di Azure:
Portale di Azure: in Impostazioni hub nell'hub IoT, selezionare Endpoint predefiniti e passare a Messaggistica da cloud a dispositivo. L'impostazione della proprietà feedback.maxDeliveryCount o feedback.lockDurationAsIso8601 non è attualmente supportata nel portale di Azure.
Interfaccia della riga di comando di Azure: usare il comando az iot hub update:
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
Passaggi successivi
Per informazioni sugli SDK che è possibile usare per gestire i messaggi da cloud a dispositivo, vedere Sdk dell'hub IoT di Azure.
Per indicazioni sullo sviluppo di applicazioni che gestiscono messaggi da cloud a dispositivo, vedere Inviare e ricevere messaggi da cloud a dispositivo.