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, los mensajes de telemetría y las 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 relación contains dirigida a gemelos de tipo Room. Con esta definición, Azure Digital Twins le permitirá crear relaciones contains desde cualquier gemelo Floor en 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 de código 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(DigitalTwinsJsonPropertyNames.DigitalTwinMetadata)]
    public MyCustomDigitalTwinMetadata Metadata { get; set; } = new MyCustomDigitalTwinMetadata();

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

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

internal class MyCustomDigitalTwinMetadata
{
    [JsonPropertyName(DigitalTwinsJsonPropertyNames.MetadataModel)]
    public string ModelId { get; set; }

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

    [JsonPropertyName("humidity")]
    public DigitalTwinPropertyMetadata 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
        {
            Metadata = { ModelId = "dtmi:example:Room;1" },
            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 last updated on {response.Value.Metadata.Temperature.LastUpdatedOn}");
    }
}

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, vea la sección Creación de un gemelo digital de Administración de Digital Twins.

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

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

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 formateado como objeto JSON:

{
  "$dtId": "Cafe",
  "$etag": "W/\"e59ce8f5-03c0-4356-aea9-249ecbdc07f9\"",
  "Temperature": 72,
  "Location": {
    "x": 101,
    "y": 33
  },
  "component": {
    "TableOccupancy": 1,
    "$metadata": {
      "TableOccupancy": {
        "desiredValue": 1,
        "desiredVersion": 3,
        "ackVersion": 2,
        "ackCode": 200,
        "ackDescription": "OK"
      }
    }
  },
  "$metadata": {
    "$model": "dtmi:com:contoso:Room;1",
    "Temperature": {
      "desiredValue": 72,
      "desiredVersion": 5,
      "ackVersion": 4,
      "ackCode": 200,
      "ackDescription": "OK"
    },
    "Location": {
      "desiredValue": {
        "x": 101,
        "y": 33,
      },
      "desiredVersion": 8,
      "ackVersion": 8,
      "ackCode": 200,
      "ackDescription": "OK"
    }
  }
}

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 Digital Twins
• Administración del grafo de gemelos y las relaciones

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

• Lenguaje de consulta