Configurare un'istanza e l'autenticazione di Gemelli digitali di Azure
Questo articolo illustra i passaggi per configurare una nuova istanza di Gemelli digitali di Azure, inclusa la creazione dell'istanza e la configurazione dell'autenticazione. Dopo aver completato questo articolo, si avrà un'istanza di Gemelli digitali di Azure pronta per iniziare a eseguire la programmazione.
La configurazione completa per una nuova istanza di Gemelli digitali di Azure è costituita da due parti:
- Creazione dell'istanza
- Configurazione delle autorizzazioni di accesso utente: gli utenti di Azure devono avere il ruolo proprietario dei dati di Gemelli digitali di Azure nell'istanza di Gemelli digitali di Azure per poterli gestire e i relativi dati. In questo passaggio, l'utente come proprietario/amministratore della sottoscrizione di Azure assegnerà questo ruolo alla persona che gestirà l'istanza di Gemelli digitali di Azure. Può trattarsi di se stessi o di un altro utente dell'organizzazione.
Importante
Per completare questo articolo e configurare completamente un'istanza utilizzabile, sono necessarie le autorizzazioni per gestire sia le risorse che l'accesso degli utenti nella sottoscrizione di Azure. Il primo passaggio può essere completato da chiunque sia in grado di creare risorse nella sottoscrizione, ma il secondo passaggio richiede autorizzazioni di gestione degli accessi utente (o la collaborazione di un utente con queste autorizzazioni). Per altre informazioni, vedere la sezione Prerequisiti: Autorizzazioni necessarie per il passaggio di autorizzazione di accesso utente.
Prerequisiti
Usare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere Avvio rapido su Bash in Azure Cloud Shell.
Se si preferisce eseguire i comandi di riferimento dell'interfaccia della riga di comando in locale, installare l'interfaccia della riga di comando di Azure. Per l'esecuzione in Windows o macOS, è consigliabile eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker. Per altre informazioni, vedere Come eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker.
Se si usa un'installazione locale, accedere all'interfaccia della riga di comando di Azure con il comando az login. Per completare il processo di autenticazione, seguire la procedura visualizzata nel terminale. Per altre opzioni di accesso, vedere Accedere tramite l'interfaccia della riga di comando di Azure.
Quando richiesto, al primo utilizzo installare l'estensione dell'interfaccia della riga di comando di Azure. Per altre informazioni sulle estensioni, vedere Usare le estensioni con l'interfaccia della riga di comando di Azure.
Eseguire az version per trovare la versione e le librerie dipendenti installate. Per eseguire l'aggiornamento alla versione più recente, eseguire az upgrade.
Configurare la sessione dell'interfaccia della riga di comando
Per iniziare a usare Gemelli digitali di Azure nell'interfaccia della riga di comando, è prima di tutto necessario accedere e impostare il contesto dell'interfaccia della riga di comando sulla sottoscrizione per questa sessione. Eseguire questi comandi nella finestra Interfaccia della riga di comando:
az login
az account set --subscription "<your-Azure-subscription-ID>"
Suggerimento
Nel comando riportato sopra si può anche usare il nome della sottoscrizione invece dell'ID.
Se è la prima volta che si usa questa sottoscrizione con Gemelli digitali di Azure, eseguire questo comando per registrarsi con lo spazio dei nomi di Gemelli digitali di Azure. In caso di dubbi, è possibile eseguirlo di nuovo anche se è stato già completato nel passato.
az provider register --namespace 'Microsoft.DigitalTwins'
A questo punto, si aggiungerà l'estensione Microsoft Azure IoT per l'interfaccia della riga di comando di Azure, per abilitare i comandi per l'interazione con Gemelli digitali di Azure e altri servizi IoT. Eseguire questo comando per assicurarsi di avere la versione più recente dell'estensione:
az extension add --upgrade --name azure-iot
A questo punto si è pronti per usare Gemelli digitali di Azure nell’interfaccia della riga di comando di Azure.
Per verificarlo, è possibile eseguire az dt --help in qualsiasi momento per visualizzare un elenco dei comandi di Gemelli digitali di Azure di primo livello disponibili.
Creare l'istanza di Gemelli digitali di Azure
In questa sezione si creerà una nuova istanza di Gemelli digitali di Azure usando il comando dell'interfaccia della riga di comando. Sarà necessario fornire:
- Gruppo di risorse in cui verrà distribuita l'istanza. Se non si ha già un gruppo di risorse esistente, è possibile crearne uno con questo comando:
az group create --location <region> --name <name-for-your-resource-group> - Area per la distribuzione. Per informazioni sulle aree che supportano Gemelli digitali di Azure, vedere Prodotti Di Azure disponibili in base all'area.
- Nome dell'istanza. Se la sottoscrizione ha un'altra istanza di Gemelli digitali di Azure nell'area che usa già il nome specificato, verrà chiesto di selezionare un nome diverso.
Usare questi valori nel comando az dt seguente per creare l'istanza:
az dt create --dt-name <name-for-your-Azure-Digital-Twins-instance> --resource-group <your-resource-group> --location <region>
Sono disponibili diversi parametri facoltativi che possono essere aggiunti al comando per specificare elementi aggiuntivi sulla risorsa durante la creazione, inclusa la creazione di un'identità gestita per l'istanza o l'abilitazione/disabilitazione dell'accesso alla rete pubblica. Per un elenco completo dei parametri supportati, vedere la documentazione di riferimento az dt create .
Creare l'istanza con un'identità gestita
Quando si abilita un'identità gestita nell'istanza di Gemelli digitali di Azure, viene creata un'identità in Microsoft Entra ID. Tale identità può quindi essere usata per eseguire l'autenticazione ad altri servizi. È possibile abilitare un'identità gestita per un'istanza di Gemelli digitali di Azure durante la creazione dell'istanza o successiva in un'istanza esistente.
Usare il comando dell'interfaccia della riga di comando seguente per il tipo scelto di identità gestita.
Comando identità assegnato dal sistema
Per creare un'istanza di Gemelli digitali di Azure con identità assegnata dal sistema abilitata, è possibile aggiungere un --mi-system-assigned parametro al az dt create comando usato per creare l'istanza. Per altre informazioni sul comando di creazione, vedere la relativa documentazione di riferimento o le istruzioni generali per la configurazione di un'istanza di Gemelli digitali di Azure.
Per creare un'istanza con un'identità assegnata dal sistema, aggiungere il --mi-system-assigned parametro come segue:
az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-system-assigned
Comando identità assegnato dall'utente
Per creare un'istanza con un'identità assegnata dall'utente, specificare l'ID di un'identità assegnata dall'utente esistente usando il --mi-user-assigned parametro , come illustrato di seguito:
az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-user-assigned <user-assigned-identity-resource-ID>
Verificare l'esito positivo e raccogliere valori importanti
Se l'istanza è stata creata correttamente, il risultato nell'interfaccia della riga di comando è simile al seguente, che restituisce informazioni sulla risorsa creata:
Prendere nota del nome host, del nome e del gruppo di risorse dell'istanza di Gemelli digitali di Azure dall'output. Questi valori sono tutti importanti e potrebbe essere necessario usarli mentre si continua a usare l'istanza di Gemelli digitali di Azure per configurare l'autenticazione e le risorse di Azure correlate. Se altri utenti eseguiranno la programmazione rispetto all'istanza, è necessario condividere questi valori con essi.
Suggerimento
È possibile visualizzare queste proprietà, insieme a tutte le proprietà dell'istanza, in qualsiasi momento eseguendo az dt show --dt-name <your-Azure-Digital-Twins-instance>.
È ora disponibile un'istanza di Gemelli digitali di Azure pronta per l'uso. Successivamente, si concedono le autorizzazioni utente di Azure appropriate per gestirlo.
Configurare le autorizzazioni di accesso utente
Gemelli digitali di Azure usa l'ID Microsoft Entra per il controllo degli accessi in base al ruolo. Ciò significa che prima che un utente possa effettuare chiamate del piano dati all'istanza di Gemelli digitali di Azure, all'utente deve essere assegnato un ruolo con le autorizzazioni appropriate.
Per Gemelli digitali di Azure, questo ruolo è Proprietario dei dati di Gemelli digitali di Azure. Per altre informazioni sui ruoli e la sicurezza, vedere Sicurezza per le soluzioni di Gemelli digitali di Azure.
Nota
Questo ruolo è diverso dal ruolo Proprietario di Microsoft Entra ID, che può essere assegnato anche nell'ambito dell'istanza di Gemelli digitali di Azure. Si tratta di due ruoli di gestione distinti e il proprietario non concede l'accesso alle funzionalità del piano dati concesse con proprietario dei dati di Gemelli digitali di Azure.
Questa sezione illustra come creare un'assegnazione di ruolo per un utente nell'istanza di Gemelli digitali di Azure usando il messaggio di posta elettronica dell'utente nel tenant di Microsoft Entra nella sottoscrizione di Azure. A seconda del ruolo dell'organizzazione, è possibile configurare questa autorizzazione per se stessi o configurarla per conto di un altro utente che gestirà l'istanza di Gemelli digitali di Azure.
Prerequisiti: requisiti di autorizzazione
Per poter completare tutti i passaggi seguenti, è necessario avere un ruolo nella sottoscrizione con le autorizzazioni seguenti:
- Creare e gestire le risorse di Azure
- Gestire l'accesso degli utenti alle risorse di Azure (inclusa la concessione e la delega delle autorizzazioni)
I ruoli comuni che soddisfano questo requisito sono proprietario, amministratore account o la combinazione di amministratore accesso utenti e collaboratore. Per una spiegazione completa dei ruoli e delle autorizzazioni, incluse le autorizzazioni incluse in altri ruoli, vedere Ruoli di Azure, ruoli di Microsoft Entra e ruoli di amministratore della sottoscrizione classica nella documentazione di Controllo degli accessi in base al ruolo di Azure.
Per visualizzare il ruolo nella sottoscrizione, visitare la pagina delle sottoscrizioni nel portale di Azure (è possibile usare questo collegamento o cercare Sottoscrizioni con la barra di ricerca del portale). Cercare il nome della sottoscrizione in uso e visualizzare il ruolo nella colonna Ruolo personale:
Se si scopre che il valore è Collaboratore o un altro ruolo che non dispone delle autorizzazioni necessarie descritte in precedenza, è possibile contattare l'utente nella sottoscrizione che dispone di queste autorizzazioni (ad esempio proprietario della sottoscrizione o amministratore account) e procedere in uno dei modi seguenti:
- Richiedere di completare i passaggi di assegnazione dei ruoli per conto dell'utente.
- Richiedere di elevare il ruolo nella sottoscrizione in modo che si disponga delle autorizzazioni necessarie per procedere autonomamente. La scelta appropriata dipende dall'organizzazione e dal ruolo al suo interno.
Assegnare il ruolo
Per concedere a un utente l'autorizzazione per gestire un'istanza di Gemelli digitali di Azure, è necessario assegnargli il ruolo Proprietario dati di Gemelli digitali di Azure all'interno dell'istanza.
Usare il comando seguente per assegnare il ruolo (deve essere eseguito da un utente con autorizzazioni sufficienti nella sottoscrizione di Azure). Il comando richiede di passare il nome dell'entità utente nell'account Microsoft Entra per l'utente a cui deve essere assegnato il ruolo. Nella maggior parte dei casi, questo valore corrisponderà al messaggio di posta elettronica dell'utente nell'account Microsoft Entra.
az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<Azure-AD-user-principal-name-of-user-to-assign>" --role "Azure Digital Twins Data Owner"
Il risultato di questo comando viene restituito informazioni sull'assegnazione di ruolo creata per l'utente.
Nota
Se questo comando restituisce un errore che indica che l'interfaccia della riga di comando non riesce a trovare l'utente o l'entità servizio nel database a grafo:
Assegnare invece il ruolo usando l'ID oggetto dell'utente. Questo problema può verificarsi per gli utenti con account Microsoft personali (ACCOUNT del servizio gestito) .
Usare la pagina portale di Azure degli utenti di Microsoft Entra per selezionare l'account utente e aprire i relativi dettagli. Copiare l'ID oggetto dell'utente:
Ripetere quindi il comando elenco di assegnazioni di ruolo usando l'ID oggetto dell'utente per il assignee parametro precedente.
Verificare l'esito positivo
Un modo per verificare che l'assegnazione di ruolo sia stata configurata correttamente consiste nel visualizzare le assegnazioni di ruolo per l'istanza di Gemelli digitali di Azure nel portale di Azure. Passare all'istanza di Gemelli digitali di Azure nel portale di Azure. Per arrivarci, è possibile cercarlo nella pagina delle istanze di Gemelli digitali di Azure o cercarne il nome nella barra di ricerca del portale.
Visualizzare quindi tutti i ruoli assegnati in Assegnazioni di ruolo di controllo di accesso (IAM>). L'assegnazione di ruolo dovrebbe essere visualizzata nell'elenco.
È ora disponibile un'istanza di Gemelli digitali di Azure pronta per l'uso e sono state assegnate le autorizzazioni per gestirla.
Abilitare/disabilitare l'identità gestita per l'istanza
Questa sezione illustra come aggiungere un'identità gestita a un'istanza di Gemelli digitali di Azure già esistente. È anche possibile disabilitare l'identità gestita in un'istanza che lo contiene già.
Usare i comandi dell'interfaccia della riga di comando seguenti per il tipo scelto di identità gestita.
Comandi di identità assegnati dal sistema
Il comando per abilitare un'identità assegnata dal sistema per un'istanza esistente è lo stesso az dt create comando usato per creare una nuova istanza con un'identità assegnata dal sistema. Anziché specificare un nuovo nome di un'istanza da creare, è possibile specificare il nome di un'istanza già esistente. Assicurarsi quindi di aggiungere il --mi-system-assigned parametro .
az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned
Per disabilitare l'identità assegnata dal sistema in un'istanza in cui è attualmente abilitata, usare il comando seguente per impostare su --mi-system-assigned false.
az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned false
Comandi di identità assegnati dall'utente
Per abilitare un'identità assegnata dall'utente in un'istanza esistente, specificare l'ID di un'identità assegnata dall'utente esistente nel comando seguente:
az dt identity assign --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>
Per disabilitare un'identità assegnata dall'utente in un'istanza in cui è attualmente abilitata, specificare l'ID dell'identità nel comando seguente:
az dt identity remove --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>
Considerazioni sulla disabilitazione delle identità gestite
È importante considerare gli effetti che le modifiche apportate all'identità o ai relativi ruoli possono avere sulle risorse che lo usano. Se si usano identità gestite con gli endpoint di Gemelli digitali di Azure o per cronologia dei dati e l'identità è disabilitata oppure viene rimosso un ruolo necessario, la connessione all'endpoint o alla cronologia dei dati può diventare inaccessibile e il flusso di eventi verrà interrotto.
Per continuare a usare un endpoint configurato con un'identità gestita che ora è stata disabilitata, è necessario eliminare l'endpoint e ricrearlo con un tipo di autenticazione diverso. Prima che gli eventi riprendano il processo di recapito all'endpoint dopo la modifica, potrebbe trascorrere fino a un'ora.
Passaggi successivi
Testare le singole chiamate API REST nell'istanza usando i comandi dell'interfaccia della riga di comando di Gemelli digitali di Azure:
In alternativa, vedere come connettere un'applicazione client all'istanza con il codice di autenticazione: