Gemelli digitali e grafico dei gemelli

Questo articolo descrive quali gemelli digitali sono nel contesto di Gemelli digitali di Azure e come le relazioni tra di esse possono formare un grafo dei gemelli. In una soluzione gemelli digitali di Azure, le entità nell'ambiente sono rappresentate da gemelli digitali. Un gemello digitale è un'istanza di uno dei modelli personalizzati. Può essere connessa ad altri gemelli digitali tramite relazioni per formare un grafo gemello: questo grafo gemello è la rappresentazione dell'intero ambiente.

Suggerimento

Il nome "Gemelli digitali di Azure" fa riferimento a questo servizio di Azure nel suo complesso. Il termine "gemelli digitali" o semplicemente "gemelli" si riferisce a singoli nodi gemelli all'interno dell'istanza del servizio.

Gemelli digitali

Prima di poter creare un gemello digitale nell'istanza di Gemelli digitali di Azure, è necessario avere un modello caricato nel servizio. Un modello descrive il set di proprietà e relazioni che un particolare gemello può avere, tra le altre cose. Per i tipi di informazioni definite in un modello, vedere Modelli personalizzati.

Dopo aver creato e caricato un modello, l'app client può creare un'istanza del tipo. Questa istanza è un gemello digitale. Ad esempio, dopo aver creato un modello di Floor, è possibile creare uno o più gemelli digitali che usano questo tipo (ad esempio un gemello di tipo Floor denominato Ground Floor Floor, un altro denominato Floor2 e così via).

Nota

I gemelli digitali in Gemelli digitali di Azure sono diversi dai dispositivi gemelli in hub IoT. hub IoT dispositivi gemelli si concentrano spesso sulla descrizione degli aspetti e delle funzionalità di un dispositivo stesso, mentre i gemelli in Gemelli digitali di Azure sono più rappresentazioni concettuali che possono archiviare informazioni dettagliate definite dall'utente su un dispositivo o su molti dispositivi correlati.

I dispositivi in hub IoT possono essere connessi a Gemelli digitali di Azure come parte di una soluzione end-to-end che rappresenta il dispositivo tra i servizi.

Relazioni: un grafo di gemelli digitali

I gemelli sono connessi in un grafo dei gemelli in base alle relative relazioni. Le relazioni che un gemello può avere sono definite come parte del modello.

Ad esempio, il modello Floor potrebbe definire una contains relazione destinata a gemelli di tipo Room. Con questa definizione, Gemelli digitali di Azure consentirà di creare contains relazioni da qualsiasi gemello Floor a qualsiasi gemello Room (inclusi i gemelli di sottotipi Room).

Il risultato di questo processo è un set di nodi (i gemelli digitali) connessi tramite archi (le relative relazioni) in un grafo.

Visualizzazione

Azure Digital Twins Explorer è uno strumento visivo per esplorare i dati nel grafico 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.

Ecco l'aspetto della visualizzazione:

Creare con le API

Questa sezione illustra come creare gemelli digitali e relazioni da un'applicazione client. Contiene esempi di .NET SDK che usano le API DigitalTwins, per fornire un contesto più dettagliato su ciò che accade all'interno di ognuno di questi concetti.

Creare i gemelli digitali

Di seguito è riportato un frammento di codice client che usa le API DigitalTwins per creare un'istanza di un gemello di tipo Room con un twinId oggetto definito durante la creazione di istanze.

È possibile inizializzare le proprietà di un gemello al momento della creazione o impostarle in un secondo momento. Per creare un gemello con proprietà inizializzate, creare un documento JSON che fornisca i valori di inizializzazione necessari.

// Define a custom model type for the twin to be created

internal class CustomDigitalTwin
{
    [JsonPropertyName(DigitalTwinsJsonPropertyNames.DigitalTwinId)]
    public string Id { get; set; }

    [JsonPropertyName(DigitalTwinsJsonPropertyNames.DigitalTwinETag)]
    public string ETag { get; set; }

    [JsonPropertyName("temperature")]
    public double Temperature { get; set; }

    [JsonPropertyName("humidity")]
    public double Humidity{ get; set; }
}

// Initialize properties and create the twin
public class TwinOperationsCreateTwin
{
    public async Task CreateTwinAsync(DigitalTwinsClient client)
    {
        // Initialize the twin properties
        var myTwin = new CustomDigitalTwin
        {
            Temperature = 25.0,
            Humidity = 50.0,
        };

        // Create the twin
        const string twinId = "<twin-ID>";
        Response<CustomDigitalTwin> response = await client.CreateOrReplaceDigitalTwinAsync(twinId, myTwin);
        Console.WriteLine($"Temperature value: {response.Value.Temperature}");
    }
}

È anche possibile usare una classe helper denominata BasicDigitalTwin per archiviare i campi delle proprietà in un oggetto "gemello" più direttamente, in alternativa all'uso di un dizionario. Per altre informazioni sulla classe helper ed esempi del relativo uso, vedere Creare un gemello digitale.

Nota

Anche se le proprietà dei dispositivi gemelli vengono considerate facoltative e pertanto non devono essere inizializzate, tutti i componenti del gemello devono essere impostati quando viene creato il gemello. Possono essere oggetti vuoti, ma i componenti devono comunque esistere.

Creare relazioni

Di seguito è riportato un esempio di codice client che usa le API DigitalTwins per creare una relazione da un gemello digitale (il gemello "di origine") a un altro gemello digitale (il gemello "di destinazione").

public async Task CreateRelationship(DigitalTwinsClient client)
{
    var rel = new BasicRelationship
    {
        TargetId = "myTargetTwin",
        Name = "contains", // a relationship with this name must be defined in the model
        // Initialize properties
        Properties =
        {
            { "active", true },
        },
    };
    await client.CreateOrReplaceRelationshipAsync("mySourceTwin", "rel001", rel);
}

Creare gemelli e relazioni in blocco con l'API Importa processi

È possibile caricare molti gemelli e relazioni in una singola chiamata API usando l'API Importa processi. I gemelli e le relazioni create con questa API possono includere facoltativamente l'inizializzazione delle relative proprietà. Per istruzioni dettagliate ed esempi che usano questa API, vedere istruzioni di importazione bulk per gemelli e relazioni.

Eliminare gli elementi del grafo

Per eliminare gemelli e relazioni specifici, usare le API DigitalTwins Delete e DigitalTwins DeleteRelationship (disponibili anche in come comandi dell'interfaccia della riga di comando e chiamate SDK).

Per eliminare tutti i modelli, i gemelli e le relazioni in un'istanza contemporaneamente, usare l'API Elimina processi.

Rappresentazioni JSON degli elementi del grafo

I dati e i dati delle relazioni di Gemelli digitali vengono archiviati in formato JSON, il che significa che quando si esegue una query sul grafo del gemello nell'istanza di Gemelli digitali di Azure, il risultato sarà una rappresentazione JSON di gemelli digitali e relazioni create.

Formato JSON del gemello digitale

Se rappresentato come oggetto JSON, un gemello digitale visualizzerà i campi seguenti:

Nome del campo	Descrizione
$dtId	Stringa fornita dall'utente che rappresenta l'ID del gemello digitale
$etag	Campo HTTP standard assegnato dal server Web
$metadata.$model	ID dell'interfaccia del modello che caratterizza questo gemello digitale
$metadata.<property-name>	Altre informazioni sui metadati sulle proprietà del gemello digitale
$metadata.<property-name>.lastUpdateTime	Data/ora in cui il messaggio di aggiornamento della proprietà è stato elaborato da Gemelli digitali di Azure
$metadata.<property-name>.sourceTime	Proprietà facoltativa scrivibile che rappresenta il timestamp quando l'aggiornamento della proprietà è stato osservato nel mondo reale. Questa proprietà può essere scritta solo usando la versione 2022-05-31 delle API/SDK di Gemelli digitali di Azure e il valore deve essere conforme al formato di data e ora ISO 8601. Per altre informazioni su come aggiornare questa proprietà, vedere Aggiornare sourceTime di una proprietà.
<property-name>	Valore di una proprietà in JSON (string, tipo di numero o oggetto)
$relationships	URL del percorso della raccolta relazioni. Questo campo è assente se il gemello digitale non presenta bordi delle relazioni in uscita.
<component-name>	Oggetto JSON contenente i valori e i metadati delle proprietà del componente, simili a quelli dell'oggetto radice. Questo oggetto esiste anche se il componente non ha proprietà.
<component-name>.$metadata	Informazioni sui metadati per il componente, simili al livello radice $metadata
<component-name>.<property-name>	Valore della proprietà del componente in JSON (string, tipo di numero o oggetto)

Ecco un esempio di gemello digitale formattato come oggetto JSON. Questo gemello ha due proprietà, Umidità e Temperatura e un componente denominato Termostato.

{
    "$dtId": "myRoomID",
    "$etag": "W/\"8e6d3e89-1166-4a1d-9a99-8accd8fef43f\"",
    "$metadata": {
        "$model": "dtmi:example:Room23;1",
        "Humidity": {
          "lastUpdateTime": "2021-11-30T18:47:53.7648958Z"
        },
        "Temperature": {
          "lastUpdateTime": "2021-11-30T18:47:53.7648958Z"
        }
    },
    "Humidity": 55,
    "Temperature": 35,
    "Thermostat": {
        "$metadata": {}
    }

Formato JSON della relazione

Se rappresentato come oggetto JSON, una relazione di un gemello digitale visualizzerà i campi seguenti:

Nome del campo	Descrizione
$relationshipId	Stringa fornita dall'utente che rappresenta l'ID di questa relazione. Questa stringa è univoca nel contesto del gemello digitale di origine, il che significa anche che sourceId + relationshipId è univoco nel contesto dell'istanza di Gemelli digitali di Azure.
$etag	Campo HTTP standard assegnato dal server Web
$sourceId	ID del gemello digitale di origine
$targetId	ID del gemello digitale di destinazione
$relationshipName	Nome della relazione
<property-name>	[Facoltativo] Valore di una proprietà di questa relazione, in JSON (string, tipo di numero o oggetto)

Ecco un esempio di relazione formattata come oggetto JSON:

{
  "$relationshipId": "relationship-01",
  "$etag": "W/\"506e8391-2b21-4ac9-bca3-53e6620f6a90\"",
  "$sourceId": "GroundFloor",
  "$targetId": "Cafe",
  "$relationshipName": "contains",
  "startDate": "2020-02-04"
}

Passaggi successivi

Vedere come gestire gli elementi del grafo con le API di Gemelli digitali di Azure:

• Gestire gemelli digitali
• Gestire il grafico e le relazioni dei gemelli

In alternativa, vedere l'articolo relativo all'esecuzione di query sul grafo di Gemelli digitali di Azure per informazioni:

• Linguaggio di query