Condividi tramite

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

  • Articolo

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 Codificare 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 acquisire informazioni sulle API di Gemelli digitali di Azure e provare a implementare i propri comandi modificando il progetto di esempio come si preferisce.

In questa esercitazione si apprenderà come:

  • Modellare un ambiente
  • Creare i gemelli digitali
  • Aggiungere relazioni per formare un grafo
  • Eseguire una query sul grafo 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.
  • In questa esercitazione viene usato .NET. È possibile scaricare la versione più recente di .NET SDK da diverse piattaforme da Download .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#. Scaricare il progetto di esempio nel computer passando al link dell'esempio e selezionando il pulsante Esplora codice sotto il titolo.

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

Screenshot del repository digital-twins-samples in GitHub, con evidenziati i passaggi per il download come file ZIP.

Verrà scaricata una cartella .zip nel computer denominata 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 come descritto in questo articolo, è necessaria un'istanza di Gemelli digitali di Azure e le autorizzazioni necessarie per l'utilizzo. Se in precedenza è stata già 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 nel 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.

Nel computer 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, andare 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 sostituire instanceUrl con l'URL del nome host dell'istanza di Gemelli digitali di Azure (aggiungendo https:// prima del nome host, come illustrato di seguito).

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

Salva e chiudi 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 che si vogliono usare per accedere all'istanza di Gemelli digitali di Azure. Se si usa una finestra dell'interfaccia della riga di comando locale, eseguire il comando az login 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 della console del progetto:

Screenshot del messaggio di benvenuto dall'app da riga di comando.

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à eseguita nuovamente più avanti in questa 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 grafo 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 Digital Twins Definition Language (DTDL) 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:

  1. 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.

  2. Modificare una proprietà. Cambiare il nome della proprietà Humidity in HumidityLevel (o qualcosa di differente se si desidera). Se si usa un valore diverso da HumidityLevel, prendere nota del valore immesso e continuare a usarlo al posto di HumidityLevel nell'intera esercitazione.

  3. 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"
}

  4. Aggiungere una relazione. Sotto la proprietà RoomName appena aggiunta incollare il codice seguente per aggiungere la possibilità che questo tipo di dispositivo gemello formi relazioni contains 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 tal modo si configura l'istanza del servizio Gemelli digitali di Azure con il vocabolario del dominio personalizzato. Una volta caricati i modelli, è possibile creare le istanze di gemelli che li usano.

  1. Tornare alla finestra della console aperta alla cartella digital-twins-samples-main\AdtSampleApp\SampleClientApp ed eseguire di nuovo l'app console con dotnet run.

  2. Nella finestra della console del progetto eseguire il comando seguente per caricare il modello Room aggiornato, nonché un modello Floor che verrà usato anche nella sezione successiva per creare tipi differenti di gemelli.

    CreateModels Room Floor

    L'output dovrebbe indicare che i modelli sono stati creati correttamente.

  3. 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:

    Screenshot del risultato di GetModels, che mostra il modello Room aggiornato.

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 comando CreateModels 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. In questa fase non è necessario passare informazioni sulle relazioni.

  1. 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 Stanza include tre proprietà, per cui è possibile specificare argomenti con i valori iniziali per tali 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.

    Screenshot che mostra un estratto del risultato dei comandi CreateDigitalTwin, che include floor0, floor1, room0 e room1.

  2. È possibile verificare se i gemelli sono stati creati eseguendo il comando Query. 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 grafo, potrebbe verificarsi una latenza di 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 la JSON Patch 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.

  1. Eseguire questo comando per cambiare la proprietà RoomName di room0 da "Room0" a "PresidentialSuite":

    UpdateDigitalTwin room0 add /RoomName string PresidentialSuite

    L'output dovrebbe indicare che il gemello è stato aggiornato correttamente.

  2. È 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 relazioni tra questi gemelli, per connetterli in un grafo dei gemelli. 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 relazione di tipo contains 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.

  1. Eseguire i comandi seguenti per aggiungere una relazione contains da ogni gemello Floor creato 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à stringa ownershipUser 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:

    Screenshot di un estratto del risultato dei comandi CreateRelationship, che include relationship0 e relationship1.

  2. È possibile verificare le relazioni con uno dei comandi seguenti, che stamperanno le relazioni nell'istanza di Gemelli digitali di Azure.

    • Per vedere tutte le relazioni provenienti da ogni piano (visualizzazione delle relazioni da un lato): 
      GetRelationships floor0
GetRelationships floor1
    • Per vedere tutte le relazioni in arrivo in ogni stanza (visualizzazione della relazione dall'"altro" lato): 
      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:

Diagramma che mostra un grafo concettuale. floor0 è connesso tramite relationship0 a room0 e floor1 è connesso tramite relationship1 a room1.

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 grafo, potrebbe verificarsi una latenza di 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.

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

  1. Quali sono tutte le entità dell'ambiente rappresentate in Gemelli digitali di Azure? (query su tutto)

    Query

    Questo comando consente di ottenere una panoramica dell'ambiente e assicurarsi che tutti gli elementi siano rappresentati come previsto all'interno di Gemelli digitali di Azure. Il risultato di questo comando un output contenente ogni gemello digitale con i relativi dettagli. Di seguito è riportato un estratto:

    Screenshot che mostra un risultato parziale della query gemella, tra cui room0 e floor1.

    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).

  2. 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 questa operazione mostra room0 e room1, ma non mostra floor0 o floor1 (perché si tratta di piani, non di stanze).

    Screenshot del risultato della query del modello, che mostra solo room0 e room1.

  3. 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.

    Screenshot del risultato della query di relazione, che mostra room0.

  4. 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 grafo in base alle proprietà per rispondere a varie domande, anche per trovare outlier nell'ambiente che potrebbero richiedere attenzione. Sono supportati anche altri operatori di confronto, ossia <,>, = o !=. I risultati mostrano room1, perché ha una temperatura pari a 80.

    Screenshot del risultato della query della proprietà, che mostra solo room1.

  5. 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.

    Screenshot del risultato della query composta, che non mostra risultati.

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 desidera 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 DeleteAllTwins e DeleteAllModels dell'app di 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 tutti gli elementi contenuti al suo interno.

    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 grafo, per avere un'idea dei tipi di domande a cui Gemelli digitali di Azure è in grado di rispondere su un ambiente.

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

Connettere una soluzione end-to-end