Inviare messaggi da cloud a dispositivo da un hub IoT
Per inviare notifiche unidirezionale a un'app per dispositivi dal back-end della soluzione, inviare messaggi da cloud a dispositivo dall'hub IoT al dispositivo. Per una discussione sulle 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 di hub IoT di base e standard/gratuiti, vedere Scegliere il livello di hub IoT appropriato per la soluzione.
Si inviano messaggi da cloud a dispositivo tramite un endpoint con connessione al servizio, /messages/devicebound. Un dispositivo riceve quindi i messaggi tramite un endpoint specifico del dispositivo, /devices/{deviceId}/messages/devicebound.
Per indirizzare 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 più messaggi allo stesso dispositivo.
Ciclo di vita del messaggio da cloud a dispositivo
Per garantire il recapito di messaggi almeno una volta, l'hub IoT mantiene persistenti i messaggi da cloud a dispositivo nelle code per dispositivo. I dispositivi devono riconoscere in modo esplicito il completamento di un messaggio prima che l'hub IoT rimuove 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 Enqueued. Quando un dispositivo vuole ricevere un messaggio, l'hub IoT blocca il messaggio impostando lo stato su Invisibile. Questo stato consente ad altri thread nel dispositivo di avviare la ricezione di 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 causa l'impostazione dell'hub IoT sullo stato letterato non recapitato . I dispositivi che si connettono al protocollo Message Queuing Telemetry Transport (MQTT) non possono rifiutare messaggi da cloud a dispositivo.
Abbandonare il messaggio, che causa l'inserimento del messaggio nell'hub IoT nella coda, con lo stato impostato su Enqueued. I dispositivi che si connettono al protocollo MQTT non possono abbandonare i messaggi da cloud a dispositivo.
Un thread potrebbe non riuscire a elaborare un messaggio senza inviare una notifica all'hub IoT. In questo caso, i messaggi passano automaticamente dallo stato Invisibile allo stato Inqueued dopo un timeout di visibilità (o il timeout di blocco ). Il valore di questo timeout è di un minuto e non può essere modificato.
La proprietà Numero massimo di recapito nell'hub IoT determina il numero massimo di volte in cui un messaggio può passare tra gli stati Enqueued e Invisible . Dopo tale numero di transizioni, l'hub IoT imposta lo stato del messaggio su Dead lettered. Analogamente, l'hub IoT imposta lo stato di un messaggio su Dead lettered dopo la scadenza. Per altre informazioni, vedere Scadenza dei messaggi (ora di vita).
L'articolo Come inviare messaggi da cloud a dispositivo con hub IoT illustra come inviare messaggi da cloud a dispositivo dal cloud e riceverli in un dispositivo.
Un dispositivo completa normalmente 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 mantenuto 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 mantenuto 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 in base a una delle opzioni seguenti:
- Proprietà ExpiryTimeUtc nel servizio
- L'hub IoT, usando l'ora predefinita per vivere 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 per evitare l'invio di messaggi ai dispositivi disconnessi consiste nell'impostare breve tempo per i valori live . 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 notifica quali dispositivi sono:
- 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 | 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 recapitato , 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 completo 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 per ottenere nuovamente il servizio se si verifica un errore.
Come illustrato negli endpoint, l'hub IoT fornisce commenti e suggerimenti tramite un endpoint con connessione 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. |
| UserId | {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.
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 richiesta, usata nei messaggi di feedback generati dall'hub IoT: Success Scaduta DeliveryCountExceeded Rifiutato Eliminati |
| description | Valori stringa per StatusCode. |
| deviceId | DeviceId del dispositivo di destinazione del messaggio da cloud a dispositivo a cui è correlato questo feedback. |
| deviceGenerationId | DeviceGenerationId del dispositivo di destinazione del messaggio da cloud a dispositivo a cui è correlato 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"
},
{
...
},
...
]
Commenti e suggerimenti in sospeso per i dispositivi eliminati
Quando un dispositivo viene eliminato, vengono eliminati anche eventuali commenti e suggerimenti 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. Dopo l'eliminazione di un dispositivo, si deve presumere che il feedback del messaggio correlato vada perso.
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); impostazione predefinita: un'ora |
| maxDeliveryCount | Numero massimo di recapito per le code da cloud a 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); impostazione predefinita: un'ora |
| feedback.maxDeliveryCount | Numero massimo di recapito per la coda dei commenti e suggerimenti | da 1 a 100; valore predefinito: 10 |
| feedback.lockDurationAsIso8601 | Durata del blocco per la coda dei commenti e suggerimenti | ISO_8601 intervallo da 5 a 300 secondi (minimo cinque secondi); impostazione predefinita: 60 secondi. |
È possibile impostare le opzioni di configurazione in uno dei modi seguenti:
- portale di Azure: in Impostazioni hub nell'hub IoT selezionare Endpoint predefiniti e passare alla 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 ricevere messaggi da cloud a dispositivo, vedere hub IoT di Azure SDK.
Per provare a ricevere i messaggi da cloud a dispositivo, vedere l'esercitazione Invio da cloud a dispositivo.