Gemelos digitales y grafo de gemelos

En este artículo se describe qué son los gemelos digitales en el contexto de Azure Digital Twins y cómo las relaciones entre ellos pueden formar un grafo de gemelos. En una solución de Azure Digital Twins, las entidades del entorno se representan mediante gemelos digitales. Un gemelo digital es una instancia de uno de sus modelos definidos de forma personalizada. Se puede conectar a otros gemelos digitales a través de relaciones para formar una grafo de gemelos: este grafo de gemelos es la representación de todo el entorno.

Gemelos digitales

Para poder crear un gemelo digital en la instancia de Azure Digital Twins, debe tener un modelo cargado en el servicio. Un modelo describe el conjunto de propiedades y relaciones que puede tener un gemelo determinado, entre otras cosas. Para conocer los tipos de información que se definen en un modelo, vea Modelos personalizados.

Después de crear y cargar un modelo, su aplicación cliente puede crear una instancia del tipo, que es un gemelo digital. Por ejemplo, después de crear un modelo de Floor, puede crear uno o varios gemelos digitales que usen este tipo (como un gemelo de tipo Floor denominado "GroundFloor", otro denominado "Floor2", etc.).

Relaciones: un grafo de gemelos digitales

Los gemelos se conectan a un grafo de gemelos a través de sus relaciones. Las relaciones que un gemelo puede tener se definen como parte de su modelo.

Por ejemplo, el modelo Floor podría definir una contains relación destinada a gemelos de tipo Room. Con esta definición, Azure Digital Twins le permitirá crear contains relaciones desde cualquier gemelo floor a cualquier gemelo room (incluidos los gemelos que son de subtipos Room).

El resultado de este proceso es un conjunto de nodos (los gemelos digitales) conectado a través de bordes (sus relaciones) en un grafo.

Visualización

Azure Digital Twins Explorer es una herramienta visual para explorar los datos en el grafo de Azure Digital Twins. Puede usar el explorador para ver, consultar y editar los modelos, los gemelos y las relaciones.

Para obtener información sobre la herramienta Azure Digital Twins Explorer, vea Azure Digital Twins Explorer. Para obtener pasos detallados sobre el uso de sus características, consulte Uso de Azure Digital Twins Explorer.

Este es el aspecto de la visualización:

Creación con las API

En esta sección se muestra en qué se basa la creación de gemelos digitales y relaciones desde una aplicación cliente. Contiene ejemplos del SDK de .NET que usan las API de DigitalTwins para proporcionar más contexto sobre lo que sucede dentro de cada uno de estos conceptos.

Creación de gemelos digitales

A continuación se muestra un fragmento de código de cliente que usa las API de DigitalTwins para crear una instancia de un gemelo de tipo Room con un elemento twinId que se define durante dicha creación.

Puede inicializar las propiedades de un gemelo cuando se crea o más adelante. Para crear un gemelo con propiedades inicializadas, cree un documento JSON que proporcione los valores de inicialización necesarios.

// 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}");
    }
}

También puede usar una clase auxiliar denominada BasicDigitalTwin para almacenar campos de propiedades en un objeto "gemelo" más directamente, como alternativa al uso de un diccionario. Para obtener más información sobre la clase auxiliar y observar ejemplos de su uso, consulte Creación de un gemelo digital.

Crear relaciones

A continuación figura un ejemplo de código de cliente que usa las API de DigitalTwins para crear una relación entre dos gemelos digitales (el gemelo de "origen" y el de "destino").

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);
}

Creación de gemelos y relaciones de forma masiva con la API de importación de trabajos

Puede cargar muchos gemelos y relaciones en una sola llamada API mediante import Jobs API. Los gemelos y las relaciones creados con esta API pueden incluir opcionalmente la inicialización de sus propiedades. Para obtener instrucciones detalladas y ejemplos que usan esta API, consulte instrucciones de importación masiva para gemelos y relaciones.

Eliminar elementos de grafo

Para eliminar gemelos y relaciones específicos, use las API DigitalTwins Delete y DigitalTwins DeleteRelationship (también disponibles en como comandos de la CLI y llamadas del SDK).

Para eliminar todos los modelos, gemelos y relaciones de una instancia a la vez, use la API Eliminar trabajos.

Representaciones JSON de elementos de grafo

Los datos de gemelos digitales y los de relaciones se almacenan en formato JSON, es decir, cuando consulte el grafo de gemelos en la instancia de Azure Digital Twins, el resultado será una representación JSON de los gemelos digitales y las relaciones que ha creado.

Formato JSON de gemelo digital

Si se representa como un objeto JSON, un gemelo digital mostrará los campos siguientes:

A continuación se muestra un ejemplo de gemelo digital con formato como objeto JSON. Este gemelo tiene dos propiedades, Humidity y Temperature, y un componente denominado Thermostat.

{
    "$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 de relación

Si se representa como un objeto JSON, una relación de un gemelo digital mostrará los campos siguientes:

A continuación se muestra un ejemplo de relación formateada como objeto JSON:

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

Pasos siguientes

Consulte cómo administrar elementos de grafo con las API de Azure Digital Twins:

• Administración de gemelos digitales
• Administración del grafo y las relaciones de gemelos

O bien, consulte el grafo de gemelos de Azure Digital Twins para obtener información:

• Lenguaje de consulta