Informazioni sui modelli gemelli e su come definirli in Gemelli digitali di Azure

Articolo
01/04/2024

Una caratteristica chiave di Gemelli digitali di Azure è la possibilità di definire un vocabolario personalizzato e creare il grafo del gemello nei termini auto-definiti dell'azienda. Questa funzionalità viene fornita tramite modelli forniti dall'utente. Puoi pensare ai modelli come i sostantivi in una descrizione del tuo mondo. I modelli di Gemelli digitali di Azure sono rappresentati nel linguaggio DTDL (Digital Twin Definition Language) basato su JSON-LD.

Un modello è simile a una classe in un linguaggio di programmazione orientato agli oggetti, definendo una forma di dati per un concetto specifico nell'ambiente di lavoro reale. I modelli hanno nomi (ad esempio Room o TemperatureSensor) e contengono elementi quali proprietà, componenti e relazioni che descrivono il tipo di entità nell'ambiente. Successivamente, questi modelli verranno usati per creare gemelli digitali che rappresentano entità specifiche che soddisfano questa descrizione del tipo.

DTDL (Digital Twin Definition Language) per i modelli

I modelli per Gemelli digitali di Azure vengono definiti usando il linguaggio DTDL (Digital Twins Definition Language).

È possibile visualizzare la descrizione completa del linguaggio per DTDL v3 in GitHub: Descrizione della lingua DTDL versione 3. Questa pagina include dettagli di riferimento DTDL ed esempi utili per iniziare a scrivere modelli DTDL personalizzati.

DTDL è basato su JSON-LD ed è indipendente dal linguaggio di programmazione. DTDL non è esclusivo di Gemelli digitali di Azure. Viene usato anche per rappresentare i dati dei dispositivi in altri servizi IoT, ad esempio Plug and Play IoT.

Il resto di questo articolo riepiloga il modo in cui viene usato il linguaggio in Gemelli digitali di Azure.

Versioni DTDL supportate

Gemelli digitali di Azure supporta le versioni DTDL 2 e 3 (abbreviate rispettivamente nella documentazione a v2 e v3). V3 è la scelta consigliata per la modellazione in Gemelli digitali di Azure in base alle funzionalità espanse, tra cui:

Relax della versione DTMI
Supporto delle matrici per le proprietà
Limiti maggiori per l'ereditarietà dei modelli
Estensioni delle funzionalità
- Possibilità di decorare schemi di interfaccia personalizzati con tipi semantici (forniti con l'estensione QuantitativeTypes)

Se queste funzionalità sono descritte nella documentazione, sono accompagnate da una nota che sono disponibili solo in DTDL v3. Per un elenco completo delle differenze tra DTDL v2 e v3, vedere DTDL v3 Language Description: Changes from Version 2 (Descrizione del linguaggio DTDL v3: modifiche dalla versione 2).

Gemelli digitali di Azure supporta anche l'uso di una combinazione di modelli v2 e v3 all'interno della stessa istanza. Quando si usano modelli di entrambe le versioni, tenere presenti le restrizioni seguenti:

Un'interfaccia v2 non può estendere un'interfaccia v3 o avere un componente con un'interfaccia v3 come schema.
Viceversa, un'interfaccia v3 può estendere un'interfaccia v2 e un'interfaccia v3 può avere un componente con un'interfaccia v2 come schema.
Le relazioni possono puntare in entrambe le direzioni, da un'origine del modello v2 a una destinazione del modello v3 o viceversa da un'origine del modello v3 a una destinazione del modello v2.

È anche possibile eseguire la migrazione di modelli v2 esistenti a v3. Per istruzioni su come eseguire questa operazione, vedere Convertire i modelli v2 in v3.

Nota

Attualmente, Azure Digital Twins Explorer supporta completamente i modelli DTDL v2 e supporta funzionalità limitate per i modelli DTDL v3. In Azure Digital Twins Explorer i modelli DTDL v3 possono essere visualizzati nel pannello Modelli e i gemelli creati con modelli DTDL v3 possono essere visualizzati e modificati (inclusi quelli con proprietà di matrice). Tuttavia, i modelli DTDL v3 non verranno visualizzati nel pannello Model Graph e non possono essere importati usando Azure Digital Twins Explorer. Per importare modelli DTDL v3 nell'istanza, usare un'altra interfaccia di sviluppo come le API e gli SDK o l'interfaccia della riga di comando di Azure.

Panoramica dei modelli

I modelli di tipo gemello possono essere scritti in qualsiasi editor di testo. Il linguaggio DTDL segue la sintassi JSON, quindi è consigliabile archiviare i modelli con l'estensione .json. L'uso dell'estensione JSON consente a molti editor di testo di programmazione di fornire il controllo e l'evidenziazione della sintassi di base per i documenti DTDL. È disponibile anche un'estensione DTDL per Visual Studio Code.

Ecco i campi all'interno di un'interfaccia del modello:

Campo	Descrizione
`@id`	Identificatore DTMI (Digital Twin Model Identifier) per il modello, nel formato `dtmi:<domain>:<unique-model-identifier>;<model-version-number>`. In DTDL v3 il numero di versione può essere omesso o strutturato come numero di versione in due parti (`<major>.<minor>`).
`@type`	Identifica il tipo di informazioni descritte. Per un'interfaccia, il tipo è `Interface`.
`@context`	Imposta il contesto per il documento JSON. I modelli devono essere usati `dtmi:dtdl:context;2` per DTDL v2 o `dtmi:dtdl:context;3` per DTDL v3. I modelli DTDL v3 possono anche denominare estensioni di funzionalità aggiuntive in questo campo.
`displayName`	[facoltativo] Consente di definire un nome descrittivo per il modello. Se non si usa questo campo, il modello userà il relativo valore DTMI completo.
`contents`	Tutti i dati dell'interfaccia rimanenti vengono inseriti qui, come matrice di definizioni di attributi. Ogni attributo deve fornire un oggetto `@type` (`Property`, `Relationship`o `Component`) per identificare il tipo di informazioni sull'interfaccia che descrive e quindi un set di proprietà che definiscono l'attributo effettivo. Nella sezione successiva vengono descritti in dettaglio gli attributi del modello.

Ecco un esempio di modello DTDL di base. Questo modello descrive un oggetto Home, con una proprietà per un ID. Il modello Home definisce anche una relazione con un modello Floor, che può essere usato per indicare che un gemello Home è connesso a determinati gemelli Floor.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "contents": [
    {
      "@type": "Property",
      "name": "id",
      "schema": "string"     
    },    
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1"
    }
  ]
}

Attributi modello

Le informazioni principali su un modello vengono fornite dai relativi attributi, definiti all'interno della contents sezione dell'interfaccia del modello.

Ecco gli attributi disponibili in DTDL supportati in Gemelli digitali di Azure. Un'interfaccia del modello DTDL usata per Gemelli digitali di Azure può contenere zero, uno o molti dei campi seguenti:

Proprietà : le proprietà sono campi dati che rappresentano lo stato di un'entità , ad esempio le proprietà in molti linguaggi di programmazione orientati agli oggetti. Le proprietà dispongono di archiviazione di backup e possono essere lette in qualsiasi momento. Per altre informazioni, vedere Proprietà di seguito.
Relazione : le relazioni consentono di rappresentare il modo in cui un gemello digitale può essere coinvolto con altri gemelli digitali. Le relazioni possono rappresentare significati semantici diversi, ad esempio contains ("floor contains room"), cools ("hvac cool room"), isBilledTo ("compressore viene fatturato all'utente") e così via. Le relazioni consentono alla soluzione di fornire un grafico di entità correlate. Le relazioni possono anche avere proprietà proprie. Per altre informazioni, vedere Relazioni di seguito.
Componente : i componenti consentono di compilare l'interfaccia del modello come assembly di altre interfacce, se necessario. Un esempio di componente è un'interfaccia front Fotocamera (e un'altra interfaccia componente indietro Fotocamera) usata per definire un modello per un telefono. Definire prima un'interfaccia per front Fotocamera come se fosse il proprio modello e quindi farvi riferimento durante la definizione di Telefono.

Usare un componente per descrivere un elemento che fa parte integrante della soluzione, ma non necessita di un'identità separata e non deve essere creato, eliminato o riorganizzato in modo indipendente nel grafico gemello. Se si desidera che le entità abbiano esistenze indipendenti nel grafo dei gemelli, rappresentarle come gemelli digitali separati di modelli diversi, connessi da relazioni.

Suggerimento

I componenti possono essere usati anche per l'organizzazione, per raggruppare set di proprietà correlate all'interno di un'interfaccia del modello. In questo caso, è possibile considerare ogni componente come uno spazio dei nomi o una "cartella" all'interno dell'interfaccia.

Per altre informazioni, vedere Componenti di seguito.

La descrizione del linguaggio DTDL v3 definisce anche comandi e telemetria, ma nessuno di questi vengono usati in Gemelli digitali di Azure. I comandi non sono supportati e i dati di telemetria, anche se consentiti nelle definizioni dei modelli, non hanno casi d'uso univoci nella modellazione di Gemelli digitali di Azure. Anziché usare i dati di telemetria DTDL, è consigliabile usare le proprietà DTDL per archiviare le informazioni sullo stato del gemello.

Nota

Sebbene non sia necessario definire campi di telemetria nei modelli DTDL per archiviare i dati dei dispositivi in ingresso, Gemelli digitali di Azure può generare eventi come dati di telemetria usando l'API SendTelemetry. In questo modo viene attivato un evento messaggio di telemetria di Gemelli digitali che può essere ricevuto da un gestore eventi per eseguire azioni su altri dispositivi gemelli o attivare servizi downstream.

Proprietà

In questa sezione vengono fornite informazioni più dettagliate sulle proprietà nei modelli DTDL.

Per informazioni complete sui campi che possono essere visualizzati come parte di una proprietà, vedere Proprietà nella descrizione del linguaggio DTDL v3.

Nota

L'attributo writable DTDL per le proprietà non è attualmente supportato in Gemelli digitali di Azure. Può essere aggiunto al modello, ma Gemelli digitali di Azure non lo applichererà. Per altre informazioni, vedere Note DTDL specifiche del servizio.

Schema

In base a DTDL, lo schema per gli attributi di proprietà può essere un tipo primitivo standard,integer ovvero , doublestringe , e booleanaltri tipi, ad dateTime esempio e duration.

Oltre ai tipi primitivi, i campi delle proprietà possono avere questi tipi complessi:

Object
Map
Enum
Array, solo in DTDL v3. Array il tipo per le proprietà non è supportato in DTDL v2.

Possono anche essere tipi semantici, che consentono di annotare valori con unità. In DTDL v2 i tipi semantici sono supportati in modo nativo. In DTDL v3 è possibile includerli con un'estensione di funzionalità.

Esempio di proprietà di base

Ecco un esempio di base di una proprietà in un modello DTDL. In questo esempio viene illustrata la proprietà ID di un oggetto Home.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "contents": [
    {
      "@type": "Property",
      "name": "id",
      "schema": "string"     
    },    
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1"
    }
  ]
}

Esempio di tipo oggetto complesso

Le proprietà possono essere di tipi complessi, incluso un Object tipo.

L'esempio seguente mostra un'altra versione del modello Home, con una proprietà per il relativo indirizzo. address è un oggetto, con i propri campi per strada, città, stato e zip.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {
      "@type": "Property",
      "name": "address",
      "schema": {
        "@type": "Object",
        "fields": [
          {
            "name": "street",
            "schema": "string"
          },
          {
            "name": "city",
            "schema": "string"
          },
          {
            "name": "state",
            "schema": "string"
          },
          {
            "name": "zip",
            "schema": "string"
          }
        ]
      }
    },
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1",
      "properties": [
        {
          "@type": "Property",
          "name": "lastOccupied",
          "schema": "dateTime"
        }
      ]
    }
  ]
}

Esempio di tipo semantico DTDL v2

I tipi semantici sono per esprimere un valore con un'unità. Le proprietà per Gemelli digitali di Azure possono usare qualsiasi tipo semantico supportato da DTDL.

In DTDL v2 i tipi semantici sono supportati in modo nativo. Per altre informazioni sui tipi semantici in DTDL v2, vedere Tipi semantici nella descrizione del linguaggio DTDL v2. Per informazioni sui tipi semantici in DTDL v3, vedere l'estensione della funzionalità DTDL DTDL v3 QuantitativeTypes.

L'esempio seguente mostra un modello sensore DTDL v2 con proprietà del tipo semantico per Umidità e Temperatura.

{
  "@id": "dtmi:com:adt:dtsample:v2sensor;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;2",
  "displayName": "Sensor (v2 model)",
  "contents": [
    {
      "@type": ["Property", "Temperature"],
      "name": "Temperature",
      "schema": "double",
      "unit": "degreeFahrenheit"    
    },
    {
      "@type": ["Property", "Humidity"],
      "name": "Humidity",
      "schema": "double",
      "unit": "gramPerCubicMetre" 
    }
  ]
}

Importante

"Property" deve essere il primo elemento della @type matrice, seguito dal tipo semantico. In caso contrario, il campo potrebbe non essere visibile in Azure Digital Twins Explorer.

Relazioni

Questa sezione illustra in dettaglio le relazioni nei modelli DTDL.

Per un elenco completo dei campi che possono essere visualizzati come parte di una relazione, vedere Relazione nella descrizione del linguaggio DTDL v3.

Nota

Gli writableattributi , minMultiplicitye maxMultiplicity DTDL per le relazioni non sono attualmente supportati in Gemelli digitali di Azure. Possono essere aggiunti al modello, ma Gemelli digitali di Azure non li applicheremo. Per altre informazioni, vedere Note DTDL specifiche del servizio.

Esempio di relazione di base

Ecco un esempio di base di una relazione su un modello DTDL. Questo esempio mostra una relazione su un modello Home che consente di connettersi a un modello Floor.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "contents": [
    {
      "@type": "Property",
      "name": "id",
      "schema": "string"     
    },    
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1"
    }
  ]
}

Nota

Per le relazioni, @id è un campo facoltativo. Se non viene specificato alcun elemento @id , il processore dell'interfaccia del gemello digitale ne assegnerà uno.

Relazioni mirate e non mirate

Le relazioni possono essere definite con o senza una destinazione. Una destinazione specifica i tipi di gemelli che la relazione può raggiungere. Ad esempio, è possibile includere una destinazione per specificare che un modello Home può avere solo una rel_has_floors relazione con i gemelli floor.

In alcuni casi, è possibile definire una relazione senza una destinazione specifica, in modo che la relazione possa connettersi a molti tipi diversi di gemelli.

Ecco un esempio di relazione su un modello DTDL che non ha una destinazione. In questo esempio, la relazione è per definire i sensori che potrebbero avere una sala e la relazione può connettersi a qualsiasi tipo.

{
  "@id": "dtmi:com:adt:dtsample:room;1",
  "@type": "Interface",
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:dtdl:extension:quantitativeTypes;1"
  ],
  "displayName": "Room",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {
      "@type": ["Property", "Humidity"],
      "name": "humidity",
      "schema": "double",
      "unit": "gramPerCubicMetre"
    },
    {
      "@type": "Component",
      "name": "thermostat",
      "schema": "dtmi:com:adt:dtsample:thermostat;1"
    },
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:room:rel_has_sensors;1",
      "name": "rel_has_sensors",
      "displayName": "Room has sensors"

Proprietà delle relazioni

DTDL consente anche alle relazioni di avere proprietà proprie. Quando si definisce una relazione all'interno di un modello DTDL, la relazione può avere un proprio properties campo in cui è possibile definire proprietà personalizzate per descrivere lo stato specifico della relazione.

Nell'esempio seguente viene illustrata un'altra versione del modello Home, in cui la rel_has_floors relazione ha una proprietà che rappresenta l'ultimo occupato da Floor correlato.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {
      "@type": "Property",
      "name": "address",
      "schema": {
        "@type": "Object",
        "fields": [
          {
            "name": "street",
            "schema": "string"
          },
          {
            "name": "city",
            "schema": "string"
          },
          {
            "name": "state",
            "schema": "string"
          },
          {
            "name": "zip",
            "schema": "string"
          }
        ]
      }
    },
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1",
      "properties": [
        {
          "@type": "Property",
          "name": "lastOccupied",
          "schema": "dateTime"
        }
      ]
    }
  ]
}

Componenti

Questa sezione illustra in dettaglio i componenti nei modelli DTDL.

Per un elenco completo dei campi che possono essere visualizzati come parte di un componente, vedere Componente nella descrizione del linguaggio DTDL v3.

Esempio di componente di base

Ecco un esempio di base di un componente in un modello DTDL. Questo esempio mostra un modello Room che usa un modello termostato come componente.

[
  {
    "@id": "dtmi:com:adt:dtsample:room;1",
    "@type": "Interface",
    "@context": [
      "dtmi:dtdl:context;3",
      "dtmi:dtdl:extension:quantitativeTypes;1"
    ],
    "displayName": "Room",
    "extends": "dtmi:com:adt:dtsample:core;1",
    "contents": [
      {
        "@type": ["Property", "Humidity"],
        "name": "humidity",
        "schema": "double",
        "unit": "gramPerCubicMetre"
      },
      {
        "@type": "Component",
        "name": "thermostat",
        "schema": "dtmi:com:adt:dtsample:thermostat;1"
      },
      {
        "@type": "Relationship",
        "@id": "dtmi:com:adt:dtsample:room:rel_has_sensors;1",
        "name": "rel_has_sensors",
        "displayName": "Room has sensors"
      }
    ]
  },
  {
    "@context": [
      "dtmi:dtdl:context;3",
      "dtmi:dtdl:extension:quantitativeTypes;1"
    ],
    "@id": "dtmi:com:adt:dtsample:thermostat;1",
    "@type": "Interface",
    "displayName": "thermostat",
    "contents": [
      {
        "@type": ["Property", "Temperature"],
        "name": "temperature",
        "schema": "double",
        "unit": "degreeFahrenheit"
      }
    ]
  }
]

Se anche altri modelli in questa soluzione devono contenere un termostato, possono fare riferimento allo stesso modello di termostato di un componente nelle proprie definizioni, proprio come fa Room.

Importante

L'interfaccia del componente (termostato nell'esempio precedente) deve essere definita nella stessa matrice di tutte le interfacce che lo usano (Room nell'esempio precedente) per trovare il riferimento al componente.

Ereditarietà del modello

A volte si potrebbe rendere un modello ulteriormente specializzato. Ad esempio, potrebbe essere utile avere un modello generico Sala e varianti specializzate ConferenceRoom e Gym. Per esprimere la specializzazione, DTDL supporta l'ereditarietà. Le interfacce possono ereditare da una o più interfacce. A tale scopo, è possibile aggiungere un extends campo al modello.

La extends sezione è un nome di interfaccia o una matrice di nomi di interfaccia ,consentendo all'interfaccia di estensione di ereditare da più modelli padre. Un singolo elemento padre può fungere da modello di base per più interfacce di estensione.

Nota

In DTDL v2 ognuna extends può avere al massimo due interfacce elencate. In DTDL v3 non esiste alcun limite al numero di valori immediati per un oggetto extends.

Sia in DTDL v2 che v3, il limite di profondità totale per una extends gerarchia è 10.

Nell'esempio seguente viene ricreato il modello Home dell'esempio DTDL precedente come sottotipo di un modello "core" più grande. Il modello padre (Core) viene definito per primo e quindi il modello figlio (Home) si basa su di esso usando extends.

{
    "@id": "dtmi:com:adt:dtsample:core;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;3",
    "displayName": "Core",
    "contents": [
        {
            "@type": "Property",
            "name": "id",
            "schema": "string"
        },
        {
            "@type": "Property",
            "name": "name",
            "schema": "string"
        }
    ]
}

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {

In questo caso Core aggiunge un ID e un nome a Home. Anche altri modelli possono estendere il modello Core per ottenere queste proprietà. Ecco un modello Room che estende la stessa interfaccia padre:

{
  "@id": "dtmi:com:adt:dtsample:room;1",
  "@type": "Interface",
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:dtdl:extension:quantitativeTypes;1"
  ],
  "displayName": "Room",

Una volta applicata l'ereditarietà, l'interfaccia di estensione espone tutte le proprietà dell'intera catena di ereditarietà.

L'interfaccia di estensione non può modificare alcuna definizione delle interfacce padre; può essere aggiunto solo a loro. Non può anche ridefinire una funzionalità già definita in una delle relative interfacce padre (anche se le funzionalità sono definite come uguali). Ad esempio, se un'interfaccia padre definisce una double proprietà mass, l'interfaccia di estensione non può contenere una dichiarazione di mass, anche se è anche un oggetto double.

Estensioni delle funzionalità DTDL v3

DTDL v3 abilita le estensioni del linguaggio che definiscono classi metamodelle aggiuntive, che è possibile usare per scrivere modelli più avanzati. Questa sezione descrive le classi di estensione delle funzionalità che è possibile usare per aggiungere funzionalità non principali ai modelli DTDL v3.

Ogni estensione di funzionalità è identificata dal relativo identificatore di contesto, ovvero un valore DTMI (Digital Twin Model Identifier) univoco. Per abilitare un'estensione di funzionalità in un modello, aggiungere l'identificatore di contesto dell'estensione al campo del @context modello (insieme all'identificatore di contesto DTDL generale di dtmi:dtdl:context;3). È possibile aggiungere più estensioni di funzionalità allo stesso modello.

Di seguito è riportato un esempio dell'aspetto del @context campo con le estensioni delle funzionalità. L'estratto seguente è tratto da un modello che usa sia l'estensione QuantitativeTypes che l'estensione Annotation.

  "@context": [
      "dtmi:dtdl:context;3",
      "dtmi:dtdl:extension:quantitativeTypes;1",
      "dtmi:dtdl:extension:annotation;1"
  ]

Dopo aver aggiunto un'estensione di funzionalità a un modello, si avrà accesso ai tipi aggiuntivi dell'estensione all'interno del modello. È possibile aggiungere tipi aggiuntivi al @type campo di un elemento DTDL per fornire all'elemento funzionalità aggiuntive. Il tipo aggiunto può aggiungere proprietà aggiuntive all'elemento .

Ad esempio, di seguito è riportato un estratto di un modello che usa l'estensione Annotation. Questa estensione ha un tipo aggiunto denominato ValueAnnotation, che viene aggiunto nell'esempio seguente a un elemento property. L'aggiunta di questo tipo aggiuntivo all'elemento property consente all'elemento di avere un campo aggiuntivo annotates , che viene utilizzato per indicare un'altra proprietà annotata da questo elemento.

{
  "@type": [ "Property", "ValueAnnotation" ],
  "name": "currentTempAccuracy",
  "annotates": "currentTemp",
  "schema": "double"
  },

La parte restante di questa sezione illustra l'estensione Annotation e altre estensioni delle funzionalità DTDL v3 in modo più dettagliato.

Estensione annotazione

L'estensione Annotation viene usata per aggiungere metadati personalizzati a un elemento di proprietà in un modello DTDL v3. L'identificatore di contesto è dtmi:dtdl:extension:annotation;1.

Questa estensione include il ValueAnnotation tipo aggiunto, che può essere aggiunto a un elemento della proprietà DTDL. Il ValueAnnotation tipo aggiunge un campo all'elemento , annotates, che consente di assegnare un nome a un'altra proprietà annotata dall'elemento corrente.

Per altri dettagli ed esempi di questa estensione, vedere Estensione annotazione nella descrizione del linguaggio DTDL v3.

Estensione per l'istorizzazione

L'estensione Historization viene usata per designare una proprietà in un modello DTDL v3 come elemento che deve essere istorizzato (ovvero la sequenza cronologica dei relativi valori deve essere registrata, insieme ai tempi in cui i valori cambiano). L'identificatore di contesto è dtmi:dtdl:extension:historization;1.

Questa estensione include il Historized tipo aggiunto, che può essere aggiunto come cotipo a un elemento della proprietà DTDL per indicare che il servizio deve rendere persistenti i valori cronologici dell'elemento e renderli disponibili per l'esecuzione di query e analisi. Il Historized tipo aggiunto non aggiunge alcun campo all'elemento.

Per altri dettagli ed esempi di questa estensione, vedere Estensione historization nella descrizione del linguaggio DTDL v3.

Override dell'estensione

L'estensione di override viene usata per eseguire l'override di una proprietà in un modello DTDL V3 con un valore di istanza. Viene usato in combinazione con l'estensione dell'annotazione e il relativo identificatore di contesto è dtmi:dtdl:extension:overriding;1.

Questa estensione include il Override tipo aggiunto, che può essere aggiunto a una proprietà DTDL che è anche cotipata con ValueAnnotation (dall'estensione dell'annotazione). Il Override tipo aggiunge un campo all'elemento , overrides, che consente di assegnare un nome a un campo sull'elemento con annotazioni di cui eseguire l'override in base al valore dell'elemento corrente.

Per altri dettagli ed esempi di questa estensione, vedere Override dell'estensione nella descrizione del linguaggio DTDL v3.

Estensione QuantitativeTypes

L'estensione QuantitativeTypes viene usata per abilitare tipi semantici, tipi di unità e unità in un modello DTDL v3. L'identificatore di contesto è dtmi:dtdl:extension:quantitativeTypes;1.

Questa estensione consente l'uso di molti tipi semantici come tipi aggiuntivi, che possono essere aggiunti a un oggetto CommandRequest, a Field, a MapValue o a una proprietà in DTDL v3. I tipi semantici aggiungono un campo all'elemento , unit, che accetta un'unità valida che corrisponde al tipo semantico.

Per altre informazioni sull'estensione, inclusi esempi e un elenco completo di tipi e unità semantici supportati, vedere Estensione QuantitativeTypes nella descrizione del linguaggio DTDL v3.

Note DTDL specifiche del servizio

Non tutti i servizi che usano DTDL implementano le stesse funzionalità di DTDL. Esistono alcune funzionalità DTDL attualmente non supportate da Gemelli digitali di Azure, tra cui:

Comandi DTDL
Attributo writable sulle proprietà o sulle relazioni. Anche se questo attributo può essere impostato in base alle specifiche DTDL, il valore non viene usato da Gemelli digitali di Azure. Questi attributi vengono invece sempre considerati scrivibili da client esterni che dispongono di autorizzazioni di scrittura generali per il servizio Gemelli digitali di Azure.
Proprietà minMultiplicity e maxMultiplicity sulle relazioni. Anche se questi attributi possono essere impostati in base alle specifiche DTDL, i valori non vengono applicati da Gemelli digitali di Azure.

Affinché un modello DTDL sia compatibile con Gemelli digitali di Azure, deve soddisfare anche questi requisiti:

Tutti gli elementi DTDL di primo livello in un modello devono essere di tipo Interface. Il motivo di questo requisito è che le API del modello di Gemelli digitali di Azure possono ricevere oggetti JSON che rappresentano un'interfaccia o una matrice di interfacce. Di conseguenza, nessun altro tipo di elemento DTDL è consentito al livello superiore.
DTDL per Gemelli digitali di Azure non deve definire alcun comando.
Gemelli digitali di Azure consente solo un singolo livello di annidamento dei componenti, ovvero un'interfaccia usata come componente non può avere componenti.
Le interfacce non possono essere definite inline all'interno di altre interfacce DTDL; devono essere definite come entità di primo livello separate con i propri ID. Quindi, quando un'altra interfaccia vuole includere tale interfaccia come componente o tramite ereditarietà, può fare riferimento al relativo ID.

Strumenti di modellazione e procedure consigliate

Questa sezione descrive considerazioni e consigli aggiuntivi per la modellazione.

Usare ontlogi standard di settore esistenti

Un'ontologia è un set di modelli che descrivono in modo completo un determinato dominio, ad esempio produzione, strutture di costruzione, sistemi IoT, città intelligenti, griglie energetiche, contenuto 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 ontelogi di modelli DTDL basati su standard di settore, per ridurre al minimo la reinventazione e incoraggiare la coerenza e la semplicità tra le soluzioni del settore. Altre informazioni su queste onlogie, tra cui come usarle e quali onlogi sono ora disponibili, in Che cos'è un'ontologia?.

Prendere in considerazione le implicazioni delle query

Durante la progettazione di modelli per riflettere le entità nell'ambiente, può essere utile esaminare le implicazioni della query nella progettazione. È possibile progettare proprietà in modo da evitare set di risultati di grandi dimensioni dall'attraversamento del grafico. È anche possibile modellare le relazioni che dovranno essere risposte in una singola query come relazioni a livello singolo.

Convalidare i modelli

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 ed eliminare modelli in blocco

Al termine della creazione, dell'estensione o della selezione dei modelli, è necessario caricarli nell'istanza di Gemelli digitali di Azure per renderli disponibili per l'uso nella soluzione.

È possibile caricare molti modelli in una singola chiamata API usando l'API Importa processi. 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. Per istruzioni dettagliate ed esempi che usano questa API, vedere istruzioni per l'importazione bulk per i modelli.

Un'alternativa all'API Import Jobs è l'esempio di uploader del modello, che usa le singole API del modello per caricare più file di modello contemporaneamente. L'esempio implementa anche il riordinamento automatico per risolvere le dipendenze del modello. Attualmente funziona solo con la versione 2 di DTDL.

Se è necessario eliminare tutti i modelli in un'istanza di Gemelli digitali di Azure contemporaneamente, è possibile usare l'esempio model deleter. Si tratta di un progetto che contiene la logica ricorsiva per gestire le dipendenze del modello tramite il processo di eliminazione. Attualmente funziona solo con la versione 2 di DTDL.

In alternativa, se si vogliono cancellare i dati in un'istanza eliminando tutti i modelli insieme a tutti i gemelli e le relazioni, è possibile usare l'API Elimina processi.

Visualizzare i modelli

Dopo aver caricato i modelli nell'istanza di Gemelli digitali di Azure, è possibile usare Azure Digital Twins Explorer per visualizzarli. Lo strumento di esplorazione contiene un elenco di tutti i modelli nell'istanza, nonché un grafico del modello che illustra come sono correlati tra loro, incluse eventuali relazioni tra ereditarietà e modello.

Nota

Di seguito è riportato un esempio dell'aspetto di un grafo del modello:

Per altre informazioni sull'esperienza del modello in Azure Digital Twins Explorer, vedere Esplorare i modelli e Model Graph.

Passaggi successivi

Informazioni sulla creazione di modelli basati su ontologi standard del settore: Che cos'è un'ontologia?
Approfondire la gestione dei modelli con le operazioni API: Gestire i modelli DTDL
Informazioni sull'uso dei modelli per creare gemelli digitali: gemelli digitali e il grafo dei gemelli

Informazioni sui modelli gemelli e su come definirli in Gemelli digitali di Azure

DTDL (Digital Twin Definition Language) per i modelli

Versioni DTDL supportate

Panoramica dei modelli

Attributi modello

Proprietà

Schema

Esempio di proprietà di base

Esempio di tipo oggetto complesso

Esempio di tipo semantico DTDL v2

Relazioni

Esempio di relazione di base

Relazioni mirate e non mirate

Proprietà delle relazioni

Componenti

Esempio di componente di base

Ereditarietà del modello

Estensioni delle funzionalità DTDL v3

Estensione annotazione

Estensione per l'istorizzazione

Override dell'estensione

Estensione QuantitativeTypes

Note DTDL specifiche del servizio

Strumenti di modellazione e procedure consigliate

Usare ontlogi standard di settore esistenti

Prendere in considerazione le implicazioni delle query

Convalidare i modelli

Caricare ed eliminare modelli in blocco

Visualizzare i modelli

Passaggi successivi

Risorse aggiuntive