Condividi tramite

Comprendere il registro delle identità nell'hub IoT

  • Articolo

Ogni hub IoT ha un registro delle identità che archivia le informazioni sui dispositivi e i moduli autorizzati a 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 l'ID modulo archiviato nel registro delle identità rispettano la distinzione tra maiuscole e minuscole.

Il registro delle identità è una raccolta con supporto REST delle risorse di identità. 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à per:

  • Eseguire il provisioning dei dispositivi o dei moduli che si connettono all'hub IoT.
  • Controllare l'accesso per dispositivo/modulo agli endpoint dell'hub.

Operazioni del registro delle identità

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

  • Creare l'identità
  • Aggiornare l'identità
  • Recuperare l'identità in base all'ID
  • Eliminare l'identità
  • Elencare fino a 1.000 identità
  • Esportare 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 RFC 7232.

Un registro delle identità hub IoT non contiene metadati dell'applicazione.

Importante

Usare il registro delle identità solo per le operazioni di gestione e provisioning dei dispositivi. Le operazioni con velocità effettiva elevata in fase di esecuzione non devono dipendere dall'esecuzione di operazioni nel registro delle identità. Ad esempio, controllare lo stato di connessione di un dispositivo prima di inviare un comando non è un modello supportato. Assicurarsi di verificare le frequenze di limitazione per il registro delle identità.

Nota

Può richiedere alcuni secondi affinché un dispositivo o l'identità di un modulo siano disponibili per il recupero dopo la creazione. In caso di errori, è possibile ritentare l'operazione get delle identità del dispositivo o del modulo.

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 si ritiene che un dispositivo sia compromesso o non autorizzato per qualsiasi motivo.

    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 la sezione Disabilitare o eliminare un dispositivo in Creare e gestire le identità dei dispositivi.

Importare ed esportare le identità dei dispositivi

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

Usare operazioni asincrone sull'endpoint del provider di risorse dell'hub IoT per importare o esportare in blocco le identità dei dispositivi da un registro delle identità di un hub IoT. Le importazioni e le esportazioni sono processi a esecuzione prolungata che usano un contenitore BLOB fornito dal cliente.

Per altre informazioni sulle API di importazione ed esportazione, vedere Risorsa dell'hub IoT. Per altre informazioni sull'esecuzione di processi di importazione ed esportazione, vedere Importare ed esportare le identità dei dispositivi dell'hub IoT in blocco.

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 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. Il registro delle identità di hub IoT può 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 consentire a un nuovo dispositivo di connettersi all'hub, aggiungere un ID dispositivo e le chiavi al registro delle identità hub IoT. Come parte del processo di provisioning, può essere necessario inizializzare i dati specifici del dispositivo in altri archivi di soluzioni. È anche possibile usare il servizio Device Provisioning in hub IoT di Azure per abilitare il provisioning JIT senza tocco in uno o più hub IoT. Per altre informazioni, vedere La documentazione del servizio Device Provisioning in hub IoT di Azure.

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 un percorso e impostare l'origine dei dati su DeviceLifecycleEvents. Per impostazione predefinita, non vengono inviate notifiche sul ciclo di vita, cioè non esistono percorsi preesistenti. Quando si crea una route con origine dati uguale a DeviceLifecycleEvents, gli eventi del ciclo di vita vengono inviati sia per le identità dei dispositivi che per le identità dei moduli. Il contenuto del messaggio varia a seconda che gli eventi vengano generati per identità del modulo o identità del dispositivo. Per ulteriori informazioni sulle proprietà e sul contenuto restituito nel messaggio di notifica, consultare Schemi di eventi non di telemetria in Azure IoT Hub.

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à dell'identità del dispositivo

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: - . % _ * ? ! ( ) , : = @ $ '. I caratteri + # speciali non sono supportati.
generationId Obbligatoria, di sola lettura Stringa con distinzione tra maiuscole e minuscole generata da hub IoT fino a 128 caratteri. Questo valore viene usato per distinguere i dispositivi con lo stesso deviceId, quando vengono eliminati e ricreati.
etag Obbligatoria, di sola lettura Stringa che rappresenta un ETag debole per l'identità del dispositivo, in base a RFC 7232.
autenticazione facoltativo Oggetto composito contenente le informazioni di autenticazione e i materiali di sicurezza. Per altre informazioni, vedere AuthenticationMechanism nella documentazione dell'API REST.
capacità opzionale Set di funzionalità del dispositivo. Ad esempio, se il dispositivo è un dispositivo perimetrale o no. Per altre informazioni, vedere DeviceCapabilities nella documentazione dell'API REST.
deviceScope facoltativo Ambito del dispositivo. Nei dispositivi perimetrali, generati automaticamente e non modificabili. Deprecato nei dispositivi non installati. 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 la sezione Relazioni padre e figlio di Come usare un dispositivo IoT Edge come gateway.
parentScopes opzionale 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 installati la proprietà non è presente se il dispositivo non ha un elemento padre. Per altre informazioni, vedere la sezione Relazioni padre e figlio di Come usare un dispositivo IoT Edge come gateway.
status Obbligatorio Indicatore di accesso. Può essere Enabled o Disabled. Se Enabled, il dispositivo è autorizzato a connettersi. Se è Disabled, il dispositivo non potrà accedere ad alcun endpoint per il dispositivo.
statusReason opzionale 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.
stato di connessione Sola lettura Campo che indica 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 a questo stato potrebbero essere ritardati, a seconda delle condizioni e delle configurazioni di rete.

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: - . % _ * ? ! ( ) , : = @ $ '. I 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. Questo valore viene usato per distinguere i dispositivi con lo stesso deviceId, quando vengono eliminati e ricreati.
etag Obbligatoria, di sola lettura Stringa che rappresenta un ETag debole per l'identità del dispositivo, in base a RFC 7232.
autenticazione opzionale Oggetto composito contenente le informazioni di autenticazione e i materiali di sicurezza. Per altre informazioni, vedere AuthenticationMechanism nella documentazione dell'API REST.
managedBy facoltativo Identifica chi gestisce questo modulo. Ad esempio, questo valore è IoT Edge se il runtime edge è proprietario di questo modulo.
cloudToDeviceMessageCount Sola lettura Il numero di messaggi da cloud a modulo attualmente in coda per essere inviati al modulo.
connectionState Sola lettura Campo che indica 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.

Contenuto correlato

Per analizzare l'uso del servizio Device Provisioning dell'hub IoT per abilitare il provisioning automatico senza intervento umano, vedere: