Comprendere e usare dispositivi gemelli nell'hub IoT
I dispositivi gemelli sono documenti JSON nei quali vengono archiviate informazioni sullo stato dei dispositivi, ad esempio metadati, configurazioni e condizioni. L'hub IoT di Azure gestisce un dispositivo gemello per ogni dispositivo che viene connesso all'hub IoT.
Nota
Le funzionalità descritte in questo articolo sono disponibili solo nel livello Standard dell'hub IoT. Per altre informazioni sui livelli di hub IoT basic e standard/gratuiti, vedere Scegliere il livello di hub IoT appropriato per la soluzione.
L'articolo illustra:
- la struttura del dispositivo gemello: tag, proprietà desiderate e segnalate.
- Le operazioni che le app per dispositivo e i back-end possono eseguire sui dispositivi gemelli.
Usare i dispositivi gemelli per:
Archiviare i metadati specifici del dispositivo nel cloud, ad esempio il percorso di distribuzione di un distributore automatico.
Segnalare informazioni sullo stato corrente, come funzionalità disponibili e condizioni dall'app per dispositivo. Ad esempio, se un dispositivo è connesso all'hub IoT tramite rete cellulare o Wi-Fi.
Sincronizzare lo stato dei flussi di lavoro a esecuzione prolungata tra l'app per dispositivi e back-end, ad esempio quando il back-end della soluzione specifica la nuova versione del firmware da installare e l'app per dispositivo segnala le varie fasi del processo di aggiornamento.
Eseguire query sui metadati, la configurazione o lo stato dei dispositivi.
Vedere Indicazioni sulle comunicazioni da dispositivo a cloud per informazioni sull'uso delle proprietà indicate, dei messaggi da dispositivo a cloud o del caricamento di file.
Vedere Indicazioni sulle comunicazioni da cloud a dispositivo per informazioni sull'uso delle proprietà specifiche, dei metodi diretti o dei messaggi da cloud a dispositivo.
Per informazioni sul modo in cui i dispositivi gemelli sono correlati al modello di dispositivo usato da un dispositivo azure Plug and Play IoT, vedere Informazioni Plug and Play IoT gemelli digitali.
Dispositivi gemelli
I dispositivi gemelli consentono di archiviare informazioni sul dispositivo che possono essere usate:
Dal dispositivo e dai back-end per sincronizzare condizioni e configurazione del dispositivo.
Dal back-end della soluzione per eseguire query e come destinazione delle operazioni a esecuzione prolungata.
Il ciclo di vita di un dispositivo gemello è correlato all'identità del dispositivo corrispondente. I dispositivi gemelli vengono creati ed eliminati implicitamente quando viene creata o eliminata un'identità del dispositivo nell'hub IoT.
Un dispositivo gemello è un documento JSON che include:
Tag. Una sezione del documento JSON che il back-end della soluzione è in grado di leggere e in cui può scrivere. I tag non sono visibili alle applicazioni per dispositivi.
Proprietà desiderate. Sono usate insieme alle proprietà segnalate per sincronizzare la configurazione o le condizioni del dispositivo. Il back-end della soluzione è in grado di impostare le proprietà desiderate e l'app per dispositivo è in grado di leggerle. L'app per dispositivo può anche ricevere notifiche relative alle modifiche apportate alle proprietà desiderate.
Proprietà segnalate. Sono usate insieme alle proprietà desiderate per sincronizzare la configurazione o le condizioni del dispositivo. L'app per dispositivo è in grado di impostare le proprietà segnalate, mentre il back-end della soluzione è in grado di fare delle query.
Proprietà delle identità dei dispositivi. La radice del documento JSON del dispositivo gemello contiene le proprietà di sola lettura dell'identità del dispositivo corrispondente archiviata nel registro delle identità. Proprietà
connectionStateUpdatedTimeegenerationIdnon verranno incluse.
L'esempio seguente illustra un documento JSON del dispositivo gemello:
{
"deviceId": "devA",
"etag": "AAAAAAAAAAc=",
"status": "enabled",
"statusReason": "provisioned",
"statusUpdateTime": "0001-01-01T00:00:00",
"connectionState": "connected",
"lastActivityTime": "2015-02-30T16:24:48.789Z",
"cloudToDeviceMessageCount": 0,
"authenticationType": "sas",
"x509Thumbprint": {
"primaryThumbprint": null,
"secondaryThumbprint": null
},
"version": 2,
"tags": {
"deploymentLocation": {
"building": "43",
"floor": "1"
}
},
"properties": {
"desired": {
"telemetryConfig": {
"sendFrequency": "5m"
},
"$metadata" : {...},
"$version": 1
},
"reported": {
"telemetryConfig": {
"sendFrequency": "5m",
"status": "success"
},
"batteryLevel": 55,
"$metadata" : {...},
"$version": 4
}
}
}
Nell'oggetto radice si trovano le proprietà dell'identità del dispositivo e gli oggetti contenitore per tags e per entrambe le proprietà reported e desired. Il properties contenitore contiene alcuni elementi di sola lettura ($metadata e $version) descritti nelle sezioni Metadati dispositivo gemello e Concorrenza ottimistica.
Esempio di proprietà segnalata
Nell'esempio precedente, il dispositivo gemello contiene la proprietà batteryLevel che viene segnalata dall'app per dispositivo. Questa proprietà consente di eseguire una query e di far funzionare i dispositivi in base al livello di carica della batteria più recente segnalato. Altri esempi sono l'app per dispositivo che segnala le funzionalità o le opzioni di connettività del dispositivo.
Nota
Le proprietà segnalate semplificano gli scenari in cui il back-end della soluzione è interessato all'ultimo valore noto di una proprietà. Usare i messaggi dal dispositivo al cloud se il back-end della soluzione deve elaborare la telemetria del dispositivo in forma di sequenze di eventi con timestamp, ad esempio una serie temporale.
Esempio di proprietà desiderata
Nell'esempio precedente le proprietà desiderate e segnalate del dispositivo gemello telemetryConfig vengono usate dal back-end della soluzione e dall'app per dispositivo per sincronizzare la configurazione della telemetria per questo dispositivo. Ad esempio:
Il back-end della soluzione imposta la proprietà desiderata sul valore di configurazione desiderato. Questa è la parte del documento con il set di proprietà desiderate:
"desired": { "telemetryConfig": { "sendFrequency": "5m" }, ... },L'app del dispositivo riceve una notifica immediata della modifica se il dispositivo è connesso. Se non è connesso, l'app del dispositivo segue il flusso di riconnessione del dispositivo quando si connette. L'app segnala quindi la configurazione aggiornata o una condizione di errore riscontrata nell'uso della proprietà
status. Questa è la parte con le proprietà segnalate:"reported": { "telemetryConfig": { "sendFrequency": "5m", "status": "success" } ... }Il back-end della soluzione può tenere traccia dei risultati dell'operazione di configurazione su più dispositivi, eseguendo query sui dispositivi gemelli.
Nota
I frammenti di codice precedenti sono esempi ottimizzati per una migliore leggibilità, di un modo per codificare una configurazione del dispositivo e il relativo stato. L'hub IoT non impone uno schema specifico per l'uso delle proprietà desiderate e segnalate del dispositivo gemello nei dispositivi gemelli.
Importante
Plug and Play IoT definisce uno schema che usa diverse proprietà aggiuntive per sincronizzare le modifiche alle proprietà desiderate e segnalate. Se la soluzione usa Plug and Play IoT, è necessario seguire le convenzioni Plug and Play durante l'aggiornamento delle proprietà dei dispositivi gemelli. Per altre informazioni e un esempio, vedere Proprietà scrivibili in Plug and Play IoT.
È possibile usare i gemelli per sincronizzare le operazioni a esecuzione prolungata, ad esempio gli aggiornamenti del firmware. Per altre informazioni su come usare le proprietà per sincronizzare e tenere traccia dell'operazione a esecuzione prolungata sui dispositivi, vedere Usare le proprietà desiderate per configurare i dispositivi.
Operazioni di back-end
Il back-end della soluzione opera sul dispositivo gemello tramite le seguenti operazioni atomiche esposte tramite HTTPS:
Recuperare un dispositivo gemello tramite ID. Questa operazione restituisce il documento del dispositivo gemello, inclusi tag e proprietà di sistema desiderate e segnalate.
Aggiornare parzialmente il dispositivo gemello. Questa operazione consente al back-end della soluzione di aggiornare parzialmente i tag o le proprietà desiderate di un dispositivo gemello. L'aggiornamento parziale è espresso come documento JSON che aggiunge o aggiorna tutte le proprietà. Le proprietà impostate su
nullvengono rimosse. L'esempio seguente crea una nuova proprietà desiderata con valore{"newProperty": "newValue"}, sostituisce il valore esistente diexistingPropertycon"otherNewValue", e rimuoveotherOldProperty. Non vengono apportate altre modifiche alle altre proprietà desiderate o ai tag esistenti:{ "properties": { "desired": { "newProperty": { "nestedProperty": "newValue" }, "existingProperty": "otherNewValue", "otherOldProperty": null } } }Sostituzione di proprietà desiderate. Questa operazione consente al back-end della soluzione di sovrascrivere completamente tutte le proprietà desiderate esistenti e di sostituirle con un nuovo documento JSON
properties/desired.Sostituzione di tag. Questa operazione consente al back-end della soluzione di sovrascrivere completamente tutti i tag esistenti e di sostituirli con un nuovo documento JSON
tags.Ricezione di notifiche relative al dispositivo gemello. Questa operazione invia notifiche al back-end della soluzione a ogni modifica del dispositivo gemello. A questo scopo, la soluzione IoT deve creare una route e impostare l'origine dati su twinChangeEvents. Per impostazione predefinita, non esiste alcuna route di questo tipo, quindi non vengono inviate notifiche gemelle. Se la frequenza delle modifiche è troppo elevata o per altri motivi, ad esempio un errore interno, l'hub IoT potrebbe inviare solo una notifica che contiene tutte le modifiche. Se pertanto l'applicazione ha bisogno di controllo e registrazione affidabili di tutti gli stati intermedi, è consigliabile usare messaggi da dispositivo a cloud. Per altre informazioni sulle proprietà e sul corpo restituito nel messaggio di notifica del gemello, vedere Schemi di eventi non di telemetria.
Tutte le operazioni precedenti supportano la concorrenza ottimistica e richiedono l'autorizzazione ServiceConnect, come indicato nell'articolo Controllare l'accesso all'hub IoT.
Oltre a queste operazioni, il back-end della soluzione può:
Eseguire una query sui dispositivi gemelli usando il linguaggio di query hub IoT simile a SQL.
Eseguire operazioni su set di grandi dimensioni dei dispositivi gemelli usando i processi.
Operazioni del dispositivo
Il dispositivo opera sul dispositivo gemello usando le seguenti operazioni atomiche:
Recuperare un dispositivo gemello. Questa operazione restituisce il documento del dispositivo gemello, incluse le proprietà di sistema desiderate e segnalate, al dispositivo attualmente connesso. I tag non sono visibili alle app del dispositivo.
Aggiornamento parziale delle proprietà segnalate. Questa operazione consente l'aggiornamento parziale delle proprietà segnalate del dispositivo attualmente connesso. Questa operazione usa lo stesso formato di aggiornamento JSON che il back-end della soluzione usa per un aggiornamento parziale delle proprietà desiderate.
Osservazione di proprietà desiderate. Il dispositivo attualmente connesso può scegliere di ricevere la notifica degli aggiornamenti delle proprietà desiderate quando vengono eseguiti. Il dispositivo riceve lo stesso modulo di aggiornamento che segnala la sostituzione parziale o completa eseguita dal back-end della soluzione.
Tutte le operazioni precedenti richiedono l'autorizzazione DeviceConnect, come definito in Controllare l'accesso all'hub IoT.
Azure IoT SDK per dispositivi semplifica l'uso delle operazioni precedenti con linguaggi e piattaforme diversi. Per altre informazioni sulle primitive dell'hub IoT per la sincronizzazione delle proprietà desiderate vedere Flusso di riconnessione del dispositivo.
Formato di tag e proprietà
I tag e le proprietà desiderate e segnalate sono oggetti JSON soggetti alle restrizioni indicate di seguito:
Chiavi: tutte le chiavi negli oggetti JSON sono con codifica UTF-8, con distinzione tra maiuscole e minuscole e fino a 1 KB. I caratteri consentiti escludono i caratteri di controllo UNICODE (segmenti C0 e C1) e
.,$e SP.Nota
hub IoT query usate in Il routing dei messaggi non supporta spazi vuoti o uno dei caratteri seguenti come parte di un nome di chiave:
()<>@,;:\"/?={}.Valori: tutti i valori negli oggetti JSON possono essere dei tipi JSON seguenti: boolean, number, string, object. Sono supportate anche matrici.
I numeri interi possono avere un valore minimo pari a -4503599627370496 e un valore massimo di 4503599627370495.
I valori stringa sono codificati con UTF-8 e possono avere una lunghezza massima di 4 KB.
Profondità: la profondità massima degli oggetti JSON nei tag, nelle proprietà desiderate e nelle proprietà segnalate è 10. Ad esempio, l'oggetto seguente è valido:
{ ... "tags": { "one": { "two": { "three": { "four": { "five": { "six": { "seven": { "eight": { "nine": { "ten": { "property": "value" } } } } } } } } } } }, ... }
Dimensioni del dispositivo gemello
hub IoT applica un limite di dimensioni di 8 KB per il valore di e un limite di tagsdimensioni di 32 KB ciascuno per il valore di properties/desired e properties/reported. Questi totali sono esclusivi di elementi di sola lettura come $version e $metadata/$lastUpdated.
Le dimensioni dei dispositivi gemelli vengono calcolate nel modo seguente:
Per ogni proprietà nel documento JSON, hub IoT calcola in modo cumulativo e aggiunge la lunghezza della chiave e del valore della proprietà.
Le chiavi delle proprietà vengono considerate come stringhe con codifica UTF8.
I valori delle proprietà semplici vengono considerati come stringhe con codifica UTF8, valori numerici (8 byte) o valori booleani (4 byte).
Le dimensioni delle stringhe con codifica UTF8 vengono calcolate con il conteggio di tutti i caratteri, esclusi i caratteri di controllo UNICODE (segmenti C0 e C1).
I valori delle proprietà complesse (oggetti annidati) vengono calcolati in base alle dimensioni aggregate delle chiavi delle proprietà e ai valori delle proprietà che contengono.
hub IoT rifiuta con un errore tutte le operazioni che aumentano le dimensioni dei tagsdocumenti , properties/desiredo properties/reported oltre il limite.
Metadati del dispositivo gemello
L'hub IoT conserva il timestamp dell'ultimo aggiornamento di ogni oggetto JSON nelle proprietà desiderate e segnalate del dispositivo gemello. I timestamp sono in formato UTC e codificati in formato ISO8601YYYY-MM-DDTHH:MM:SS.mmmZ.
Ad esempio:
{
...
"properties": {
"desired": {
"telemetryConfig": {
"sendFrequency": "5m"
},
"$metadata": {
"telemetryConfig": {
"sendFrequency": {
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$version": 23
},
"reported": {
"telemetryConfig": {
"sendFrequency": "5m",
"status": "success"
},
"batteryLevel": "55%",
"$metadata": {
"telemetryConfig": {
"sendFrequency": {
"$lastUpdated": "2016-03-31T16:35:48.789Z"
},
"status": {
"$lastUpdated": "2016-03-31T16:35:48.789Z"
},
"$lastUpdated": "2016-03-31T16:35:48.789Z"
},
"batteryLevel": {
"$lastUpdated": "2016-04-01T16:35:48.789Z"
},
"$lastUpdated": "2016-04-01T16:24:48.789Z"
},
"$version": 123
}
}
...
}
Queste informazioni vengono mantenute a ogni livello (non solo al livello foglia della struttura JSON) per conservare gli aggiornamenti che rimuovono le chiavi dell'oggetto.
Concorrenza ottimistica
I tag, le proprietà desiderate e le proprietà segnalate supportano la concorrenza ottimistica. Se è necessario garantire l'ordine degli aggiornamenti delle proprietà gemelle, valutare la possibilità di implementare la sincronizzazione a livello di applicazione attendendo il callback delle proprietà segnalate prima di inviare l'aggiornamento successivo.
I dispositivi gemelli hanno una proprietà ETag (etag ), in base RFC7232, che rappresenta la rappresentazione JSON del gemello. È possibile usare la etag proprietà nelle operazioni di aggiornamento condizionale dal back-end della soluzione per garantire la coerenza. Questa è l'unica opzione per garantire la coerenza nelle operazioni che coinvolgono il tags contenitore.
Le proprietà desiderate e segnalate del dispositivo gemello hanno anche un $version valore garantito come incrementale. In modo analogo a un valore ETag, la versione può essere usata dall'entità di aggiornamento per garantire la coerenza degli aggiornamenti. Ad esempio, un'app per dispositivo per una proprietà segnalata o la soluzione del back-end per una proprietà desiderata.
Le versioni sono utili anche quando un agente di osservazione, ad esempio l'app per dispositivo che osserva le proprietà desiderate, deve riconciliare le concorrenze tra il risultato di un'operazione di recupero e una notifica di aggiornamento. Altre informazioni sono reperibili nella sezione Flusso di riconnessione del dispositivo.
Flusso di riconnessione del dispositivo
L'hub IoT non conserva le notifiche di aggiornamento delle proprietà desiderate dei dispositivi connessi. Ne consegue che un dispositivo che esegue la connessione deve recuperare il documento completo delle proprietà desiderate, ed eseguire la sottoscrizione alle notifiche di aggiornamento. Data la possibilità di concorrenza tra le notifiche di aggiornamento e il recupero completo, deve essere assicurato il flusso seguente:
- L'app per dispositivo esegue la connessione a un hub IoT.
- L'app per dispositivo esegue la sottoscrizione per le notifiche di aggiornamento delle proprietà desiderate.
- L'app per dispositivo recupera il documento completo delle proprietà desiderate.
L'app per dispositivo è in grado di ignorare tutte le notifiche con il valore di $version minore o uguale a quello dell'intero documento recuperato. Questo approccio è possibile poiché l'hub IoT garantisce l'incremento delle versioni.
Materiale di riferimento
Di seguito sono indicati altri argomenti di riferimento reperibili nella Guida per gli sviluppatori dell'hub IoT:
L'articolo IoT Hub endpoints (Endpoint dell'hub IoT) illustra i diversi endpoint esposti da ogni hub IoT per operazioni della fase di esecuzione e di gestione.
L'articolo Quote e limitazioni descrive le quote applicabili al servizio hub IoT e il comportamento di limitazione previsto quando si usa il servizio.
L'articolo Azure IoT SDK per dispositivi e servizi elenca gli SDK nei diversi linguaggi che è possibile usare quando si sviluppano app per dispositivi e servizi che interagiscono con l'hub IoT.
L'articolo Linguaggio di query dell'hub IoT per dispositivi gemelli, processi e routing di messaggi descrive il linguaggio di query dell’hub IoT che è possibile usare per recuperare informazioni dall’hub IoT sui processi e i dispositivi gemelli.
L'articolo Supporto di MQTT nell'hub IoT offre altre informazioni sul supporto dell'hub IoT per il protocollo MQTT.
Passaggi successivi
In questa esercitazione si è appreso come usare i dispositivi gemelli. Altri argomenti di interesse disponibili nella Guida per sviluppatori dell'hub IoT:
- Comprendere e usare i moduli gemelli nell'hub IoT
- Richiamare un metodo diretto in un dispositivo
- Pianificare processi in più dispositivi
Per provare alcuni dei concetti descritti in questo articolo, vedere le esercitazioni sull'hub IoT seguenti: