Comprendere il registro delle identità nell'hub IoT
A ogni hub IoT è associato un registro delle identità in cui sono archiviate le informazioni sui dispositivi e i moduli a cui è consentito connettersi all'hub IoT. Prima che un dispositivo o modulo possa connettersi a un hub IoT, è necessario che sia presente una voce relativa al dispositivo o al modulo nel registro delle identità dell'hub IoT. Un dispositivo o un modulo deve autenticarsi anche con l'hub IoT in base alle credenziali archiviate nel registro delle identità.
L'ID dispositivo o modulo archiviato nel registro delle identità rispetta la distinzione tra maiuscole e minuscole.
A livello generale, il registro delle identità è una raccolta di risorse relative alle identità dei dispositivi e dei moduli che supportano 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.
Usare il registro delle identità quando è necessario:
- Eseguire il provisioning dei dispositivi o dei moduli che si connettono all'hub IoT.
- Controllare l'accesso per dispositivo/per modulo agli endpoint collegati al dispositivo o modulo dell'hub.
Operazioni del registro delle identità
Il registro delle identità dell'hub IoT espone le operazioni seguenti:
- Creazione dell'identità del dispositivo o del modulo
- Aggiornamento dell'identità del dispositivo o del modulo
- Recupero dell'identità del dispositivo o del modulo tramite ID
- Eliminazione dell'identità del dispositivo o del modulo
- Elencare al massimo 1000 identità
- Esportare le identità del dispositivo in Archiviazione BLOB di Azure
- Importare le identità del dispositivo da 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.
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à.
Nota
La disponibilità di un dispositivo o di un'identità del modulo dopo la creazione può richiedere alcuni secondi. Riprovare l'operazione get delle identità del dispositivo o del modulo in caso di errori.
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 ritiene che un dispositivo sia compromesso o non più autorizzato.
Importante
L'hub IoT non controlla gli elenchi di revoche di certificati durante l'autenticazione dei dispositivi con autenticazione basata su certificato. Se si dispone di un dispositivo che deve essere bloccato dalla connessione all'hub IoT a causa di un certificato potenzialmente compromesso, è necessario disabilitare il dispositivo nel registro delle identità.
Questa funzionalità non è disponibile per i moduli.
Per altre informazioni, vedere Disabilitare o eliminare un dispositivo in un hub IoT.
Importare ed esportare le identità dei dispositivi
Usare operazioni asincrone sull'endpoint del provider di risorse dell'hub IoT per esportare in blocco le identità dei dispositivi da un registro delle identità di un 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à.
Usare operazioni asincrone sull'endpoint del provider di risorse dell'hub IoT per importare in blocco le identità dei dispositivi in un registro delle identità di un 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à.
Per altre informazioni sulle API di importazione e di esportazione, vedere IoT Hub resource provider REST APIs (API REST del provider di risorse dell'hub IoT). Per altre informazioni sull'esecuzione dei processi di importazione ed esportazione, vedere Gestione in blocco delle identità dei dispositivi dell'hub IoT.
Le identità dei dispositivi possono anche essere esportate e importate da un hub IoT usando l'API del servizio tramite l'API REST o uno degli SDK del servizio dell'hub IoT.
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 Azure Cosmos DB per archiviare altri dati 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. Inoltre, è possibile utilizzare il servizio Device Provisioning dell'hub IoT di Azure per abilitare il provisioning automatico JIT per uno o più hub IoT senza la necessità dell'intervento umano. Per altre informazioni, vedere la documentazione di servizio per il provisioning.
Notifiche per il ciclo di vita di dispositivi e moduli
L'hub IoT può inviare una notifica alla soluzione IoT quando un'identità dispositivo viene creata o eliminata inviando notifiche del ciclo di vita. 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. Creando una route con origine dati uguale a DeviceLifecycleEvents, gli eventi del ciclo di vita vengono inviati per identità del dispositivo e identità del modulo. Il contenuto del messaggio varia a seconda che gli eventi vengano generati per identità del modulo o identità del dispositivo. Per altre informazioni sulle proprietà e sul corpo restituito nel messaggio di notifica, vedere Schemi di eventi non di telemetria.
Le notifiche per la creazione dell'identità del modulo sono diverse per i moduli IoT Edge rispetto ad altri moduli. Per i moduli IoT Edge, la notifica di creazione viene inviata solo se il dispositivo IoT Edge corrispondente è in esecuzione. Per tutti gli altri moduli, le notifiche del ciclo di vita vengono inviate ogni volta che l'identità del modulo viene aggiornata sul lato hub IoT.
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/minuscole (lunghezza massima 128 caratteri) con caratteri alfanumerici ASCII a 7 bit più alcuni caratteri speciali: - . % _ * ? ! ( ) , : = @ $ '. Caratteri speciali: + # non sono supportati. |
| 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. |
| autenticazione | facoltative | Oggetto composito contenente le informazioni di autenticazione e i materiali di sicurezza. Per altre informazioni, vedere Meccanismo di autenticazione nella documentazione dell'API REST. |
| capabilities | facoltative | Set di funzionalità del dispositivo. Ad esempio, se il dispositivo è un dispositivo perimetrale o meno. Per altre informazioni, vedere Funzionalità del dispositivo nella documentazione dell'API REST. |
| deviceScope | facoltative | Ambito del dispositivo. Nei dispositivi perimetrali, generati automaticamente e non modificabili. Deprecato nei dispositivi non perimetrali. Tuttavia, nei dispositivi figlio (foglia) impostare questa proprietà sullo stesso valore della proprietà parentScopes (deviceScope del dispositivo padre) per garantire la compatibilità con le versioni precedenti dell'API. Per altre informazioni, vedere IoT Edge come gateway: Relazioni padre e figlio. |
| parentScopes | facoltative | Ambito dell'elemento padre diretto di un dispositivo figlio (il valore della proprietà deviceScope del dispositivo padre). Nei dispositivi perimetrali, il valore è vuoto se il dispositivo non ha un elemento padre. Nei dispositivi non perimetrali, la proprietà non è presente se il dispositivo non ha un elemento padre. Per altre informazioni, vedere IoT Edge come gateway: Relazioni padre e figlio. |
| stato | Obbligatorio | Indicatore di accesso. Può essere Enabled o Disabled. Se è Enabled, il dispositivo sarà autorizzato alla connessione. Se è Disabilitato, il dispositivo non potrà accedere ad alcun endpoint per il dispositivo. |
| statusReason | facoltative | 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 disconnessi segnalati come connessi. |
| 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. Questa proprietà è infine coerente, ma potrebbe essere ritardata fino a 5-10 minuti. Per questo motivo, non deve essere usato negli scenari di produzione. |
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.
Nota
Attualmente gli SDK del dispositivo non supportano l'uso dei caratteri + e # in deviceId.
Proprietà delle identità dei moduli
Le identità dei moduli vengono rappresentate da documenti JSON con le proprietà seguenti:
| Proprietà | Opzioni | Descrizione |
|---|---|---|
| deviceId | Obbligatoria, di sola lettura negli aggiornamenti | Stringa con distinzione tra maiuscole/minuscole (lunghezza massima 128 caratteri) con caratteri alfanumerici ASCII a 7 bit più alcuni caratteri speciali: - . + % _ # * ? ! ( ) , : = @ $ '. |
| moduleId | Obbligatoria, di sola lettura negli aggiornamenti | Stringa con distinzione tra maiuscole/minuscole (lunghezza massima 128 caratteri) con caratteri alfanumerici ASCII a 7 bit più alcuni caratteri speciali: - . + % _ # * ? ! ( ) , : = @ $ '. |
| 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. |
| autenticazione | facoltative | Oggetto composito contenente le informazioni di autenticazione e i materiali di sicurezza. Per altre informazioni, vedere Meccanismo di autenticazione nella documentazione dell'API REST. |
| managedBy | facoltative | Identifica chi gestisce questo modulo. Ad esempio, questo valore è "IoT Edge" se il runtime edge è proprietario di questo modulo. |
| cloudToDeviceMessageCount | sola lettura | Numero di messaggi da cloud a modulo attualmente in coda da inviare al modulo. |
| 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 disconnessi segnalati come connessi. |
| 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
Attualmente gli SDK del dispositivo non supportano l'uso dei caratteri + e # in deviceId e moduleId.
Materiale di riferimento
Di seguito sono indicati altri articoli di riferimento reperibili nella Guida per gli sviluppatori dell'hub IoT:
Endpoint dell'hub IoT illustra i diversi endpoint esposti da ogni hub IoT per operazioni della fase di esecuzione e di gestione.
Quote e limitazioni descrive le quote e i comportamenti di limitazione applicabili al servizio hub IoT.
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.
Linguaggio di query dell'hub IoT descrive il linguaggio di query che è possibile usare per recuperare informazioni dall'hub IoT sui dispositivi gemelli e sui processi.
Supporto di MQTT nell'hub IoT offre altre informazioni sul supporto dell'hub IoT per il protocollo MQTT.
Passaggi successivi
Ora che si è appreso come usare il registro delle identità dell'hub IoT, si potrebbe essere interessati agli articoli seguenti della Guida per gli sviluppatori dell'hub IoT:
Use device twins to synchronize state and configurations (Usare dispositivi gemelli per sincronizzare lo stato e le configurazioni)
Per analizzare l'uso del servizio Device Provisioning dell'hub IoT per abilitare il provisioning automatico senza intervento umano, vedere: