Impostare un'istanza di Azure Digital Twins e l'autenticazione (CLI)

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, avrai un'istanza di Azure Digital Twins pronta per iniziare a programmare.

La configurazione completa per una nuova istanza di Gemelli digitali di Azure è costituita da due parti:

1. Creazione dell'istanza.
2. 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 assegna questo ruolo alla persona che gestisce l'istanza di Gemelli digitali di Azure. Questa persona potrebbe essere se stessa o un altro utente dell'organizzazione.

Prerequisiti

• Utilizzare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere Introduzione ad 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 Eseguire l'autenticazione ad Azure con l'interfaccia della riga di comando di Azure.

  • Quando ti viene richiesto, installa l'estensione CLI di Azure al primo utilizzo. Per altre informazioni sulle estensioni, vedere Usare e gestire 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. Esegui questi comandi nella finestra CLI.

az login
az account set --subscription "<your-Azure-subscription-ID>"

Se usi questa sottoscrizione con Azure Digital Twins per la prima volta, esegui il comando seguente per registrarti nello spazio dei nomi di Azure Digital Twins. Se non si è certi, è possibile eseguirlo di nuovo anche se è stato eseguito qualche volta in passato.

az provider register --namespace 'Microsoft.DigitalTwins'

Aggiungere quindi l'estensione Microsoft Azure IoT per l'interfaccia della riga di comando di Azure per abilitare i comandi per interagire 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 momento è possibile usare Gemelli digitali di Azure nell'interfaccia della riga di comando di Azure.

È possibile verificare questo stato eseguendo az dt --help in qualsiasi momento per visualizzare un elenco dei comandi principali di Gemelli digitali di Azure disponibili.

Creare l'istanza di Azure Digital Twins

In questa sezione viene creata una nuova istanza di Azure Digital Twins usando il comando CLI. È necessario fornire:

• Gruppo di risorse in cui viene 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 geografica 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 tua sottoscrizione ha un'altra istanza di Gemelli digitali di Azure nella stessa area che usa già il nome specificato, ti verrà chiesto di scegliere 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 altre informazioni 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 Azure Digital Twins, 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 seguente comando CLI per il tipo di identità gestita scelto.

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 di hostName, name e resourceGroup 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 programmano in base all'istanza di , è necessario condividere questi valori con essi.

È ora disponibile un'istanza di Azure Digital Twins pronta all'uso. Successivamente, si assegnano le autorizzazioni utente di Azure appropriate per gestirlo.

Configurare le autorizzazioni di accesso utente

Azure Digital Twins utilizza 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.

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 gestisce 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, tra cui 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 tuo ruolo nella tua sottoscrizione, visita la pagina delle Sottoscrizioni nel portale di Azure (è possibile utilizzare questo collegamento o cercare Sottoscrizioni con la barra di ricerca del portale). Cerca il nome della sottoscrizione che stai utilizzando e visualizza il tuo ruolo nella colonna Il mio ruolo.

Se 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.
• Chiedi loro di elevare il tuo ruolo all'interno della sottoscrizione in modo da disporre delle autorizzazioni necessarie per procedere autonomamente. Se questa richiesta è appropriata può dipendere 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. Un utente con autorizzazioni sufficienti nella sottoscrizione di Azure deve eseguire il comando . Il comando richiede di passare il nome principale utente nell'account Microsoft Entra per l'utente a cui deve essere assegnato il ruolo. Nella maggior parte dei casi, questo valore corrisponde 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 fornisce informazioni circa l'assegnazione di ruolo creata per l'utente.

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.

Vai alla tua istanza di Azure Digital Twins nel portale di Azure. Per raggiungerlo, è possibile cercarlo nella pagina delle istanze di Azure Digital Twins o digitare il suo nome nella barra di ricerca del portale.

Quindi, visualizza tutti i ruoli assegnati sotto Controllo accesso (IAM) > Assegnazione dei ruoli. 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à.

Utilizzare i seguenti comandi CLI 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, utilizzare il seguente comando per impostare --mi-system-assigned su 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 la 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 viene interrotto.

Per continuare a usare un endpoint configurato con un'identità gestita ora disabilitata, è necessario eliminare l'endpoint e ricrearlo con un tipo di autenticazione diverso. Il ripristino della consegna degli eventi all'endpoint dopo questa modifica potrebbe richiedere fino a un'ora.

Passaggi successivi

Testare le singole chiamate API REST nella tua istanza usando i comandi della CLI di Azure Digital Twins.

• riferimento al database di az
• Set di comandi CLI di Azure Digital Twins

In alternativa, vedere come connettere un'applicazione client all'istanza con il codice di autenticazione:

• Scrivere codice di autenticazione dell'app client