Comprendere il registro delle identità nell'hub IoTUnderstand the identity registry in your IoT hub

Ogni hub IoT ha un registro delle identità in cui sono archiviate le informazioni sui dispositivi a cui è consentito connettersi all'hub IoT.Every IoT hub has an identity registry that stores information about the devices permitted to connect to the IoT hub. 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.Before a device can connect to an IoT hub, there must be an entry for that device in the IoT hub's identity registry. Un dispositivo deve autenticarsi anche con l'hub IoT in base alle credenziali archiviate nel registro delle identità.A device must also authenticate with the IoT hub based on credentials stored in the identity registry.

L'ID dispositivo archiviato nel registro delle identità fa distinzione tra maiuscole e minuscole.The device ID stored in the identity registry is case-sensitive.

A livello generale, il registro delle identità è una raccolta delle risorse relative alle identità dei dispositivi che supporta REST.At a high level, the identity registry is a REST-capable collection of device identity resources. 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.When you add an entry in the identity registry, IoT Hub creates a set of per-device resources such as the queue that contains in-flight cloud-to-device messages.

Usare il registro delle identità quando è necessario:Use the identity registry when you need to:

  • Il provisioning dei dispositivi che si connettono per l'hub IoT.Provision devices that connect to your IoT hub.
  • Controllare l'accesso per dispositivo agli endpoint che usano dispositivi dell'hub.Control per-device access to your hub's device-facing endpoints.

Nota

Il registro delle identità non contiene metadati specifici delle applicazioni.The identity registry does not contain any application-specific metadata.

Operazioni del registro delle identitàIdentity registry operations

Il registro delle identità dell'hub IoT espone le operazioni seguenti:The IoT Hub identity registry exposes the following operations:

  • Creare l'identità del dispositivoCreate device identity
  • Aggiornare l'identità del dispositivoUpdate device identity
  • Recuperare l'identità del dispositivo tramite IDRetrieve device identity by ID
  • Eliminare l'identità del dispositivoDelete device identity
  • Elencare al massimo 1000 identitàList up to 1000 identities
  • Esportare tutte le identità nell'Archiviazione BLOB di AzureExport all identities to Azure blob storage
  • Importare le identità nell'Archiviazione BLOB di AzureImport identities from Azure blob storage

Tutte queste operazioni possono usare la concorrenza ottimistica, come specificato in RFC7232.All these operations can use optimistic concurrency, as specified 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.The only way to retrieve all identities in an IoT hub's identity registry is to use the Export functionality.

Un registro delle identità di un hub IoT:An IoT Hub identity registry:

  • Non contiene metadati delle applicazioni.Does not contain any application metadata.
  • È accessibile come un dizionario, usando il valore deviceId come chiave.Can be accessed like a dictionary, by using the deviceId as the key.
  • Non supporta le query espressive.Does not support expressive queries.

Una soluzione IoT include in genere un archivio separato specifico della soluzione che contiene metadati specifici dell'applicazione.An IoT solution typically has a separate solution-specific store that contains application-specific metadata. 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.For example, the solution-specific store in a smart building solution would record the room in which a temperature sensor is deployed.

Importante

Usare il registro delle identità solo per le operazioni di gestione e provisioning dei dispositivi.Only use the identity registry for device management and provisioning operations. Le operazioni a velocità effettiva elevata in fase di esecuzione non devono dipendere dall'esecuzione di operazioni nel registro delle identità.High throughput operations at run time should not depend on performing operations in the identity registry. Ad esempio, la verifica dello stato di connessione di un dispositivo prima dell'invio di un comando non è uno schema supportato.For example, checking the connection state of a device before sending a command is not a supported pattern. Assicurarsi di verificare le frequenze di limitazione per il registro delle identità dei dispositivi e il modello di heartbeat del dispositivo.Make sure to check the throttling rates for the identity registry, and the device heartbeat pattern.

Disabilitare i dispositiviDisable devices

È possibile disabilitare i dispositivi aggiornando la proprietà status di un'identità nel registro delle identità.You can disable devices by updating the status property of an identity in the identity registry. Questa proprietà viene in genere usata in due scenari:Typically, you use this property in two scenarios:

  • Durante un processo di orchestrazione di provisioning.During a provisioning orchestration process. Per altre informazioni, vedere Provisioning di dispositivi.For more information, see Device Provisioning.
  • Se per qualsiasi motivo si ritiene che un dispositivo sia compromesso o non più autorizzato.If, for any reason, you think a device is compromised or has become unauthorized.

