Comprendere il registro delle identità nell'hub IoT

Ogni hub IoT ha un registro delle identità in cui sono archiviate le informazioni sui dispositivi a cui è consentito connettersi all'hub IoT. Prima che un dispositivo possa connettersi a un hub IoT, è necessario che sia presente una voce relativa al dispositivo nel registro delle identità dell'hub IoT. Un dispositivo deve autenticarsi anche con l'hub IoT in base alle credenziali archiviate nel registro delle identità.

L'ID dispositivo archiviato nel registro delle identità fa distinzione tra maiuscole e minuscole.

A livello generale, il registro delle identità è una raccolta delle risorse relative alle identità dei dispositivi che supporta REST. Quando si aggiunge una voce nel registro delle identità, l'hub IoT crea un set di risorse per dispositivo, ad esempio una coda contenente messaggi da cloud a dispositivo in elaborazione.

Quando usare le autorizzazioni

Usare il registro delle identità quando è necessario:

  • Il provisioning dei dispositivi che si connettono per l'hub IoT.
  • Controllare l'accesso per dispositivo agli endpoint che usano dispositivi dell'hub.
Nota

Il registro delle identità non contiene metadati specifici delle applicazioni.

Operazioni del registro delle identità

Il registro delle identità dell'hub IoT espone le operazioni seguenti:

  • Creare l'identità del dispositivo
  • Aggiornare l'identità del dispositivo
  • Recuperare l'identità del dispositivo tramite ID
  • Eliminare l'identità del dispositivo
  • Elencare al massimo 1000 identità
  • Esportare tutte le identità nell'Archiviazione BLOB di Azure
  • Importare le identità nell'Archiviazione BLOB di Azure

Tutte queste operazioni possono usare la concorrenza ottimistica, come specificato in RFC7232.

Importante

L'unico modo per recuperare tutte le identità nel registro delle identità di un hub IoT consiste nell'usare la funzionalità Esporta.

Un registro delle identità di un hub IoT:

  • Non contiene metadati delle applicazioni.
  • È accessibile come un dizionario, usando il valore deviceId come chiave.
  • Non supporta le query espressive.

Una soluzione IoT include in genere un archivio separato specifico della soluzione che contiene metadati specifici dell'applicazione. Ad esempio, l'archivio specifico della soluzione in una soluzione per un edificio efficiente registra l'ambiente in cui viene distribuito un sensore di temperatura.

Importante

Usare il registro delle identità solo per le operazioni di gestione e provisioning dei dispositivi. Le operazioni a velocità effettiva elevata in fase di esecuzione non devono dipendere dall'esecuzione di operazioni nel registro delle identità. Ad esempio, la verifica dello stato di connessione di un dispositivo prima dell'invio di un comando non è uno schema supportato. Assicurarsi di verificare le frequenze di limitazione per il registro delle identità dei dispositivi e il modello di heartbeat del dispositivo.

Disabilitare i dispositivi

È possibile disabilitare i dispositivi aggiornando la proprietà status di un'identità nel registro delle identità. Questa proprietà viene in genere usata in due scenari:

  • Durante un processo di orchestrazione di provisioning. Per altre informazioni, vedere Provisioning di dispositivi.
  • Se, per qualsiasi motivo, si considera un dispositivo compromesso o non più autorizzato.

Importare ed esportare le identità dei dispositivi

È possibile esportare in blocco le identità dei dispositivi dal registro delle identità di un hub IoT usando operazioni asincrone sull'endpoint del provider di risorse dell'hub IoT. Le esportazioni sono processi a esecuzione prolungata che usano un contenitore BLOB specificato dal cliente per salvare i dati relativi alle identità dei dispositivi letti dal registro delle identità.

È possibile importare in blocco le identità dei dispositivi nel registro delle identità di un hub IoT usando operazioni asincrone sull'endpoint del provider di risorse dell'hub IoT. Le importazioni sono processi a esecuzione prolungata che usano un contenitore BLOB specificato dal cliente per scrivere i dati relativi alle identità nel registro delle identità.

Provisioning di dispositivi

I dati del dispositivo archiviati da una soluzione IoT dipendono dai requisiti specifici di tale soluzione. Tuttavia, come minimo, una soluzione deve archiviare identità di dispositivo e chiavi di autenticazione. L'hub IoT di Azure include un registro delle identità in grado di archiviare i valori per ogni dispositivo, ad esempio ID, chiavi di autenticazione e codici di stato. Una soluzione può usare altri servizi di Azure, ad esempio archiviazione tabelle, Archiviazione BLOB o Cosmos DB per archiviare dati aggiuntivi sui dispositivi.

Provisioning di dispositivi è il processo di aggiunta dei dati iniziali dei dispositivi agli archivi nella soluzione. Per abilitare un nuovo dispositivo per la connessione all'hub è necessario aggiungere un ID dispositivo e le relative chiavi al registro delle identità dell'hub IoT. Come parte del processo di provisioning, può essere necessario inizializzare i dati specifici del dispositivo in altri archivi di soluzioni.

Heartbeat dispositivo

Il registro delle identità dell'hub IoT contiene un campo denominato connectionState. Durante le fasi di sviluppo e debug, usare solo il campo connectionState. Le soluzioni IoT non devono eseguire query sul campo in fase di esecuzione. Ad esempio, non devono eseguire query sul campo connectionState per verificare se un dispositivo è connesso prima di inviare un messaggio da cloud a dispositivo o un SMS.

Se la soluzione IoT deve sapere se un dispositivo è connesso, è necessario implementare il modello di heartbeat.

Nel modello di heartbeat il dispositivo invia messaggi da dispositivo a cloud almeno una volta ogni intervallo di tempo stabilito, ad esempio almeno una volta ogni ora. Di conseguenza, anche se in un dispositivo non sono presenti dati da inviare, viene comunque inviato un messaggio vuoto da dispositivo a cloud, in genere con una proprietà che lo identifica come heartbeat. Sul lato servizio, la soluzione gestisce una mappa con l'ultimo heartbeat ricevuto per ogni dispositivo e presuppone che sia presente un problema con il dispositivo se non riceve un messaggio di heartbeat entro il tempo previsto.

Un'implementazione più complessa può includere le informazioni acquisite dal monitoraggio delle operazioni per identificare i dispositivi che provano a connettersi o a comunicare ma con esito negativo. Quando si implementa il modello di heartbeat, assicurarsi di controllare Quote e limitazioni dell'hub IoT.

Nota

Se una soluzione IoT usa lo stato di connessione esclusivamente per determinare se inviare i messaggi da cloud a dispositivo e i messaggi non vengono trasmessi a grandi set di dispositivi, è da considerare l'uso del criterio a breve scadenza più semplice. Un modello di questo tipo consente di gestire il registro dello stato di connessione del dispositivo in modo analogo a un modello di heartbeat, ma con maggiore efficienza. Se si richiede l'acknowledgement dei messaggi, l'hub IoT può inviare una notifica per indicare quali dispositivi possono ricevere messaggi e quali no.

Notifiche del ciclo di vita dei dispositivi

L'hub IoT può inviare una notifica alla soluzione IoT quando un'identità dispositivo viene creata o eliminata inviando notifiche del ciclo di vita dei dispositivi. A questo scopo, la soluzione IoT deve creare una route e impostare l'origine dati su DeviceLifecycleEvents. Per impostazione predefinita, non vengono inviate notifiche del ciclo di vita, il che significa che queste route non sono preesistenti. Il messaggio di notifica include le proprietà e il corpo.

Proprietà: le proprietà di sistema del messaggio hanno come prefisso il simbolo '$'.

Nome Valore
$content-type application/json
$iothub-enqueuedtime Data e ora in cui è stata inviata la notifica
$iothub-message-source deviceLifecycleEvents
$content-encoding utf-8
opType createDeviceIdentity o deleteDeviceIdentity
hubName Nome dell'hub IoT
deviceId ID del dispositivo
operationTimestamp Timestamp ISO8601 dell'operazione
iothub-message-schema deviceLifecycleNotification

Corpo: questa sezione è in formato JSON e rappresenta la copia dell'identità dispositivo creata. Ad esempio,

{
    "deviceId":"11576-ailn-test-0-67333793211",
    "etag":"AAAAAAAAAAE=",
    "properties": {
        "desired": {
            "$metadata": {
                "$lastUpdated": "2016-02-30T16:24:48.789Z"
            },
            "$version": 1
        },
        "reported": {
            "$metadata": {
                "$lastUpdated": "2016-02-30T16:24:48.789Z"
            },
            "$version": 1
        }
    }
}

Argomenti di riferimento:

Gli argomenti di riferimento seguenti offrono altre informazioni sul registro delle identità.

Proprietà delle identità dei dispositivi

Le identità dei dispositivi vengono rappresentate da documenti JSON con le proprietà indicate di seguito.

Proprietà Opzioni Descrizione
deviceId Obbligatoria, di sola lettura negli aggiornamenti Stringa con distinzione tra maiuscole e minuscole (con lunghezza massima di 128 caratteri) di caratteri alfanumerici ASCII a 7 bit + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}.
generationId Obbligatoria, di sola lettura Stringa con distinzione tra maiuscole/minuscole generata dall'hub IoT con lunghezza massima di 128 caratteri. Tale valore viene usato per distinguere i dispositivi con la stessa proprietà deviceId in caso di eliminazione e nuova creazione.
etag Obbligatoria, di sola lettura Stringa che rappresenta un ETag vulnerabile per l'identità del dispositivo, come indicato in RFC7232.
auth Facoltativa Oggetto composito contenente le informazioni di autenticazione e i materiali di sicurezza.
auth.symkey Facoltativa Oggetto composito contenente una chiave primaria e una chiave secondaria, archiviate in formato Base 64.
status Obbligatoria Indicatore di accesso. Può essere Enabled o Disabled. Se è Enabled, il dispositivo sarà autorizzato alla connessione. Se è Disabled, il dispositivo non potrà accedere ad alcun endpoint per il dispositivo.
statusReason Facoltativa Stringa con 128 caratteri di lunghezza che memorizza il motivo dello stato dell'identità del dispositivo. Sono consentiti tutti i caratteri UTF-8.
statusUpdateTime Sola lettura Indicatore temporale che mostra la data e l'ora dell'ultimo aggiornamento dello stato.
connectionState Sola lettura Campo indicante lo stato della connessione: Connected o Disconnected. Questo campo rappresenta la visualizzazione Hub IoT dello stato di connessione del dispositivo. Importante: è consigliabile usare questo campo solo per scopi di sviluppo e di debug. Lo stato di connessione viene aggiornato solo per i dispositivi che usano MQTT o AMQP. Si basa anche su ping a livello di protocollo (ping MQTT o AMQP) e può avere un ritardo massimo di soli 5 minuti. Per questi motivi possono essere presenti falsi positivi, ad esempio dispositivi segnalati come connessi, ma in realtà disconnessi.
connectionStateUpdatedTime Sola lettura Indicatore temporale che mostra la data e l'ora dell'ultimo aggiornamento dello stato della connessione.
lastActivityTime Sola lettura Indicatore temporale che mostra la data e l'ora in cui il dispositivo si è connesso oppure ha ricevuto o inviato un messaggio per l'ultima volta.
Nota

Lo stato della connessione può rappresentare solo la visualizzazione Hub IoT dello stato della connessione. Gli aggiornamenti dello stato possono essere ritardati a seconda delle condizioni e delle configurazioni della rete.

Materiale di riferimento

Di seguito sono indicati altri argomenti di riferimento reperibili nella Guida per gli sviluppatori dell'hub IoT:

Passaggi successivi

Ora che si è appreso come usare il registro delle identità dell'hub IoT, si potrebbe essere interessati agli argomenti seguenti della Guida per gli sviluppatori dell'hub IoT:

Per provare alcuni dei concetti descritti in questo articolo, può essere utile l'esercitazione seguente sull'hub IoT: