Esercitazione: Creare un grafo di Gemelli digitali di Azure usando un'app client di esempio

Articolo
01/03/2024

In questa esercitazione si creerà un grafo in Gemelli digitali di Azure usando modelli, gemelli e relazioni. Lo strumento per questa esercitazione è l'applicazione client della riga di comando di esempio per interagire con un'istanza di Gemelli digitali di Azure. L'app client è simile a quella scritta in Codice di un'app client.

È possibile usare questo esempio per eseguire azioni essenziali di Gemelli digitali di Azure, ad esempio il caricamento di modelli, la creazione e la modifica di gemelli e la creazione di relazioni. È anche possibile esaminare il codice dell'esempio per informazioni sulle API di Gemelli digitali di Azure e praticare l'implementazione di comandi personalizzati modificando il progetto di esempio desiderato.

In questa esercitazione si apprenderà come:

Modellare un ambiente
Creare i gemelli digitali
Aggiungere relazioni per formare un grafo
Eseguire una query sul grafico per rispondere alle domande

Prerequisiti

Prima di iniziare questa esercitazione, iniziare con questi prerequisiti:

Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.
Questa esercitazione usa .NET. È possibile scaricare la versione più recente di .NET SDK per più piattaforme da Scaricare .NET.

Continuare quindi con il resto di questa sezione per configurare i prerequisiti rimanenti.

Ottenere risorse di esempio

L'esercitazione è basata su un progetto end-to-end di Gemelli digitali di Azure scritto in C#. Ottenere il progetto di esempio nel computer passando al collegamento di esempio e selezionando il pulsante Sfoglia codice sotto il titolo.

Verrà visualizzato il repository GitHub per gli esempi, che è possibile scaricare come file ZIP selezionando il pulsante Codice seguito da Scarica ZIP.

Verrà scaricata una cartella zip nel computer come digital-twins-samples-main.zip. Decomprimere la cartella ed estrarre i file.

Preparare un'istanza di Gemelli digitali di Azure

Per usare Gemelli digitali di Azure in questo articolo, è necessaria un'istanza di Gemelli digitali di Azure e le autorizzazioni necessarie per usarlo. Se è già stata configurata un'istanza di Gemelli digitali di Azure, è possibile usare tale istanza e passare alla sezione successiva. In caso contrario, seguire le istruzioni riportate in Configurare un'istanza e l'autenticazione. Le istruzioni contengono informazioni che consentono di verificare che ogni passaggio sia stato completato correttamente.

Dopo aver configurato l'istanza, prendere nota del nome host dell'istanza. È possibile trovare il nome host nella portale di Azure.

Configurare il progetto di esempio

Configurare quindi un'applicazione client di esempio che interagirà con l'istanza di Gemelli digitali di Azure.

Passare alla cartella scaricata in precedenza dagli esempi end-to-end di Gemelli digitali di Azure e decomprimerla se non è già stato fatto.

Una volta all'interno della cartella, passare a digital-twins-samples-main\AdtSampleApp\SampleClientApp e aprire il file appsettings.json . Questo file JSON contiene una variabile di configurazione necessaria per eseguire il progetto.

Nel corpo del file passare all'URL instanceUrl del nome host dell'istanza di Gemelli digitali di Azure aggiungendo https:// davanti al nome host, come illustrato di seguito.

{
  "instanceUrl": "https://<your-Azure-Digital-Twins-instance-host-name>"
}

Salva e chiude il file.

Configurare le credenziali di Azure locali

Questo esempio usa DefaultAzureCredential (parte della libreria Azure.Identity) per l'autenticazione degli utenti con l'istanza di Gemelli digitali di Azure eseguita nel computer locale. Per altre informazioni sui diversi modi con cui un'app client può eseguire l'autenticazione con Gemelli digitali di Azure, vedere Scrivere il codice di autenticazione dell'app.

Con DefaultAzureCredential, l'esempio cercherà le credenziali nell'ambiente locale, ad esempio un account di accesso di Azure nell'interfaccia della riga di comando di Azure locale o in Visual Studio o Visual Studio Code. Per questo motivo è necessario accedere ad Azure in locale tramite uno di questi meccanismi per configurare le credenziali per l'esempio.

Se si usa Visual Studio o Visual Studio Code per eseguire esempi di codice, assicurarsi di aver eseguito l'accesso a tale editor con le stesse credenziali di Azure da usare per accedere all'istanza di Gemelli digitali di Azure. Se si usa una finestra dell'interfaccia della riga di comando locale, eseguire il az login comando per accedere all'account Azure. In seguito, quando si esegue l'esempio di codice, si dovrebbe essere autenticati automaticamente.

Eseguire il progetto di esempio

Ora che l'app e l'autenticazione sono configurate, aprire una finestra della console locale che verrà usata per eseguire il progetto. Passare nella console alla cartella digital-twins-samples-main\AdtSampleApp\SampleClientApp ed eseguire il progetto con questo comando dotnet:

dotnet run

Il progetto inizierà l'esecuzione, eseguirà l'autenticazione e attenderà un comando.

Ecco uno screenshot dell'aspetto della console del progetto:

Suggerimento

Per un elenco di tutti i comandi che è possibile usare con questo progetto, immettere help nella console del progetto e premere INVIO.

Dopo aver confermato che l'app è in esecuzione correttamente, è possibile interrompere l'esecuzione del progetto. Verrà eseguito di nuovo più avanti nell'esercitazione.

Modellare un ambiente fisico con DTDL

Ora che l'istanza di Gemelli digitali di Azure e l'app di esempio sono configurate, è possibile iniziare a creare un grafico di uno scenario.

Il primo passaggio per la creazione di una soluzione di Gemelli digitali di Azure consiste nel definire i modelli gemelli per l'ambiente.

I modelli sono simili alle classi nei linguaggi di programmazione orientati agli oggetti; sono modelli definiti dall'utente di cui è possibile creare un'istanza per creare gemelli digitali. I modelli per Gemelli digitali di Azure vengono scritti in un linguaggio simile a JSON denominato DTDL (Digital Twins Definition Language) e definiscono un tipo di gemello in termini di proprietà, relazioni e componenti.

Nota

DTDL consente anche di definire comandi nei gemelli digitali. Tuttavia, i comandi non sono attualmente supportati nel servizio Gemelli digitali di Azure.

Nella cartella del progetto di esempio scaricata in precedenza passare alla cartella digital-twins-samples-main\AdtSampleApp\SampleClientApp\Models . Questa cartella contiene modelli di esempio.

Aprire Room.json per la modifica e apportare le modifiche seguenti al codice:

Aggiornare il numero di versione per indicare che si specifica una versione più aggiornata di questo modello. A tale scopo, sostituire 1 alla fine del valore @id con 2. È anche possibile inserire qualsiasi numero maggiore del numero di versione corrente.
Modificare una proprietà. Modificare il nome della Humidity proprietà in HumidityLevel (o qualcosa di diverso se si desidera. Se si usa qualcosa di diverso da HumidityLevel, tenere presente ciò che è stato usato e continuare a usarlo invece di HumidityLevel durante l'esercitazione.
Aggiungere una proprietà. Sotto la proprietà HumidityLevel che termina alla riga 15 incollare il codice seguente per aggiungere una proprietà RoomName alla stanza:
```
,{
  "@type": "Property",
  "name": "RoomName",
  "schema": "string"
}
```
Aggiungere una relazione. Sotto la RoomName proprietà appena aggiunta, incollare il codice seguente per aggiungere la possibilità per questo tipo di gemello di formare contains relazioni con altri gemelli:
```
,{
  "@type": "Relationship",
  "name": "contains"
}
```

Al termine, il modello aggiornato sarà simile al seguente:

{
    "@id": "dtmi:example:Room;2",
    "@type": "Interface",
    "displayName": "Room",
    "contents": [
      {
        "@type": "Property",
        "name": "Temperature",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "HumidityLevel",
        "schema": "double"
      }
      ,{
        "@type": "Property",
        "name": "RoomName",
        "schema": "string"
      }
      ,{
        "@type": "Relationship",
        "name": "contains"
      }
    ],
    "@context": "dtmi:dtdl:context;3"
  }

Assicurarsi di salvare il file prima di procedere.

Caricare modelli in Gemelli digitali di Azure

Dopo aver progettato i modelli, è necessario caricarli nell'istanza di Gemelli digitali di Azure. In questo modo viene configurata l'istanza del servizio Gemelli digitali di Azure con un vocabolario di dominio personalizzato. Dopo aver caricato i modelli, è possibile creare istanze di gemelli che le usano.

Tornare alla finestra della console aperta alla cartella digital-twins-samples-main\AdtSampleApp\SampleClientApp ed eseguire di nuovo l'app console con dotnet run.
Nella finestra della console del progetto eseguire il comando seguente per caricare il modello Room aggiornato insieme a un modello Floor che verrà usato anche nella sezione successiva per creare diversi tipi di gemelli.
```
CreateModels Room Floor
```
L'output dovrebbe indicare che i modelli sono stati creati correttamente.
Verificare se i modelli sono stati creati eseguendo il comando GetModels true. Questo comando stampa le informazioni complete per tutti i modelli caricati nell'istanza di Gemelli digitali di Azure. Cercare il modello Room modificato nei risultati:

Mantenere l'app console in esecuzione per i passaggi successivi.

Errori

L'applicazione di esempio gestisce anche gli errori del servizio.

Per testare questo problema, eseguire di nuovo il CreateModels comando per provare a caricare nuovamente il modello Room già caricato:

CreateModels Room

Poiché i modelli non possono essere sovrascritti, questo comando restituirà ora un errore del servizio che indica che alcuni DEGLI ID modello che si sta tentando di creare esistono già.

Per informazioni dettagliate su come eliminare i modelli esistenti, vedere Gestire i modelli DTDL.

Creare i gemelli digitali

Ora che alcuni modelli sono stati caricati nell'istanza di Gemelli digitali di Azure, è possibile creare i gemelli digitali in base alle definizioni dei modelli. I gemelli digitali rappresentano le entità all'interno dell'ambiente aziendale, ad esempio i sensori di un'azienda agricola, le stanze di un edificio o i fari di un'auto.

Per creare un gemello digitale, usare il comando CreateDigitalTwin. È necessario fare riferimento al modello su cui si basa il gemello e facoltativamente definire i valori iniziali per tutte le proprietà nel modello. Non è necessario passare informazioni sulle relazioni in questa fase.

Eseguire questo codice nella console del progetto in esecuzione per creare diversi gemelli, in base al modello Room aggiornato in precedenza e a un altro modello, Floor. Tenere presente che Room ha tre proprietà, in modo da poter fornire argomenti con i valori iniziali per queste proprietà. L'inizializzazione dei valori delle proprietà è facoltativa in generale, ma sono necessarie per questa esercitazione.
```
CreateDigitalTwin dtmi:example:Room;2 room0 RoomName string Room0 Temperature double 70 HumidityLevel double 30
CreateDigitalTwin dtmi:example:Room;2 room1 RoomName string Room1 Temperature double 80 HumidityLevel double 60
CreateDigitalTwin dtmi:example:Floor;1 floor0
CreateDigitalTwin dtmi:example:Floor;1 floor1
```
L'output di questi comandi dovrebbe indicare che i gemelli sono stati creati correttamente.
È possibile verificare che i gemelli siano stati creati eseguendo il Query comando . Questo comando esegue una query nell'istanza di Gemelli digitali di Azure per recuperare tutti i gemelli digitali che contiene. Cercare i gemelli room0, room1, floor0 e floor1 nei risultati.

Nota

Dopo aver apportato una modifica ai dati nel grafico, potrebbe verificarsi una latenza fino a 10 secondi prima che le modifiche vengano riflesse nelle query.

L'API DigitalTwins riflette immediatamente le modifiche, quindi se è necessaria una risposta immediata, usare una richiesta API (DigitalTwins GetById) o una chiamata SDK (GetDigitalTwin) per ottenere dati gemelli anziché una query.

Modificare un gemello digitale

È anche possibile modificare le proprietà di un gemello creato.

Nota

L'API REST sottostante usa il formato patch JSON per definire gli aggiornamenti di un gemello. L'app da riga di comando usa anche questo formato per offrire un'esperienza più efficace con le API sottostanti previste.

Eseguire questo comando per modificare roomName di room0 da "Room0" a "PresidentialSuite":
```
UpdateDigitalTwin room0 add /RoomName string PresidentialSuite
```
L'output dovrebbe indicare che il gemello è stato aggiornato correttamente.
È possibile verificare che l'aggiornamento sia riuscito eseguendo questo comando per visualizzare le informazioni di room0:
```
GetDigitalTwin room0
```
L'output dovrebbe riflettere il nome aggiornato.

Creare un grafo con l'aggiunta di relazioni

Successivamente, è possibile creare alcune relazioni tra questi gemelli, per connetterle a un grafo gemello. I grafi dei gemelli vengono usati per rappresentare l'intero ambiente.

I tipi di relazioni che è possibile creare da un gemello a un altro vengono definiti all'interno dei modelli caricati in precedenza. La definizione del modello per Floor specifica che i piani possono avere un tipo di relazione denominata contains, che consente di creare una containsrelazione di tipo da ogni gemello Floor alla stanza corrispondente che contiene.

Per aggiungere una relazione, usare il comando CreateRelationship. Specificare il gemello da cui proviene la relazione, il tipo di relazione e il gemello a cui si connette la relazione. Infine, assegnare alla relazione un ID univoco.

Eseguire i comandi seguenti per aggiungere una contains relazione da ognuno dei gemelli Floor creati in precedenza a un gemello Room corrispondente. Le relazioni sono denominate relationship0 e relationship1.
```
CreateRelationship floor0 contains room0 relationship0
CreateRelationship floor1 contains room1 relationship1
```
Suggerimento

La contains relazione nel modello Floor è stata definita anche con due proprietà ownershipUser stringa e ownershipDepartment, quindi è anche possibile fornire argomenti con i valori iniziali per questi quando si creano le relazioni. Ecco una versione alternativa del comando precedente per creare relationship0 che specifica anche i valori iniziali per queste proprietà:
```
CreateRelationship floor0 contains room0 relationship0 ownershipUser string MyUser ownershipDepartment string myDepartment
```
L'output di questi comandi conferma che le relazioni sono state create correttamente:
È possibile verificare le relazioni con uno dei comandi seguenti, che visualizzeranno le relazioni nell'istanza di Gemelli digitali di Azure.
- Per visualizzare tutte le relazioni che escono da ogni piano (visualizzazione delle relazioni da un lato):
```
GetRelationships floor0
GetRelationships floor1
```
- Per visualizzare tutte le relazioni in arrivo in ogni stanza (visualizzazione della relazione dall'altro):
```
GetIncomingRelationships room0
GetIncomingRelationships room1
```
- Per cercare queste relazioni singolarmente, in base all'ID:
```
GetRelationship floor0 relationship0
GetRelationship floor1 relationship1
```

I gemelli e le relazioni configurati in questa esercitazione formano il grafo concettuale seguente:

Eseguire una query sul grafo dei gemelli per rispondere alla domande sull'ambiente

Una delle principali funzionalità di Gemelli digitali di Azure è la possibilità di eseguire query sul grafo dei gemelli in modo semplice ed efficiente per trovare le risposte alle domande sull'ambiente.

Nota

Dopo aver apportato una modifica ai dati nel grafico, potrebbe verificarsi una latenza fino a 10 secondi prima che le modifiche vengano riflesse nelle query.

Eseguire i comandi seguenti nella console del progetto in esecuzione per rispondere ad alcune domande sull'ambiente di esempio.

Quali sono tutte le entità dell'ambiente rappresentato in Gemelli digitali di Azure? (query su tutto)
```
Query
```
Questo comando consente di tenere a colpo d'occhio l'ambiente e assicurarsi che tutto sia rappresentato come si vuole che si trovi all'interno di Gemelli digitali di Azure. Il risultato di questo comando è un output contenente ogni gemello digitale con i relativi dettagli. Ecco un estratto:

Suggerimento

Nel progetto di esempio il comando Query senza argomenti aggiuntivi è l'equivalente di Query SELECT * FROM DIGITALTWINS. Per eseguire query su tutti i gemelli nell'istanza con le API Query o i comandi dell'interfaccia della riga di comando, usare la query più lunga (completa).
Quali sono tutte le stanze dell'ambiente? (query per modello)
```
Query SELECT * FROM DIGITALTWINS T WHERE IS_OF_MODEL(T, 'dtmi:example:Room;2')
```
È possibile limitare la query ai gemelli di un determinato tipo, per ottenere informazioni più specifiche su quello che rappresentano. Il risultato di questo mostra room0 e room1, ma non mostra floor0 o floor1 (poiché sono pavimenti, non camere).
Quali sono tutte le stanze in floor0? (query per relazione)
```
Query SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.$dtId = 'floor0'
```
È possibile eseguire query in base alle relazioni nel grafo, per ottenere informazioni sul modo in cui i gemelli sono connessi o limitare la query a una determinata area. In floor0 è presente solo room0, che quindi è l'unica stanza nel risultato.
Quali sono i gemelli dell'ambiente con una temperatura superiore a 75? (query per proprietà)
```
Query SELECT * FROM DigitalTwins T WHERE T.Temperature > 75
```
È possibile eseguire una query sul grafico in base alle proprietà per rispondere a varie domande, tra cui la ricerca di outlier nell'ambiente che potrebbe richiedere attenzione. Sono supportati anche altri operatori di confronto, ossia <,>, = o !=. I risultati mostrano room1, perché ha una temperatura pari a 80.
Quali sono tutte le stanze in floor0 con una temperatura superiore a 75? (query composta)
```
Query SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.$dtId = 'floor0' AND IS_OF_MODEL(room, 'dtmi:example:Room;2') AND room.Temperature > 75
```
È anche possibile combinare le query precedenti come in SQL, usando operatori di combinazione come AND, OR, NOT. Questa query usa AND per rendere più specifica la query precedente sulle temperature dei gemelli. Il risultato include ora solo le stanze con temperature superiori a 75 che si trovano in floor0, ovvero in questo caso nessuna stanza. Il set di risultati è vuoto.

Ora che sono state eseguite diverse query nello scenario configurato, l'esercitazione è stata completata. Arrestare l'esecuzione del progetto e chiudere la finestra della console.

Pulire le risorse

Dopo aver completato questa esercitazione, è possibile scegliere le risorse da rimuovere, a seconda delle operazioni da eseguire successivamente.

Se si prevede di continuare con l'esercitazione successiva, è possibile mantenere le risorse configurate qui per continuare a usare questa istanza di Gemelli digitali di Azure e l'app di esempio configurata per l'esercitazione successiva
Se si vuole continuare a usare l'istanza di Gemelli digitali di Azure, ma cancellare tutti i modelli, i gemelli e le relazioni, è possibile usare rispettivamente i comandi e DeleteAllModels l'app di DeleteAllTwins esempio per cancellare i gemelli e i modelli nell'istanza.

Se non sono necessarie risorse create in questa esercitazione, è possibile eliminare l'istanza di Gemelli digitali di Azure e tutte le altre risorse di questo articolo con il comando az group delete dell'interfaccia della riga di comando. In questo modo vengono eliminate tutte le risorse di Azure in un gruppo di risorse, nonché il gruppo di risorse stesso.

Importante

L'eliminazione di un gruppo di risorse è irreversibile. Il gruppo di risorse e tutte le risorse in esso contenute vengono eliminati in modo permanente. Assicurarsi di non eliminare accidentalmente il gruppo di risorse sbagliato o le risorse errate.

Aprire Azure Cloud Shell o una finestra dell'interfaccia della riga di comando locale ed eseguire il comando seguente per eliminare il gruppo di risorse e tutto ciò che contiene.
```
az group delete --name <your-resource-group>
```

È anche possibile eliminare la cartella del progetto scaricata dal computer locale.

Passaggi successivi

In questa esercitazione si è iniziato a usare Gemelli digitali di Azure creando un grafo nell'istanza usando un'applicazione client di esempio. Sono stati creati modelli, gemelli digitali e relazioni per formare un grafo. Sono state anche eseguite alcune query sul grafico per ottenere un'idea dei tipi di domande a cui è possibile rispondere Gemelli digitali di Azure.

Passare all'esercitazione successiva per combinare Gemelli digitali di Azure con altri servizi di Azure per completare uno scenario end-to-end basato sui dati:

Connessione una soluzione end-to-end

Esercitazione: Creare un grafo di Gemelli digitali di Azure usando un'app client di esempio

Prerequisiti

Ottenere risorse di esempio

Preparare un'istanza di Gemelli digitali di Azure

Configurare il progetto di esempio

Configurare le credenziali di Azure locali

Eseguire il progetto di esempio

Modellare un ambiente fisico con DTDL

Caricare modelli in Gemelli digitali di Azure

Errori

Creare i gemelli digitali

Modificare un gemello digitale

Creare un grafo con l'aggiunta di relazioni

Eseguire una query sul grafo dei gemelli per rispondere alla domande sull'ambiente

Pulire le risorse

Passaggi successivi

Risorse aggiuntive