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.

Sugerencia

"Azure Digital Twins" hace referencia a este servicio de Azure en conjunto. "Gemelos digitales" o simplemente "gemelos" hace referencia a nodos gemelos individuales dentro de la instancia del servicio.

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

Nota:

Los gemelos digitales de Azure Digital Twins son diferentes de los dispositivos gemelos de IoT Hub. Los dispositivos gemelos de IoT Hub a menudo se centran en describir los aspectos y funcionalidades de un dispositivo, mientras que los gemelos de Azure Digital Twins son representaciones conceptuales que pueden almacenar información definida por el usuario sobre un dispositivo o muchos dispositivos relacionados.

Los dispositivos en IoT Hub se pueden conectar a Azure Digital Twins como parte de una solución global que representa los dispositivos entre los servicios.

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.

Nota:

Aunque las propiedades del gemelo se tratan como opcionales y, por lo tanto, no tienen que inicializarse, los componentes del gemelo deben establecerse cuando este se crea. Aunque pueden ser objetos vacíos, los componentes en sí deben existir.

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:

Nombre del campo	Descripción
$dtId	Cadena proporcionada por el usuario que representa el identificador del gemelo digital.
$etag	Campo HTTP estándar asignado por el servidor web.
$metadata.$model	Identificador de la interfaz del modelo que caracteriza al gemelo digital.
$metadata.<property-name>	Otra información de metadatos sobre las propiedades del gemelo digital.
$metadata.<property-name>.lastUpdateTime	Fecha y hora en que Azure Digital Twins procesó el mensaje de actualización de la propiedad.
$metadata.<property-name>.sourceTime	Propiedad opcional que se puede escribir que representa la marca de tiempo cuando se observó la actualización de la propiedad en un entorno real. Esta propiedad solo se puede escribir con la versión 31-05-2022 de los SDK o las API de Azure Digital Twins, y el valor debe cumplir el formato de fecha y hora de la normativa ISO 8601. Para obtener más información sobre cómo actualizar esta propiedad, vea Actualizar el valor sourceTime de una propiedad.
<property-name>	Valor de una propiedad en formato JSON (string, tipo de número u objeto).
$relationships	Dirección URL de la ruta de acceso a la colección de relaciones. Este campo no está presente si el gemelo digital no tiene bordes de relación salientes.
<component-name>	Objeto JSON que contiene los valores de propiedad y los metadatos del componente, similares a los del objeto raíz. Este objeto existe aunque el componente no tenga propiedades.
<component-name>.$metadata	Información de metadatos del componente, similar al nivel de raíz $metadata.
<component-name>.<property-name>	Valor de la propiedad del componente en formato JSON (string, tipo de número u objeto).

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:

Nombre del campo	Descripción
$relationshipId	Cadena proporcionada por el usuario que representa el identificador de esta relación. Esta cadena es única en el contexto del gemelo digital de origen, lo que también significa que sourceId + relationshipId es único en el contexto de la instancia de Azure Digital Twins.
$etag	Campo HTTP estándar asignado por el servidor web.
$sourceId	Identificador del gemelo digital de origen.
$targetId	Identificador del gemelo digital de destino.
$relationshipName	El nombre de la relación
<property-name>	[Opcional] Valor de una propiedad de esta relación en formato JSON (string, tipo de número u objeto).

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