Gestire i modelli di Gemelli digitali di Azure

Questo articolo descrive come gestire i modelli nell'istanza di Gemelli digitali di Azure. Le operazioni di gestione includono caricamento, convalida, recupero ed eliminazione di modelli.

Prerequisiti

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.

Interfacce per sviluppatori

Questo articolo illustra come completare diverse operazioni di gestione usando .NET (C#) SDK. È anche possibile creare queste stesse chiamate di gestione usando gli altri SDK del linguaggio descritti in API e SDK di Gemelli digitali di Azure.

Altre interfacce di sviluppo che è possibile usare per completare queste operazioni includono:

• Azure Digital Twins Explorer
• Chiamate API REST
• Comandi dell'interfaccia della riga di comando di Azure

Visualizzazione

Azure Digital Twins Explorer è uno strumento visivo per esplorare i dati nel grafo di Gemelli digitali di Azure. È possibile usare Esplora risorse per visualizzare, eseguire query e modificare modelli, gemelli e relazioni.

Per informazioni sullo strumento Azure Digital Twins Explorer, vedere Azure Digital Twins Explorer. Per informazioni dettagliate su come usare le funzionalità, vedere Usare Azure Digital Twins Explorer.

La visualizzazione deve avere il seguente aspetto:

Creare modelli

È possibile creare modelli personalizzati da zero o usare ontologie esistenti disponibili per il proprio settore.

Creare modelli

I modelli per Gemelli digitali di Azure vengono scritti in DTDL e salvati come file JSON. È disponibile anche un'estensione DTDL per Visual Studio Code, che fornisce la convalida della sintassi e altre funzionalità per semplificare la scrittura di documenti DTDL.

Si consideri un esempio in cui un ospedale vuole rappresentare digitalmente le loro stanze. Ogni stanza contiene un distributore intelligente di sapone per il monitoraggio del lavaggio manuale e sensori per monitorare il traffico attraverso la stanza.

Il primo passo verso la soluzione consiste nel creare modelli per rappresentare gli aspetti dell'ospedale. Una stanza dei pazienti in questo scenario può essere descritta come segue:

{
    "@id": "dtmi:com:contoso:PatientRoom;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;3",
    "displayName": "Patient Room",
    "contents": [
      {
        "@type": "Property",
        "name": "visitorCount",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "handWashCount",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "handWashPercentage",
        "schema": "double"
      },
      {
        "@type": "Relationship",
        "name": "hasDevices"
      }
    ]
  }

Questo modello definisce un nome e un ID univoco per la stanza dei pazienti e le proprietà per rappresentare il numero di visitatori e lo stato di lavaggio manuale. Questi contatori verranno aggiornati dai sensori di movimento e dai distributori intelligenti di sapone e verranno utilizzati insieme per calcolare una proprietà handwash percentage. Il modello definisce anche una relazione hasDevices, che verrà usata per connettere qualsiasi gemello digitale basato su questo modello Room ai dispositivi effettivi.

Seguendo questo metodo, è possibile definire modelli per i reparti, le zone o l'ospedale stesso.

Se l'obiettivo è creare un set di modelli completo che descrive il dominio del settore, valutare se è presente un'ontologia del settore esistente che è possibile usare per semplificare la creazione di modelli. La sezione successiva descrive in modo più dettagliato le ontologie del settore.

Usare ontologie standard del settore esistenti

Un'ontologia è un set di modelli che descrivono in modo completo un determinato dominio, come la produzione, la costruzione di strutture, sistemi IoT, città intelligenti, reti energetiche, contenuti Web e altro ancora.

Se la soluzione è destinata a un determinato settore che usa qualsiasi tipo di standard di modellazione, è consigliabile iniziare con un set preesistente di modelli progettati per il settore invece di progettare i modelli da zero. Microsoft ha collaborato con esperti di dominio per creare ontologie di modelli DTDL basate su standard di settore, per ridurre al minimo la reinvenzione e incoraggiare la coerenza e la semplicità tra le soluzioni del settore. Altre informazioni su queste ontologie, tra cui come usarle e quali ontologie sono ora disponibili, in Che cos'è un'ontologia?.

Convalidare la sintassi

Dopo aver creato un modello, è consigliabile convalidare i modelli offline prima di caricarli nell'istanza di Gemelli digitali di Azure.

Per convalidare i modelli, viene fornita una libreria di analisi DTDL sul lato client .NET in NuGet: DTDLParser. È possibile usare la libreria parser direttamente nel codice C#. È anche possibile visualizzare l'uso di esempio del parser in DTDLParserResolveSample in GitHub.

Caricare i modelli

Dopo aver creato i modelli, è possibile caricarli nell'istanza di Gemelli digitali di Azure.

Quando si è pronti per caricare un modello, è possibile usare il frammento di codice seguente per .NET SDK:

// 'client' is an instance of DigitalTwinsClient
// Read model file into string (not part of SDK)
// fileName is the name of the JSON model file
string dtdl = File.ReadAllText(fileName);
await client.CreateModelsAsync(new[] { dtdl });

Al caricamento, i file del modello vengono convalidati dal servizio.

In genere è necessario caricare più modelli nel servizio. Esistono diversi modi per caricare più modelli contemporaneamente in una singola transazione. Per facilitare la scelta di una strategia, prendere in considerazione le dimensioni del set di modelli mentre si continua con il resto di questa sezione.

Caricare set di modelli di piccole dimensioni

Per i set di modelli più piccoli, è possibile caricare più modelli contemporaneamente usando singole chiamate API. È possibile controllare il limite corrente per il numero di modelli che è possibile caricare in una singola chiamata API nel limiti di Gemelli digitali di Azure.

Se si usa l'SDK, è possibile caricare più file di modello con il metodo CreateModels simile al seguente:

var dtdlFiles = Directory.EnumerateFiles(sourceDirectory, "*.json");

var dtdlModels = new List<string>();
foreach (string fileName in dtdlFiles)
{
    // Read model file into string (not part of SDK)
    string dtdl = File.ReadAllText(fileName);
    dtdlModels.Add(dtdl);
}
await client.CreateModelsAsync(dtdlModels);

Se si usano le API REST o l'interfaccia della riga di comando di Azure, è possibile caricare più modelli inserendo più definizioni di modello in un singolo file JSON da caricare insieme. In questo caso, i modelli devono essere inseriti in un array JSON all'interno del file, come nell'esempio seguente:

[
    {
      "@id": "dtmi:com:contoso:Planet;1",
      "@type": "Interface",
      "@context": "dtmi:dtdl:context;3"
    },
    {
      "@id": "dtmi:com:contoso:Moon;1",
      "@type": "Interface",
      "@context": "dtmi:dtdl:context;3"
    }
]

Caricare set di modelli di grandi dimensioni con l'API Importa processi

Per i set di modelli di grandi dimensioni, è possibile usare l'API Importa processi per caricare più modelli contemporaneamente in una singola chiamata API. L'API può accettare simultaneamente fino al limite di Gemelli digitali di Azure per il numero di modelli in un'istanza e riordina automaticamente i modelli, se necessario, per risolvere le dipendenze. Questo metodo richiede l'uso di Archiviazione BLOB di Azure, nonché le autorizzazioni di scrittura nell'istanza di Gemelli digitali di Azure per i modelli e i processi in blocco.

Per importare modelli in blocco, è necessario strutturare i modelli (e tutte le altre risorse incluse nel processo di importazione bulk) come file NDJSON. La sezione Models viene immediatamente dopo quella Header, rendendola la prima sezione dei dati del grafo nel file. È possibile visualizzare un file di importazione di esempio e un progetto di esempio per la creazione di questi file nell’introduzione all'API Importa processi.

Successivamente, il file deve essere caricato in un BLOB di accodamento in Archiviazione BLOB di Azure. Per istruzioni su come creare un contenitore di Archiviazione di Azure, vedere Creare un contenitore. Caricare quindi il file usando il metodo di caricamento preferito (alcune opzioni sono il comando AzCopy, l'interfaccia della riga di comando di Azure o il portale di Azure).

Dopo aver caricato il file NDJSON nel contenitore, ottenere l'URL all'interno del contenitore BLOB. Questo valore verrà usato più avanti nel corpo della chiamata API di importazione in blocco.

Ecco uno screenshot che mostra il valore URL di un file BLOB nel portale di Azure:

Il file può quindi essere usato in una chiamata API Importa lavori. Si fornirà l'URL di archiviazione BLOB del file di input, nonché un nuovo URL di archiviazione BLOB per indicare dove archiviare il log di output quando viene creato dal servizio.

Recupera modelli

È possibile elencare e recuperare modelli archiviati nell'istanza di Gemelli digitali di Azure.

Alcune delle opzioni possibili sono:

• Recuperare un singolo modello
• Recuperare tutti i modelli
• Recuperare metadati e dipendenze per i modelli

Di seguito sono riportati alcune chiamate di esempio:

// 'client' is a valid DigitalTwinsClient object

// Get a single model, metadata and data
Response<DigitalTwinsModelData> md1 = await client.GetModelAsync("<model-Id>");
DigitalTwinsModelData model1 = md1.Value;

// Get a list of the metadata of all available models; print their IDs
AsyncPageable<DigitalTwinsModelData> md2 = client.GetModelsAsync();
await foreach (DigitalTwinsModelData md in md2)
{
    Console.WriteLine($"Type ID: {md.Id}");
}

// Get models and metadata for a model ID, including all dependencies (models that it inherits from, components it references)
AsyncPageable<DigitalTwinsModelData> md3 = client.GetModelsAsync(new GetModelsOptions { IncludeModelDefinition = true });

L'SDK chiama per recuperare i modelli che hanno restituito oggetti DigitalTwinsModelData. DigitalTwinsModelData contiene i metadati relativi al modello archiviato nell'istanza di Gemelli digitali di Azure, ad esempio nome, DTMI e data di creazione del modello. L'oggetto DigitalTwinsModelData include facoltativamente anche il modello stesso. Ciò significa che, a seconda dei parametri, è possibile usare le chiamate di recupero per recuperare solo i metadati (utili negli scenari in cui si desidera visualizzare un elenco dell'interfaccia utente degli strumenti disponibili, ad esempio) o l'intero modello.

La chiamata RetrieveModelWithDependencies restituisce non solo il modello richiesto, ma anche tutti i modelli da cui dipende il modello richiesto.

I modelli non vengono necessariamente restituiti nel modulo del documento in cui sono stati caricati. Gemelli digitali di Azure garantisce solo che il modulo restituito sarà semanticamente equivalente.

Aggiornare i modelli

In questa sezione vengono descritte le considerazioni e le strategie per l'aggiornamento dei modelli.

Prima dell'aggiornamento: pensare nel contesto dell'intera soluzione

Prima di apportare aggiornamenti ai modelli, è consigliabile considerare in modo olistico l'intera soluzione e l'impatto delle modifiche apportate al modello. I modelli in una soluzione di Gemelli digitali di Azure sono spesso interconnessi, quindi è importante essere consapevoli delle modifiche a catena in cui l'aggiornamento di un modello richiede l'aggiornamento di diversi altri. L'aggiornamento dei modelli influirà sui gemelli che usano i modelli e può influire anche sul codice di ingresso e sull'elaborazione di codice, applicazioni client e report automatizzati.

Ecco alcuni consigli che consentono di gestire senza problemi le transizioni del modello:

• Invece di pensare ai modelli come entità separate, prendere in considerazione l'evoluzione dell'intero set di modelli quando appropriato per mantenere aggiornati i modelli e le relative relazioni.
• Gestire modelli come il codice sorgente e gestirli nel controllo del codice sorgente. Applicare lo stesso rigore e attenzione ai modelli e alle modifiche del modello applicate ad altro codice nella soluzione.

Quando si è pronti per continuare con il processo di aggiornamento dei modelli, nella parte restante di questa sezione vengono descritte le strategie che è possibile usare per implementare gli aggiornamenti.

Strategie per l'aggiornamento dei modelli

Dopo aver caricato un modello nell'istanza di Gemelli digitali di Azure, l'interfaccia del modello non è modificabile, il che significa che non esiste una tradizionale "modifica" di modelli. Gemelli digitali di Azure non consente anche il ricaricamento dello stesso modello esatto, mentre un modello corrispondente è già presente nell'istanza.

Se invece si desidera apportare modifiche a un modello, ad esempio l'aggiornamento displayName o description, o l'aggiunta e la rimozione di proprietà, sarà necessario sostituire il modello originale.

Esistono due strategie tra cui scegliere quando si sostituisce un modello:

• Strategia 1: caricare la nuova versione del modello: caricare il modello, con un nuovo numero di versione e aggiornare i gemelli per usare il nuovo modello. Entrambe le versioni nuove e precedenti del modello saranno presenti nell'istanza fino a quando non ne verrà eliminata una.
  • Usare questa strategia quando si desidera aggiornare solo alcuni dei gemelli che usano il modello o quando si desidera assicurarsi che i gemelli rimangano conformi ai modelli e scrivibili tramite la transizione del modello.
• Strategia 2: eliminare il vecchio modello e ricaricare: eliminare il modello originale e caricare il nuovo modello con lo stesso nome e ID (valore DTMI) al suo posto. Sostituisce completamente il modello precedente con quello nuovo.
  • Usare questa strategia quando si desidera aggiornare tutti i gemelli che usano questo modello contemporaneamente, oltre a tutto il codice che reagisce ai modelli. Se l'aggiornamento del modello contiene una modifica che causa un'interruzione con l'aggiornamento del modello, i gemelli non saranno conformi ai modelli per un breve periodo di tempo durante la transizione dal modello precedente a quello nuovo, ovvero non saranno in grado di eseguire aggiornamenti finché il nuovo modello non viene caricato e i gemelli sono conformi.

Continuare con le sezioni successive per altre informazioni su ogni opzione di strategia in dettaglio.

Strategia 1: caricare una nuova versione del modello

Questa opzione comporta la creazione di una nuova versione del modello e il caricamento nell'istanza.

Questa operazione non sovrascrive le versioni precedenti del modello, quindi più versioni del modello coesisteranno nell'istanza fino a quando non vengono rimosse. Poiché la nuova versione del modello e la versione precedente del modello coesistono, i gemelli possono usare la nuova versione del modello o la versione precedente, il che significa che il caricamento di una nuova versione di un modello non influisce automaticamente sui gemelli esistenti. I gemelli esistenti rimarranno come istanze della versione precedente del modello ed è possibile aggiornarli alla nuova versione del modello applicandole patch.

Per usare questa strategia, seguire questa procedura.

1. Creare e caricare una nuova versione del modello

Per creare una nuova versione di un modello esistente, iniziare con il DTDL del modello originario. Aggiornare, aggiungere o rimuovere i campi da modificare.

Contrassegnare quindi questo modello come versione più recente del modello aggiornando il campo id del modello. L'ultima sezione dell'ID modello, dopo ;, rappresenta il numero di modello. Per indicare che questo modello è ora una versione più aggiornata, incrementare il numero alla fine del valore id a un numero maggiore del numero di versione corrente.

Se ad esempio l'ID modello precedente ha l'aspetto seguente:

"@id": "dtmi:com:contoso:PatientRoom;1",

La versione 2 di questo modello potrebbe essere simile alla seguente:

"@id": "dtmi:com:contoso:PatientRoom;2",

Quindi, caricare la nuova versione del modello nell'istanza.

Questa versione del modello sarà disponibile nell'istanza in modo da poter essere usata per i gemelli digitali. Non sovrascrive le versioni precedenti del modello, quindi più versioni del modello ora coesistono nell'istanza.

2. Aggiornare gli elementi del grafo in base alle esigenze

Aggiornare quindi i gemelli e le relazioni nell'istanza in modo da usare la nuova versione del modello anziché quella precedente.

È possibile usare le istruzioni seguenti per aggiornare i dispositivi gemelli e aggiornare le relazioni. L'operazione di patch per aggiornare il modello di un gemello avrà un aspetto simile al seguente:

[
  {
    "op": "replace",
    "path": "/$metadata/$model",
    "value": "dtmi:example:foo;1"
  }
]

Potrebbe anche essere necessario aggiornare le relazioni e altri modelli nell'istanza che fanno riferimento a questo modello per fare riferimento alla nuova versione del modello. È necessario eseguire un'altra operazione di aggiornamento del modello per ottenere questo scopo, quindi tornare all'inizio di questa sezione e ripetere il processo per altri modelli che richiedono l'aggiornamento.

3. (Facoltativo) Rimuovere o eliminare la versione precedente del modello

Se non si usa più la versione precedente del modello, è possibile rimuovere le autorizzazioni del modello precedente. Questa azione consente al modello di mantenere esistente nell'istanza, ma non può essere usata per creare nuovi gemelli digitali.

È anche possibile eliminare completamente il modello precedente se non lo si desidera più nell'istanza.

Le sezioni collegate in precedenza contengono codice di esempio e considerazioni per la rimozione e l'eliminazione di modelli.

Strategia 2: eliminare il modello precedente e ricaricare

Anziché incrementare la versione di un modello, è possibile eliminare completamente un modello e ricaricare un modello modificato nell'istanza.

Gemelli digitali di Azure non ricorda che il modello precedente è mai stato caricato, quindi questa azione sarà simile al caricamento di un modello completamente nuovo. I gemelli che usano il modello passeranno automaticamente alla nuova definizione dopo che è disponibile. A seconda del modo in cui la nuova definizione differisce da quella precedente, questi gemelli possono avere proprietà e relazioni che corrispondono alla definizione eliminata e non sono valide con quella nuova, quindi potrebbe essere necessario applicare patch per assicurarsi che rimangano valide.

Per usare questa strategia, seguire questa procedura.

1. Eliminare un modello precedente

Poiché Gemelli digitali di Azure non consente due modelli con lo stesso ID, iniziare eliminando il modello originale dall'istanza.

Usare le istruzioni seguenti per eliminare il modello originale. Questa azione lascerà i gemelli che usano temporaneamente il modello "orfano", perché ora usano un modello che non esiste più. Questo stato verrà ripristinato nel passaggio successivo quando si ricarica il modello aggiornato.

2. Creare e caricare un nuovo modello

Iniziare con il DTDL del modello originale. Aggiornare, aggiungere o rimuovere i campi da modificare.

Quindi, caricare il modello nell'istanza, come se fosse un nuovo modello caricato per la prima volta.

3. Aggiornare gli elementi del grafo in base alle esigenze

Ora che il nuovo modello è stato caricato al posto di quello precedente, i gemelli nel grafo inizieranno automaticamente a usare la nuova definizione del modello dopo la scadenza della memorizzazione nella cache nell'istanza e la reimpostazione. Questo processo può richiedere 10-15 minuti o più, a seconda delle dimensioni del grafo. Successivamente, le proprietà nuove e modificate nel modello devono essere accessibili e rimosse le proprietà non saranno più accessibili.

Aggiornare quindi i gemelli e le relazioni nell'istanza in modo che le relative proprietà corrispondano alle proprietà definite dal nuovo modello. Prima di completare questo passaggio, i gemelli che non corrispondono al modello possono ancora essere letti, ma non possono essere scritti. Per altre informazioni sullo stato dei gemelli senza un modello valido, vedere Gemelli senza modelli.

Esistono due modi per aggiornare i gemelli e le relazioni per il nuovo modello in modo che siano nuovamente scrivibili:

• Applicare patch ai gemelli e alle relazioni in base alle esigenze in modo che si adattino al nuovo modello. È possibile usare le istruzioni seguenti per aggiornare i dispositivi gemelli e aggiornare le relazioni.
  • Se sono state aggiunte proprietà: l'aggiornamento di gemelli e relazioni con i nuovi valori non è obbligatorio, poiché i gemelli che mancano i nuovi valori saranno ancora validi. È possibile applicare patch alle nuove proprietà, ma si vogliono aggiungere valori per le nuove proprietà.
  • Se sono state rimosse le proprietà: è necessario applicare patch ai dispositivi gemelli per rimuovere le proprietà che ora non sono valide con il nuovo modello.
  • Se sono state aggiornate le proprietà: è necessario applicare patch ai dispositivi gemelli per aggiornare i valori delle proprietà modificate in modo che siano validi con il nuovo modello.
• Eliminare gemelli e relazioni che usano il modello e ricrearli. È possibile usare le istruzioni seguenti per eliminare i gemelli e ricreare i gemelli ed eliminare le relazioni e ricreare le relazioni.
  • È possibile eseguire questa operazione se si apportano molte modifiche al modello e sarà difficile aggiornare i gemelli esistenti in modo che corrispondano. Tuttavia, la ricreazione può essere complicata se hai molti gemelli interconnessi da molte relazioni.

Rimuovere i modelli

I modelli possono essere rimossi dal servizio in uno dei due modi seguenti:

• Ritiro: una volta ritirato, un modello non può più essere usato per creare nuovi gemelli digitali. I gemelli digitali esistenti che usano già il modello non sono interessati dal ritiro. È ancora possibile aggiornarli con altre tecniche, come la modifica di proprietà e l'aggiunta o l'eliminazione di relazioni.
• Eliminazione: questa operazione rimuoverà completamente il modello dalla soluzione. I gemelli che usavano questo modello non sono più associati ad alcun modello valido e quindi vengono considerati come se fossero privi di un modello. È comunque possibile leggere questi gemelli, ma non è possibile apportare aggiornamenti su di essi finché non vengono riassegnati a un modello differente.

Queste operazioni sono funzionalità separate e non influiscono l'una sull'altra, anche se possono essere usate insieme per rimuovere gradualmente un modello.

Ritiro

Per rimuovere le autorizzazioni di un modello, è possibile usare il metodo DecommissionModel dall'SDK:

// 'client' is a valid DigitalTwinsClient
await client.DecommissionModelAsync(dtmiOfPlanetInterface);
// Write some code that deletes or transitions digital twins
//...

È anche possibile rimuovere le autorizzazioni di un modello usando la chiamata API REST DigitalTwinModels Update. La proprietà decommissioned è l'unica proprietà che può essere sostituita con questa chiamata API. Il documento JSON Patch avrà un aspetto simile al seguente:

[
  {
    "op": "replace",
    "path": "/decommissioned",
    "value": true
  }
]

Lo stato di rimozione delle autorizzazioni di un modello è incluso nei record ModelData restituiti dalle API di recupero del modello.

Eliminazione

È possibile eliminare tutti i modelli nell'istanza contemporaneamente oppure eseguire questa operazione su un modello alla volta.

Per un esempio di come eliminare tutti i modelli contemporaneamente, vedere i repository Esempi end-to-end per Gemelli digitali di Azure in GitHub. Il file CommandLoop.cs contiene una funzione CommandDeleteAllModels con codice per eliminare tutti i modelli nell'istanza.

Per eliminare un singolo modello, seguire le istruzioni e le considerazioni della parte restante di questa sezione.

Prima dell'eliminazione: i requisiti

In genere i modelli possono essere eliminati in qualunque momento.

L'eccezione è il modello da cui dipendono altri modelli, con una relazione extends o come componente. Si supponga ad esempio che un modello ConferenceRoom estenda un modello Room e disponga di un modello ACUnit come componente. In questo caso, non sarà possibile eliminare né il modello Room né il modello ACUnit finché i rispettivi riferimenti non verranno rimossi dal modello ConferenceRoom.

A tale scopo, aggiornare il modello dipendente per rimuovere le dipendenze o eliminare completamente il modello dipendente.

Durante l'eliminazione: il processo

Anche se un modello soddisfa i requisiti per l'eliminazione immediata, è consigliabile eseguire prima alcuni passaggi per evitare conseguenze impreviste per i gemelli che rimangono. Di seguito sono riportati alcuni passaggi che consentono di gestire il processo:

1. Prima di tutto, rimuovere le autorizzazioni del modello
2. Attendere alcuni minuti per assicurarsi che il servizio abbia elaborato le richieste di creazione dei dispositivi gemelli dell'ultimo minuto inviate prima della rimozione delle autorizzazioni
3. Eseguire query sui gemelli in base al modello per visualizzare tutti i dispositivi gemelli che usano il modello ora rimosso
4. Eliminare i gemelli se non sono più necessari o applicarli a un nuovo modello, se necessario. È possibile scegliere di non apportare alcun aggiornamento ai gemelli. In tal caso, dopo l'eliminazione del modello, i gemelli rimanenti saranno considerati come gemelli senza modello. Vedere la sezione seguente per le implicazioni che comporta questo stato.
5. Attendere altri minuti per assicurarsi che le modifiche siano state apportate in modo permanente
6. Eliminare il modello

Per eliminare un modello, è possibile usare la chiamata DeleteModel SDK:

// 'client' is a valid DigitalTwinsClient
await client.DeleteModelAsync(IDToDelete);

È anche possibile eliminare un modello con la chiamata API REST DigitalTwinModels Delete.

Dopo l'eliminazione: gemelli senza modelli

Dopo l'eliminazione di un modello, i gemelli digitali da cui era usato vengono ora considerati come privi di modello. Non esiste alcuna query in grado di fornire un elenco di tutti i gemelli in questo stato, anche se è comunque possibile eseguire una query sui gemelli dal modello eliminato per sapere quali gemelli sono interessati.

Di seguito è riportata una panoramica delle operazioni eseguibili e non eseguibili sui gemelli privi di modello.

Operazioni consentite:

• Eseguire una query sul gemello
• Leggere le proprietà
• Leggere le relazioni in uscita
• Aggiungere ed eliminare relazioni in ingresso (come in, altri gemelli possono comunque formare relazioni con questo gemello)
  • L'oggetto target nella definizione della relazione può comunque riflettere il DTMI del modello eliminato. In questo caso, può funzionare anche una relazione senza destinazione definita.
• Eliminare le relazioni
• Eliminare il gemello

Operazioni non consentite:

• Modificare le relazioni in uscita (come in, relazioni da questo gemello ad altri gemelli)
• Modifica proprietà

Dopo l'eliminazione: ricaricamento di un modello

Dopo l'eliminazione di un modello, è possibile decidere di caricare un nuovo modello con lo stesso ID di quello eliminato. Ecco cosa accade in questo caso.

• Dal punto di vista dell'archivio soluzioni, questa operazione equivale al caricamento di un modello completamente nuovo. Il servizio non ricorda che il precedente sia mai stato caricato.
• Se nel grafo sono presenti altri gemelli che fanno riferimento al modello eliminato, non sono più orfani; questo ID modello è di nuovo valido con la nuova definizione. Se tuttavia la definizione del nuovo modello è diversa da quella associata al modello eliminato, i gemelli potranno presentare proprietà e relazioni che corrispondono alla definizione eliminata e non sono valide per quella nuova.

Gemelli digitali di Azure non impedisce questo stato, quindi prestare attenzione alle patch dei gemelli in modo appropriato per assicurarsi che rimangano validi tramite l'opzione di definizione del modello.

Convertire i modelli v2 in v3

Gemelli digitali di Azure supporta le versioni DTDL 2 e 3 (abbreviate rispettivamente nella documentazione a v2 e v3). V3 è la scelta consigliata in base alle funzionalità espanse. Questa sezione illustra come aggiornare un modello DTDL v2 esistente a DTDL v3.

1. Aggiornare il contesto. La funzionalità principale che identifica un modello come v2 o v3 è il campo @context nell'interfaccia. Per convertire un modello da v2 a v3, modificare il valore del contesto dtmi:dtdl:context;2 in dtmi:dtdl:context;3. Per molti modelli, questa sarà l'unica modifica necessaria.
   1. Valore in v2: "@context": "dtmi:dtdl:context;2"
   2. Valore nella versione 3: "@context": "dtmi:dtdl:context;3".
2. Se necessario, aggiornare i tipi semantici. In DTDL v2 i tipi semantici sono supportati in modo nativo. In DTDL v3 sono incluse nell'estensione della funzionalità QuantitativeTypes. Se quindi il modello v2 usa tipi semantici, è necessario aggiungere l'estensione della funzionalità durante la conversione del modello in v3. A tale scopo, modificare prima di tutto il campo @context nell'interfaccia da un singolo valore a un array di valori, quindi aggiungere il valore dtmi:dtdl:extension:quantitativeTypes;1.
   1. Valore in v2: "@context": "dtmi:dtdl:context;2"
   2. Valore nella versione 3: "@context": ["dtmi:dtdl:context;3", "dtmi:dtdl:extension:quantitativeTypes;1"]
3. Se necessario, prendere in considerazione i limiti di dimensione. V2 e v3 hanno limiti di dimensioni differenti, quindi se l'interfaccia è molto grande, è possibile esaminare i limiti nelle differenze tra DTDL v2 e v3.

Dopo queste modifiche, un modello DTDL v2 precedente è stato convertito in un modello DTDL v3.

È anche possibile prendere in considerazione nuove funzionalità di DTDL v3, ad esempio proprietà di tipo array, relax della versione e estensioni di funzionalità aggiuntive, per verificare se uno di essi sarebbe utile aggiunte. Per un elenco completo delle differenze tra DTDL v2 e v3, vedere Modifiche dalla versione 2 nella descrizione del linguaggio DTDL v3.

Passaggi successivi

Vedere come creare e gestire gemelli digitali in base ai modelli:

• Gestire i gemelli digitali