Importare ed esportare le identità dei dispositiviImport and export device identities

È 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.You can export device identities in bulk from an IoT hub's identity registry by using asynchronous operations on the IoT Hub resource provider endpoint. 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à.Exports are long-running jobs that use a customer-supplied blob container to save device identity data read from the identity registry.

È 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.You can import device identities in bulk to an IoT hub's identity registry by using asynchronous operations on the IoT Hub resource provider endpoint. 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à.Imports are long-running jobs that use data in a customer-supplied blob container to write device identity data into the identity registry.

Per informazioni dettagliate sulle API di importazione e di esportazione, vedere IoT Hub resource provider REST APIs (API REST del provider di risorse dell'hub IoT).For detailed information about the import and export APIs, see IoT Hub resource provider REST APIs. Per altre informazioni sull'esecuzione dei processi di importazione ed esportazione, vedere Gestione in blocco delle identità dei dispositivi dell'hub IoT.To learn more about running import and export jobs, see Bulk management of IoT Hub device identities.

Provisioning di dispositiviDevice provisioning

I dati del dispositivo archiviati da una soluzione IoT dipendono dai requisiti specifici di tale soluzione.The device data that a given IoT solution stores depends on the specific requirements of that solution. Tuttavia, come minimo, una soluzione deve archiviare identità di dispositivo e chiavi di autenticazione.But, as a minimum, a solution must store device identities and authentication keys. 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.Azure IoT Hub includes an identity registry that can store values for each device such as IDs, authentication keys, and status codes. Una soluzione può usare altri servizi di Azure, ad esempio archiviazione tabelle, Archiviazione BLOB o Cosmos DB per archiviare dati aggiuntivi sui dispositivi.A solution can use other Azure services such as table storage, blob storage, or Cosmos DB to store any additional device data.

Provisioning di dispositivi è il processo di aggiunta dei dati iniziali dei dispositivi agli archivi nella soluzione.Device provisioning is the process of adding the initial device data to the stores in your solution. 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.To enable a new device to connect to your hub, you must add a device ID and keys to the IoT Hub identity registry. Come parte del processo di provisioning, può essere necessario inizializzare i dati specifici del dispositivo in altri archivi di soluzioni.As part of the provisioning process, you might need to initialize device-specific data in other solution stores.

Heartbeat dispositivoDevice heartbeat

Il registro delle identità dell'hub IoT contiene un campo denominato connectionState.The IoT Hub identity registry contains a field called connectionState. Durante le fasi di sviluppo e debug, usare solo il campo connectionState.Only use the connectionState field during development and debugging. Le soluzioni IoT non devono eseguire query sul campo in fase di esecuzione.IoT solutions should not query the field at run time. 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.For example, do not query the connectionState field to check if a device is connected before you send a cloud-to-device message or an SMS.

Se la soluzione IoT deve sapere se un dispositivo è connesso, è necessario implementare il modello di heartbeat.If your IoT solution needs to know if a device is connected, you should implement the heartbeat pattern.

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.In the heartbeat pattern, the device sends device-to-cloud messages at least once every fixed amount of time (for example, at least once every hour). 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.Therefore, even if a device does not have any data to send, it still sends an empty device-to-cloud message (usually with a property that identifies it as a heartbeat). Sul lato servizio, la soluzione gestisce una mappa con l'ultimo heartbeat ricevuto per ogni dispositivoOn the service side, the solution maintains a map with the last heartbeat received for each device. e presuppone che sia presente un problema con il dispositivo se non riceve un messaggio di heartbeat entro il tempo previsto.If the solution does not receive a heartbeat message within the expected time from the device, it assumes that there is a problem with the device.

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.A more complex implementation could include the information from operations monitoring to identify devices that are trying to connect or communicate but failing. Quando si implementa il modello di heartbeat, assicurarsi di controllare Quote e limitazioni dell'hub IoT.When you implement the heartbeat pattern, make sure to check IoT Hub Quotas and Throttles.

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.If an IoT solution uses the connection state solely to determine whether to send cloud-to-device messages, and messages are not broadcast to large sets of devices, consider using the simpler short expiry time pattern. 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.This pattern achieves the same result as maintaining a device connection state registry using the heartbeat pattern, while being more efficient. Se si richiede l'acknowledgement dei messaggi, l'hub IoT può inviare una notifica per indicare quali dispositivi possono ricevere messaggi e quali no.If you request message acknowledgements, IoT Hub can notify you about which devices are able to receive messages and which are not.

Notifiche del ciclo di vita dei dispositiviDevice lifecycle notifications

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.IoT Hub can notify your IoT solution when a device identity is created or deleted by sending device lifecycle notifications. A questo scopo, la soluzione IoT deve creare una route e impostare l'origine dati su DeviceLifecycleEvents.To do so, your IoT solution needs to create a route and to set the Data Source equal to DeviceLifecycleEvents. Per impostazione predefinita, non vengono inviate notifiche del ciclo di vita, il che significa che queste route non sono preesistenti.By default, no lifecycle notifications are sent, that is, no such routes pre-exist. Il messaggio di notifica include le proprietà e il corpo.The notification message includes properties, and body.

Proprietà: le proprietà di sistema del messaggio hanno come prefisso il simbolo '$'.Properties: Message system properties are prefixed with the '$' symbol.

NomeName ValoreValue
$content-type$content-type application/jsonapplication/json
$iothub-enqueuedtime$iothub-enqueuedtime Data e ora in cui è stata inviata la notificaTime when the notification was sent
$iothub-message-source$iothub-message-source deviceLifecycleEventsdeviceLifecycleEvents
$content-encoding$content-encoding utf-8utf-8
opTypeopType createDeviceIdentity o deleteDeviceIdentitycreateDeviceIdentity or deleteDeviceIdentity
hubNamehubName Nome dell'hub IoTName of IoT Hub
deviceIddeviceId ID del dispositivoID of the device
operationTimestampoperationTimestamp Timestamp ISO8601 dell'operazioneISO8601 timestamp of operation
iothub-message-schemaiothub-message-schema deviceLifecycleNotificationdeviceLifecycleNotification

Corpo: questa sezione è in formato JSON e rappresenta la copia dell'identità dispositivo creata.Body: This section is in JSON format and represents the twin of the created device identity. Ad esempio,For example,

{
    "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
        }
    }
}

Proprietà delle identità dei dispositiviDevice identity properties

Le identità dei dispositivi vengono rappresentate da documenti JSON con le proprietà indicate di seguito.Device identities are represented as JSON documents with the following properties:

ProprietàProperty OpzioniOptions DescrizioneDescription
deviceIddeviceId Obbligatoria, di sola lettura negli aggiornamentirequired, read-only on updates Stringa con distinzione tra maiuscole/minuscole (lunghezza massima 128 caratteri) con caratteri alfanumerici ASCII a 7 bit più alcuni caratteri speciali: - : . + % _ # * ? ! ( ) , = @ ; $ '.A case-sensitive string (up to 128 characters long) of ASCII 7-bit alphanumeric characters plus certain special characters: - : . + % _ # * ? ! ( ) , = @ ; $ '.
generationIdgenerationId Obbligatoria, di sola letturarequired, read-only Stringa con distinzione tra maiuscole/minuscole generata dall'hub IoT con lunghezza massima di 128 caratteri.An IoT hub-generated, case-sensitive string up to 128 characters long. Tale valore viene usato per distinguere i dispositivi con la stessa proprietà deviceId in caso di eliminazione e nuova creazione.This value is used to distinguish devices with the same deviceId, when they have been deleted and re-created.
etagetag Obbligatoria, di sola letturarequired, read-only Stringa che rappresenta un ETag vulnerabile per l'identità del dispositivo, come indicato in RFC7232.A string representing a weak ETag for the device identity, as per RFC7232.
authauth Facoltativaoptional Oggetto composito contenente le informazioni di autenticazione e i materiali di sicurezza.A composite object containing authentication information and security materials.
auth.symkeyauth.symkey Facoltativaoptional Oggetto composito contenente una chiave primaria e una chiave secondaria, archiviate in formato Base 64.A composite object containing a primary and a secondary key, stored in base64 format.
statusstatus Obbligatoriarequired Indicatore di accesso.An access indicator. Può essere Enabled o Disabled.Can be Enabled or Disabled. Se è Enabled, il dispositivo sarà autorizzato alla connessione.If Enabled, the device is allowed to connect. Se è Disabled, il dispositivo non potrà accedere ad alcun endpoint per il dispositivo.If Disabled, this device cannot access any device-facing endpoint.
statusReasonstatusReason Facoltativaoptional Stringa con 128 caratteri di lunghezza che memorizza il motivo dello stato dell'identità del dispositivo.A 128 character-long string that stores the reason for the device identity status. Sono consentiti tutti i caratteri UTF-8.All UTF-8 characters are allowed.
statusUpdateTimestatusUpdateTime Sola letturaread-only Indicatore temporale che mostra la data e l'ora dell'ultimo aggiornamento dello stato.A temporal indicator, showing the date and time of the last status update.
connectionStateconnectionState Sola letturaread-only Campo indicante lo stato della connessione: Connected o Disconnected.A field indicating connection status: either Connected or Disconnected. Questo campo rappresenta la visualizzazione Hub IoT dello stato di connessione del dispositivo.This field represents the IoT Hub view of the device connection status. Importante: è consigliabile usare questo campo solo per scopi di sviluppo e di debug.Important: This field should be used only for development/debugging purposes. Lo stato di connessione viene aggiornato solo per i dispositivi che usano MQTT o AMQP.The connection state is updated only for devices using MQTT or AMQP. Si basa anche su ping a livello di protocollo (ping MQTT o AMQP) e può avere un ritardo massimo di soli 5 minuti.Also, it is based on protocol-level pings (MQTT pings, or AMQP pings), and it can have a maximum delay of only 5 minutes. Per questi motivi possono essere presenti falsi positivi, ad esempio dispositivi segnalati come connessi, ma in realtà disconnessi.For these reasons, there can be false positives, such as devices reported as connected but that are disconnected.
connectionStateUpdatedTimeconnectionStateUpdatedTime Sola letturaread-only Indicatore temporale che mostra la data e l'ora dell'ultimo aggiornamento dello stato della connessione.A temporal indicator, showing the date and last time the connection state was updated.
lastActivityTimelastActivityTime Sola letturaread-only 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.A temporal indicator, showing the date and last time the device connected, received, or sent a message.

Nota

Lo stato della connessione può rappresentare solo la visualizzazione Hub IoT dello stato della connessione.Connection state can only represent the IoT Hub view of the status of the connection. Gli aggiornamenti dello stato possono essere ritardati a seconda delle condizioni e delle configurazioni della rete.Updates to this state may be delayed, depending on network conditions and configurations.

Materiale di riferimentoAdditional reference material

Di seguito sono indicati altri argomenti di riferimento reperibili nella Guida per gli sviluppatori dell'hub IoT:Other reference topics in the IoT Hub developer guide include:

  • Endpoint dell'hub IoT illustra i diversi endpoint esposti da ogni hub IoT per operazioni della fase di esecuzione e di gestione.IoT Hub endpoints describes the various endpoints that each IoT hub exposes for run-time and management operations.
  • Quote e limitazioni descrive le quote e i comportamenti di limitazione applicabili al servizio hub IoT.Throttling and quotas describes the quotas and throttling behaviors that apply to the IoT Hub service.
  • 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.Azure IoT device and service SDKs lists the various language SDKs you can use when you develop both device and service apps that interact with IoT Hub.
  • 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.IoT Hub query language describes the query language you can use to retrieve information from IoT Hub about your device twins and jobs.
  • Supporto di MQTT nell'hub IoT offre altre informazioni sul supporto dell'hub IoT per il protocollo MQTT.IoT Hub MQTT support provides more information about IoT Hub support for the MQTT protocol.

Passaggi successiviNext steps

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:Now that you have learned how to use the IoT Hub identity registry, you may be interested in the following IoT Hub developer guide topics:

Per provare alcuni dei concetti descritti in questo articolo, può essere utile l'esercitazione seguente sull'hub IoT:If you would like to try out some of the concepts described in this article, you may be interested in the following IoT Hub tutorial: