Comprendere e usare i moduli gemelli nell'hub IoT

In hub IoT, in ogni identità del dispositivo, è possibile creare fino a 50 identità del modulo. Ogni identità del modulo genera implicitamente un modulo gemello. Simili ai dispositivi gemelli, i moduli gemelli sono documenti JSON nei quali vengono archiviate informazioni sullo stato dei moduli, tra cui metadati, configurazioni e condizioni. L'hub IoT di Azure mantiene un modulo gemello per ogni modulo che viene connesso all'hub IoT.

Questo articolo presuppone che sia necessario leggere Comprendere e usare i dispositivi gemelli in hub IoT prima.

Sul lato dispositivo, gli SDK (Device Software Development Kit) hub IoT consentono di creare moduli in cui ognuno apre una connessione indipendente a hub IoT. Questa funzionalità permette di usare spazi dei nomi distinti per i diversi componenti nel dispositivo. Supponiamo ad esempio di avere un distributore automatico con tre diversi sensori. I diversi reparti dell'azienda controllano ogni sensore. È possibile creare un modulo per ogni sensore in modo che un reparto sia in grado di inviare processi o metodi diretti al sensore controllato, evitando conflitti ed errori dell'utente.

L'identità del modulo e il modulo gemello offrono le stesse funzionalità dell'identità del dispositivo e dei dispositivi gemelli, ma con una granularità superiore. Questa granularità superiore consente a determinati dispositivi, ad esempio i dispositivi basati su sistema operativo o i dispositivi firmware che gestiscono più componenti, di isolare la configurazione e le condizioni di ognuno di questi componenti. L'identità del modulo e i moduli gemelli consentono di gestire separatamente i diversi problemi quando si usano dispositivi IoT con componenti software modulari. L'obiettivo di Microsoft è supportare tutte le funzionalità dei dispositivi gemelli a livello di modulo gemello in base alla disponibilità generale dei moduli gemelli.

L'articolo illustra:

• la struttura del modulo gemello: tag, proprietà desiderate e proprietà segnalate.
• Le operazioni che le applicazioni del dispositivo e il back-end della soluzione possono eseguire sui moduli gemelli.

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.

Moduli gemelli

I moduli gemelli consentono di archiviare informazioni sul modulo che possono essere usate:

• Dai moduli nel dispositivo e dall'hub IoT per sincronizzare le condizioni e la configurazione del modulo.

• Dal back-end della soluzione per eseguire query e come destinazione delle operazioni a esecuzione prolungata.

Il ciclo di vita di un modulo gemello è correlato all'identità del modulo corrispondente. I moduli gemelli vengono creati ed eliminati implicitamente quando viene creata o eliminata un'identità del modulo nell'hub IoT.

Un modulo gemello è un documento JSON che include:

• Tag. Sezione del documento JSON in cui le app back-end possono leggere e scrivere. I tag non sono visibili ai moduli nel dispositivo. I tag vengono impostati per consentire l'esecuzione di query.

• Proprietà desiderate. Sono usate insieme alle proprietà segnalate per sincronizzare la configurazione o le condizioni del modulo. Le app back-end possono impostare le proprietà desiderate e l'app per i moduli può leggerle. L'app per modulo 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 modulo. L'app del modulo può impostare le proprietà segnalate e le app back-end possono leggerle ed eseguirle query.

• Proprietà dell'identità del modulo. La radice del documento JSON del modulo gemello contiene le proprietà di sola lettura dell'identità del modulo corrispondente archiviata nel registro delle identità.

L'esempio seguente illustra un documento JSON del modulo gemello:

{
    "deviceId": "devA",
    "moduleId": "moduleA",
    "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
        }
    }
}

Al livello superiore, un oggetto modulo gemello contiene le proprietà identity del modulo 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 del modulo gemello e Concorrenza ottimistica.

Esempio di proprietà segnalata

Nell'esempio precedente il modulo gemello contiene una batteryLevel proprietà segnalata. Questa proprietà consente di eseguire query e di operare sui moduli in base al livello di carica della batteria più recente segnalato. Altri esempi sono l'app per modulo che segnala le funzionalità o le opzioni di connettività del modulo.

Esempio di proprietà desiderata

Nell'esempio precedente le proprietà desiderate e segnalate del telemetryConfig modulo gemello vengono usate dalle app back-end e dall'app del modulo per sincronizzare la configurazione dei dati di telemetria per questo modulo. Ad esempio:

1. Un'app back-end imposta la proprietà desiderata con il valore di configurazione desiderato. Ecco la parte del documento con il set di proprietà desiderato:

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

2. L'app del modulo riceve una notifica immediata della modifica se il modulo è connesso. Se non è connesso, l'app del modulo segue il flusso di riconnessione del modulo 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. Un'app back-end può tenere traccia dei risultati dell'operazione di configurazione in molti moduli eseguendo query sui moduli gemelli.

Operazioni di back-end

Le app back-end operano sul modulo gemello usando le operazioni atomico seguenti, esposte tramite HTTPS:

• Recupero del modulo gemello in base all'ID. Questa operazione restituisce il documento del modulo gemello, inclusi tag e proprietà di sistema desiderate e segnalate.

• Aggiornamento parziale del modulo gemello. Questa operazione aggiorna parzialmente i tag o le proprietà desiderate in un modulo 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 sovrascrive completamente tutte le proprietà desiderate esistenti e sostituisce un nuovo documento JSON per properties/desired.

• Sostituzione di tag. Questa operazione sovrascrive completamente tutti i tag esistenti e sostituisce un nuovo documento JSON per tags.

• Ricezione di notifiche relative al dispositivo gemello. Questa operazione notifica quando il gemello viene modificato. Per ricevere notifiche di modifica dei moduli gemelli, 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, le app back-end possono eseguire query sui moduli gemelli usando il linguaggio di query hub IoT simile a SQL.

Operazioni sui moduli

L'app per modulo opera sul modulo gemello usando le seguenti operazioni atomiche:

• Recupero del modulo gemello. Questa operazione restituisce il documento del modulo gemello (incluse le proprietà di sistema desiderate e segnalate) per il modulo attualmente connesso.

• Aggiornamento parziale delle proprietà segnalate. Questa operazione consente l'aggiornamento parziale delle proprietà segnalate del modulo attualmente connesso.

• Osservazione di proprietà desiderate. Il modulo attualmente connesso può scegliere di ricevere la notifica degli aggiornamenti delle proprietà desiderate quando vengono eseguiti.

Tutte le operazioni precedenti richiedono l'autorizzazione DeviceConnect, come definito nell'articolo Controllare l'accesso a hub IoT.

Azure IoT SDK per dispositivi semplifica l'uso delle operazioni precedenti con linguaggi e piattaforme diversi.

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.

• 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 modulo 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:

• hub IoT calcola in modo cumulativo e aggiunge la lunghezza della chiave e del valore di ogni 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.

L'hub IoT rifiuta con errore tutte le operazioni che aumentano le dimensioni dei documenti oltre il limite specificato.

Metadati del modulo gemello

L'hub IoT conserva il timestamp dell'ultimo aggiornamento di ogni oggetto JSON nelle proprietà desiderate e segnalate del modulo 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": "5m",
                    "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 moduli 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 dalle app back-end per garantire la coerenza. Questa opzione garantisce la coerenza nelle operazioni che coinvolgono il tags contenitore.

Le proprietà desiderate e segnalate del modulo gemello hanno anche un $version valore garantito come incrementale. Analogamente a un ETag, è possibile usare il valore della versione per applicare la coerenza degli aggiornamenti. Ad esempio, un'app per moduli per una proprietà segnalata o un'app back-end per una proprietà desiderata.

Le versioni sono utili anche quando un agente di osservazione, ad esempio l'app per modulo che osserva le proprietà desiderate, deve riconciliare le concorrenze tra il risultato di un'operazione di recupero e una notifica di aggiornamento. La sezione Flusso di riconnessione del modulo fornisce altre informazioni.

Flusso di riconnessione del modulo

hub IoT non mantiene le notifiche di aggiornamento delle proprietà desiderate per i moduli disconnessi. Segue che un modulo che si connette deve recuperare il documento completo delle proprietà desiderate, oltre alla sottoscrizione per le 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 i moduli si connette a un hub IoT.
2. L'app per i moduli sottoscrive le notifiche di aggiornamento delle proprietà desiderate.
3. L'app modulo recupera il documento completo per le proprietà desiderate.

L'app per i moduli può ignorare tutte le notifiche con $version meno o uguale alla versione del documento recuperato completo. Questo approccio è possibile poiché l'hub IoT garantisce l'incremento delle versioni.

Passaggi successivi

Per provare alcuni dei concetti descritti in questo articolo, vedere le esercitazioni sull'hub IoT seguenti:

• Introduzione all'identità del modulo e ai moduli gemelli dell'hub IoT usando il back-end .NET e i dispositivi .NET