Informazioni sulla messaggistica da cloud a dispositivo da un hub IoT
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 da hub IoT di Azure, vedere Linee guida sulle comunicazioni da cloud a dispositivo.
Nota
Le funzionalità descritte in questo articolo sono disponibili solo nel livello Standard dell'hub IoT. Per altre informazioni sui livelli Basic e Standard/Gratuito dell'hub IoT, vedere Scegliere il livello appropriato dell'hub IoT per la soluzione.
Si inviano messaggi da cloud a dispositivo tramite un endpoint rivolto al servizio, /messages/devicebound. Un dispositivo riceve quindi i messaggi tramite un endpoint specifico del 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 /devices/{deviceId}/messages/devicebound.
Ogni coda di dispositivi contiene al massimo 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 messaggi almeno una volta, l'hub IoT rende persistenti i messaggi da cloud a dispositivo nelle code per dispositivo. 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, il servizio imposta lo stato del messaggio su Accodamento. 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, che determina l'impostazione dell'hub IoT sullo stato Messaggi non recapitati . Non esiste alcuna 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, che causa l'inserimento del messaggio nell'hub IoT nella coda, con lo stato impostato su Accodamento. 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.
La proprietà numero massimo di recapito nell'hub IoT determina il numero massimo di volte in cui un messaggio può eseguire la transizione tra gli stati Accodati e Invisibili . Dopo tale numero di transizioni, l'hub IoT imposta lo stato del messaggio su Messaggi non recapitati. Analogamente, l'hub IoT imposta lo stato di un messaggio su Messaggi non recapitati dopo la 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 ha salvato in modo permanente il contenuto del messaggio in locale o ha eseguito 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 ha reso persistente 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. Questa volta viene impostata da una delle opzioni seguenti:
- 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 consente di ottenere 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 abilitati a ricevere messaggi.
- sono offline, oppure l'operazione non è riuscita.
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 della proprietà Ack | Comportamento |
|---|---|
| Nessuno | 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 Messaggi non recapitabili , l'hub IoT genera un messaggio di feedback. |
| full | 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 in Endpoint, l'hub IoT fornisce feedback 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 il messaggio di feedback è stato ricevuto dall'hub. |
| ID utente | {iot hub name} |
| ContentType | application/vnd.microsoft.iothub.feedback.json |
Il sistema invierà il feedback quando il batch raggiungerà 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 nei messaggi di feedback generati dall'hub IoT: Success Scaduta DeliveryCountExceeded Rifiutata Eliminati |
| 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 un periodo di tempo per l'arrivo di commenti e suggerimenti 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 | Durata (TTL) predefinita per i messaggi da cloud a dispositivo | ISO_8601 intervallo fino a due giorni (minimo un minuto); default: un'ora |
| maxDeliveryCount | Numero massimo di recapito per le code da cloud a dispositivo per dispositivo | da 1 a 100; valore predefinito: 10 |
| feedback.ttlAsIso8601 | Conservazione per i messaggi di feedback associati 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 dei commenti e suggerimenti | ISO_8601 intervallo da 5 a 300 secondi (minimo cinque secondi); valore predefinito: 60 secondi. |
È possibile impostare le opzioni di configurazione nella 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 delle proprietà feedback.maxDeliveryCount e feedback.lockDurationAsIso8601 non è attualmente supportata in 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 hub IoT di Azure SDK.
Per indicazioni sullo sviluppo di applicazioni che gestiscono messaggi da cloud a dispositivo, vedere Inviare e ricevere messaggi da cloud a dispositivo.