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.

L'articolo illustra:

• Struttura del dispositivo gemello: tag, proprietà desiderate e proprietà segnalate.
• Le operazioni che le applicazioni di dispositivo e back-end possono eseguire sui dispositivi gemelli.

Usare i dispositivi gemelli per:

• Archiviare i metadati specifici del dispositivo nel cloud, Ad esempio, la posizione 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.

Per altre informazioni sull'uso di proprietà segnalate, messaggi da dispositivo a cloud o caricamento di file, vedere Linee guida per la comunicazione da dispositivo a cloud.

Per altre informazioni sull'uso delle proprietà desiderate, dei metodi diretti o dei messaggi da cloud a dispositivo, vedere Linee guida per la comunicazione 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 è collegato 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 app del dispositivo.

• 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à connectionStateUpdatedTime e generationId non 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
        }
    }
}

L'oggetto radice contiene le proprietà dell'identità del dispositivo e gli oggetti contenitore per tags e sia reported desired per che per le proprietà . 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.

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:

1. Il back-end della soluzione imposta la proprietà desiderata sul valore di configurazione desiderato. Ecco la parte del documento con il set di proprietà desiderato:

   "desired": {
       "telemetryConfig": {
           "sendFrequency": "5m"
       },
       ...
   },
   

2. 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. Ecco la parte delle proprietà segnalate:

   "reported": {
       "telemetryConfig": {
           "sendFrequency": "5m",
           "status": "success"
       }
       ...
   }
   

3. Il back-end della soluzione tiene traccia dei risultati dell'operazione di configurazione in molti dispositivi eseguendo query sui dispositivi gemelli.

È 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 null vengono rimosse. L'esempio seguente crea una nuova proprietà desiderata con valore {"newProperty": "newValue"}, sostituisce il valore esistente di existingProperty con "otherNewValue", e rimuove otherOldProperty. 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 nontelemetry.

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 sul 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à etagETag , 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 proprietà è 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

hub IoT non mantiene le notifiche di aggiornamento delle proprietà desiderate per i dispositivi disconnessi. 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:

1. L'app per dispositivo esegue la connessione a un hub IoT.
2. L'app per dispositivo esegue la sottoscrizione per le notifiche di aggiornamento delle proprietà desiderate.
3. 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.

Passaggi successivi

Per provare alcuni dei concetti descritti in questo articolo, vedere gli articoli seguenti hub IoT:

• Esercitazione: Configurare i dispositivi con le proprietà dei dispositivi gemelli
• Come usare i dispositivi gemelli