Compartir a través de

Información sobre los modelos gemelos y su definición en Azure Digital Twins

  • Artículo

Una característica clave de Azure Digital Twins es la capacidad de definir su propio vocabulario y crear el grafo de gemelos en los términos de la empresa definidos de manera automática. Esta funcionalidad la ofrecen los modelos proporcionados por el usuario. Puede considerar los modelos como los nombres de una descripción de su mundo. Los modelos de Azure Digital Twins se representan mediante el lenguaje de definición de gemelos digitales (DTDL), que se basa en JSON-LD.

Un modelo es similar a una clase en un lenguaje de programación orientado a objetos, el que define una forma de datos para un concepto determinado en el entorno de trabajo real. Los modelos tienen nombres (como Room o TemperatureSensor) y contienen elementos como propiedades, componentes y relaciones que describen lo que hace este tipo de entidad en el entorno. Más adelante usará estos modelos para crear gemelos digitales que representen entidades específicas que cumplan con esta descripción de tipo.

Lenguaje de definición de gemelos digitales (DTDL) para modelos

Los modelos de Azure Digital Twins se definen con el lenguaje de definición de gemelos digitales (DTDL).

Puede ver la descripción completa del lenguaje para DTDL v3 en GitHub: Descripción del lenguaje de DTDL versión 3. En esta página se incluyen detalles y ejemplos de DTDL de referencia para ayudarle a empezar a escribir sus propios modelos de DTDL.

DTDL se basa en JSON-LD y es independiente del lenguaje de programación. DTDL no es exclusivo de Azure Digital Twins. También se usa para representar datos de dispositivo en otros servicios de IoT, como IoT Plug and Play.

En el resto de este artículo se resume el uso del lenguaje en Azure Digital Twins.

Versiones de DTDL compatibles

Azure Digital Twins admite las versiones 2 y 3 de DTDL (abreviadas en la documentación como v2 y v3, respectivamente). V3 es la opción recomendada para el modelado en Azure Digital Twins en función de sus funcionalidades expandidas, entre las que se incluyen:

Cuando estas características se describen en la documentación, están acompañadas de una nota de que solo están disponibles en DTDL v3. Para obtener una lista completa de las diferencias entre DTDL v2 y v3, consulte Descripción del lenguaje de DTDL v3: Cambios de la versión 2.

Azure Digital Twins también admite el uso de una combinación de modelos de v2 y v3 dentro de la misma instancia. Al usar modelos de ambas versiones en conjunto, tenga en cuenta las restricciones siguientes:

  • Una interfaz de v2 no puede extender una interfaz de v3 o tener un componente con una interfaz de v3 como su esquema.
  • Por el contrario, una interfaz de v3 puede extender una interfaz de v2 y una interfaz de v3 puede tener un componente con una interfaz de v2 como su esquema.
  • Las relaciones pueden apuntar en cualquier dirección, desde un origen de modelo de v2 a un destino de modelo de v3 o viceversa desde un origen de modelo de v3 a un destino de modelo de v2.

También puede migrar modelos de v2 existentes a v3. Para obtener instrucciones sobre cómo hacerlo, consulte Conversión de modelos v2 a v3.

Nota:

Actualmente, Azure Digital Twins Explorer es totalmente compatible con modelos DTDL v2 y admite funcionalidad limitada para los modelos DTDL v3.

Los modelos de DTDL v3 se pueden ver en el panel Modelos y los gemelos creados con modelos de DTDL v3 se pueden ver y editar (incluidos los que tienen propiedades de matriz). Sin embargo, los modelos DTDL v3 no se mostrarán en el panel Gráfico de modelos y no se pueden importar mediante Azure Digital Twins Explorer. Para importar modelos DTDL v3 a la instancia, use otra interfaz de desarrollador, como las API y los SDK o la CLI de Azure.

Introducción al modelo

Los modelos de tipo gemelo se pueden escribir en cualquier editor de texto. El lenguaje DTDL sigue la sintaxis JSON, por lo que debe almacenar los modelos con la extensión .json. El uso de la extensión JSON permitirá que muchos editores de texto de programación proporcionen comprobación de sintaxis básica y resaltado para los documentos de DTDL. También hay una extensión de DTDL disponible para Visual Studio Code.

Estos son los campos de una interfaz de modelo:

Campo Descripción
@id Un identificador del modelo de gemelo digital (DTMI) del modelo, en el formato dtmi:<domain>:<unique-model-identifier>;<model-version-number>. En DTDL v3, el número de versión se puede omitir o estructurar como un número de versión de dos partes (<major>.<minor>).
@type Identifica el tipo de información que se describe. En el caso de una interfaz, el tipo es Interface.
@context Establece el contexto del documento JSON. Los modelos deben usar dtmi:dtdl:context;2 para DTDL v2 o dtmi:dtdl:context;3 para DTDL v3. Los modelos de DTDL v3 también pueden asignar un nombre a extensiones de características adicionales en este campo.
displayName [opcional] Le da la opción de definir un nombre descriptivo para el modelo. Si no usa este campo, el modelo usará su valor DTMI completo.
contents Todos los datos restantes de la interfaz se colocan aquí, como una matriz de definiciones de atributo. Cada atributo debe proporcionar un valor de @type (Property, Relationship o Component) para identificar el tipo de información de la interfaz que describe y, después, un conjunto de propiedades que definen el atributo real. En la sección siguiente se describen los atributos del modelo en detalle.

Este es un ejemplo de un modelo DTDL básico. Este modelo describe un modelo Home, con un valor de property como identificador. El modelo Home también define relationship con un modelo Floor, que se puede usar para indicar que un gemelo de Home está conectado a determinados gemelos de 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"
    }
  ]
}

Atributos del modelo

La información principal sobre un modelo se proporciona mediante sus atributos, que se definen dentro de la sección contents de la interfaz del modelo.

Estos son los atributos disponibles en DTDL que se admiten en Azure Digital Twins. Una interfaz de modelo de DTDL que se usa para Azure Digital Twins puede contener cero, uno o muchos de cada uno de los campos siguientes:

  • Propiedad: las propiedades son campos de datos que representan el estado de una entidad (como las propiedades de muchos lenguajes de programación orientados a objetos). Las propiedades tienen almacenamiento de seguridad y se pueden leer en cualquier momento. Para obtener más información, consulte Propiedades a continuación.

  • Relación: las relaciones permiten representar cómo un gemelo digital puede estar implicado con otros gemelos digitales. Las relaciones pueden representar distintos significados semánticos, como contains ("floor contains room"), cools ("hvac cools room"), isBilledTo ("compressor is billed to user"), y así sucesivamente. Las relaciones permiten que la solución proporcione un grafo de las entidades interrelacionadas. Las relaciones también pueden tener propiedades propias. Para obtener más información, consulte Relaciones a continuación.

  • Componente: los componentes permiten compilar la interfaz de modelo como un ensamblado de otras interfaces, si lo desea. Un ejemplo de componente es una interfaz frontCamera (y otra interfaz de componente backCamera) que se usa para definir un modelo para un teléfono. Primero defina una interfaz para cámaraFrontal como si fuera su propio modelo y, luego, puede hacer referencia a ella al definir el Teléfono.

    Use un componente para describir algo que es una parte integral de la solución, pero no necesita una identidad independiente y no es necesario crearla, eliminarla ni reorganizarla en el grafo de gemelos de forma independiente. Si quiere que las entidades tengan existencias independientes en el grafo de gemelos, represéntelas como gemelos digitales independientes de distintos modelos conectadas por relaciones.

    Sugerencia

    Los componentes también se pueden usar para la organización, a fin de agrupar conjuntos de propiedades relacionadas dentro de una interfaz de modelo. En esta situación, puede considerar cada componente como un espacio de nombres o "carpeta" dentro de la interfaz.

    Para más información, consulte la sección Componentes a continuación.

La Descripción del lenguaje de DTDL v3 también define comandos y telemetría, pero ninguno de estos se usa en Azure Digital Twins. Los comandos no se admiten y la telemetría (aunque se permite en las definiciones de modelo) no tiene ningún caso de uso único en el modelado de Azure Digital Twins. En lugar de usar la telemetría de DTDL, debe usar las propiedades de DTDL para almacenar información de estado del gemelo.

Nota:

Aunque no es necesario definir campos de telemetría en los modelos de DTDL para almacenar datos de dispositivo entrantes, Azure Digital Twins puede emitir eventos como telemetría mediante la API SendTelemetry. Esto desencadena un evento de mensajes de telemetría de gemelo digital que un controlador de eventos puede recibir para realizar acciones en otros gemelos o desencadenar servicios de bajada.

Propiedades

En esta sección se explican con mayor detalle las propiedades en los modelos de DTDL.

Para obtener información completa sobre los campos que pueden aparecer como parte de una propiedad, consulte Propiedad en la Description del lenguaje de DTDL v3.

Nota:

El atributo DTDL writable para las propiedades no se admite actualmente en Azure Digital Twins. Se puede agregar al modelo, pero Azure Digital Twins no lo aplicará. Para más información, consulte Notas de DTDL específicas del servicio.

Esquema

Según DTDL, el esquema de los atributos de propiedad puede ser de tipos primitivos estándar (integer, double, string y boolean) y de otros tipos como dateTime y duration.

Además de los tipos primitivos, los campos de propiedades pueden tener estos tipos complejos:

  • Object
  • Map
  • Enum
  • Array, solo en DTDL v3. No se admite el tipo Array para las propiedades en DTDL v2.

También pueden ser tipos semánticos, que permiten anotar valores con unidades. En DTDL v2, los tipos semánticos se admiten de manera nativa; en DTDL v3, puede incluirlos con una extensión de características.

Ejemplo de una propiedad básica

Este es un ejemplo básico de propiedad en un modelo de DTDL. En este ejemplo se muestra la propiedad ID de un elemento 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"
    }
  ]
}

Ejemplo de tipo de objeto complejo

Las propiedades pueden ser de tipos complejos, incluido un tipo Object.

En el ejemplo siguiente se muestra otra versión del modelo Home, con una propiedad para su dirección. address es un objeto, con sus propios campos para la calle, la ciudad, el estado y el código postal.

{
  "@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"
        }
      ]
    }
  ]
}

Ejemplo de tipo semántico de DTDL v2

Los tipos semánticos sirven para expresar un valor con una unidad. Las propiedades de Azure Digital Twins pueden usar cualquiera de los tipos semánticos admitidos por DTDL.

En DTDL v2, se admiten de manera nativa los tipos semánticos. Para obtener más información sobre los tipos semánticos en DTDL v2, consulte Tipos semánticos en la Descripción del lenguaje de DTDL v2. Para obtener información sobre los tipos semánticos en DTDL v3, consulte la extensión de características QuantitativeTypes de DTDL v3.

En el ejemplo siguiente se muestra un modelo de sensores de DTDL v2 con propiedades de tipo semántico para Humedad y 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" debe ser el primer elemento de la matriz @type, seguido del tipo semántico. De lo contrario, es posible que el campo no esté visible en Azure Digital Twins Explorer.

Relaciones

En esta sección se explican con mayor detalle las relaciones en los modelos de DTDL.

Para obtener una lista completa de los campos que pueden aparecer como parte de una relación, consulte Relación en la Descripción del lenguaje de DTDL v3.

Nota:

Los atributos DTDL writable, minMultiplicity y maxMultiplicity de las relaciones no se admiten actualmente en Azure Digital Twins. Se pueden agregar al modelo, pero Azure Digital Twins no los aplicará. Para más información, consulte Notas de DTDL específicas del servicio.

Ejemplo básico de relación

Este es un ejemplo básico de una relación en un modelo de DTDL. En este ejemplo se muestra una relación en un modelo Home que le permite conectarse a un modelo 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:

En las relaciones, @id es un campo opcional. Si no se proporciona el valor de @id, el procesador de la interfaz de gemelo digital asignará uno.

Relaciones con y sin destino

Las relaciones se pueden definir con o sin un destino. Los destinos especifica los tipos de gemelos a los que puede acceder la relación. Por ejemplo, puede incluir un destino para especificar que un modelo Home solo puede tener una relación rel_has_floors con gemelos de Floor.

A veces, es posible que quiera definir una relación sin un destino concreto, con el fin de que esta pueda conectarse a muchos tipos diferentes de gemelos.

Este es un ejemplo de una relación en un modelo de DTDL que no tiene un destino. En este ejemplo, la relación se usa para definir qué sensores podría tener el modelo Sala y la relación puede conectarse a cualquier 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"
    }
  ]
},

Propiedades de las relaciones

DTDL también permite que las relaciones tengan propiedades propias. Al definir una relación dentro de un modelo de DTDL, la relación puede tener su propio campo properties donde puede definir propiedades personalizadas para describir el estado específico de la relación.

En el siguiente ejemplo se muestra otra versión del modelo Home, en el que la relación rel_has_floors tiene una propiedad que representa cuándo fue la última vez que se ocupó el modelo Floor relacionado.

{
  "@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"
        }
      ]
    }
  ]
}

Componentes

En esta sección se explican con mayor detalle los componentes en los modelos de DTDL.

Para obtener una lista completa de los campos que pueden aparecer como parte de un componente, consulte Componente en la Descripción del lenguaje de DTDL v3.

Ejemplo de componente básico

Este es un ejemplo básico de un componente en un modelo de DTDL. En este ejemplo se muestra un modelo Room que usa un modelo de termostato como 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"
      }
    ]
  }
]

Si otros modelos de esta solución también deben contener un termostato, pueden hacer referencia al mismo modelo de termostato que un componente en sus propias definiciones, al igual que hace Room.

Importante

La interfaz del componente (el termostato en el ejemplo anterior) debe definirse en la misma matriz que cualquier interfaz que lo use (Room en el ejemplo anterior) para que se pueda encontrar la referencia del componente.

Herencia de modelo

En algunas ocasiones, puede que quiera especializar aún más un modelo. Por ejemplo, podría resultar útil tener un modelo genérico Sala y las variantes especializadas SalaDeConferencias y Gimnasio. Para expresar la especialización, DTDL admite la herencia. Las interfaces pueden heredar de una o varias interfaces. Para ello, tiene que agregar un campo extends al modelo.

La sección extends es un nombre de interfaz o una matriz de nombres de interfaz (lo que permite que la interfaz de extensión herede de varios modelos primarios). Un único elemento primario puede servir como modelo base para varias interfaces de extensión.

Nota:

En DTDL v2, cada extends puede tener como máximo dos interfaces enumeradas. En DTDL v3, no hay ningún límite en el número de valores inmediatos de un extends.

En DTDL v2 y v3, el límite total de profundidad de una jerarquía extends es 10.

En el ejemplo siguiente se recrea el modelo Home del ejemplo de DTDL anterior como subtipo de un modelo "central" mayor. Primero se define el modelo (Core) y, después, el modelo secundario (Home) se basa en él mediante 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": [
    {

En este caso, Core aporta un identificador y un nombre a Home. Otros modelos también pueden extender el modelo Core para obtener también estas propiedades. Este es un modelo Room que extiende la misma interfaz primaria:

{
  "@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",

Una vez que se aplica la herencia, la interfaz de extensión expone todas las propiedades de toda la cadena de herencia.

La interfaz de extensión no puede cambiar ninguna de las definiciones de las interfaces primarias; solo puede agregar a ellas. Tampoco puede volver a definir una funcionalidad que ya esté definida en ninguna de sus interfaces primarias (incluso si las funcionalidades están definidas para ser iguales). Por ejemplo, si una interfaz primaria define una propiedad double como mass, la interfaz de extensión no puede contener una declaración de mass, incluso si también es double.

Extensiones de características de DTDL v3

DTDL v3 permite extensiones de lenguaje que definen clases de metamodelos adicionales, que puede usar para escribir modelos más enriquecidos. En esta sección se describen las clases de extensión de características que puede usar para agregar características no básicas a los modelos de DTDL v3.

Cada extensión de características se identifica mediante su especificador de contexto, que es un valor único del identificador de modelo de gemelo digital (DTMI). Para habilitar una extensión de características en un modelo, agregue el especificador de contexto de la extensión al campo @context del modelo (junto con el especificador de contexto de DTDL general de dtmi:dtdl:context;3). Puede agregar varias extensiones de características al mismo modelo.

Este es un ejemplo del aspecto que podría tener ese campo @context con las extensiones de características. El fragmento siguiente procede de un modelo que usa la extensión QuantitativeTypes y la extensión Annotation.

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

Después de agregar una extensión de características a un modelo, tendrá acceso a los tipos adjuntos de esa extensión dentro del modelo. Puede agregar tipos adjuntos al campo @type de un elemento de DTDL para proporcionar a los elementos funcionalidades adicionales. El tipo adjunto puede agregar propiedades adicionales al elemento.

Por ejemplo, este es un extracto de un modelo que usa la extensión Annotation. Esta extensión tiene un tipo adjunto denominado ValueAnnotation, que se agrega en el ejemplo siguiente a un elemento de propiedad. Agregar este tipo adjunto al elemento de propiedad permite que el elemento tenga un campo annotates adicional, que se usa para indicar otra propiedad anotada por este elemento.

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

En el resto de esta sección se explica la extensión Annotation y otras extensiones de características de DTDL v3 con más detalle.

Extensión Annotation

La extensión Annotation se usa para agregar metadatos personalizados a un elemento de propiedad en un modelo de DTDL v3. Su especificador de contexto es dtmi:dtdl:extension:annotation;1.

Esta extensión incluye el tipo adjunto ValueAnnotation, que se puede agregar a un elemento de propiedad de DTDL. El tipo ValueAnnotation agrega un campo al elemento, annotates, que permite asignar un nombre a otra propiedad anotada por el elemento actual.

Para obtener más detalles y ejemplos de esta extensión, consulte Extensión Annotation en la Descripción del lenguaje de DTDL v3.

Extensión Historization

La extensión Historization se usa para designar una propiedad en un modelo de DTDL v3 como algo que se debe historizar (lo que significa que se debe registrar la secuencia histórica de sus valores, junto con momentos en los que cambian los valores). Su especificador de contexto es dtmi:dtdl:extension:historization;1.

Esta extensión incluye el tipo adjunto Historized, que se puede agregar como un cotipo a un elemento de propiedad de DTDL para indicar que el servicio debe conservar los valores históricos del elemento y hacer que estén disponibles para realizar consultas y análisis. El tipo adjunto Historized no agrega ningún campo al elemento.

Para obtener más detalles y ejemplos de esta extensión, consulte Extensión Historization en la Descripción del lenguaje de DTDL v3.

Extensión de invalidación

La extensión de invalidación se usa para invalidar una propiedad en un modelo de DTDL V3 con un valor de instancia. Se usa en combinación con la extensión de anotación y su especificador de contexto es dtmi:dtdl:extension:overriding;1.

Esta extensión incluye el tipo adjunto Override, que se puede agregar a una propiedad DTDL que también se escribe con ValueAnnotation (desde la extensión de anotación). El tipo Override agrega un campo al elemento, overrides, que permite asignar un nombre a un campo en el elemento anotado que el valor del elemento actual invalidará.

Para obtener más detalles y ejemplos de esta extensión, consulte Extensión de invalidación en la Descripción del lenguaje de DTDL v3.

Extensión QuantitativeTypes

La extensión QuantitativeTypes se usa para habilitar tipos semánticos, tipos de unidad y unidades en un modelo de DTDL v3. Su especificador de contexto es dtmi:dtdl:extension:quantitativeTypes;1.

Esta extensión permite el uso de muchos tipos semánticos como tipos adjuntos, que se pueden agregar a CommandRequest, un campo, un valor MapValue o una propiedad en DTDL v3. Los tipos semánticos agregan un campo al elemento, unit, que acepta una unidad válida que corresponde al tipo semántico.

Para obtener más información sobre la extensión, incluidos ejemplos y una lista completa de las unidades y tipos semánticos admitidos, consulte Extensión QuantitativeTypes en la Descripción del lenguaje de DTDL v3.

Notas de DTDL específicas del servicio

No todos los servicios que usan DTDL implementan las mismas características exactas de DTDL. Hay algunas características de DTDL que la instancia de Azure Digital Twins actualmente no admite, entre las que se incluyen:

  • Comandos de DTDL
  • Atributo writable en propiedades o relaciones. Aunque este atributo puede establecerse según las especificaciones de DTDL, Azure Digital Twins no usa el valor. En su lugar, estos atributos siempre se tratan como grabables por parte de los clientes externos que tienen permisos de escritura generales en el servicio Azure Digital Twins.
  • Propiedades minMultiplicity y maxMultiplicity de las relaciones. Aunque estos atributos se pueden establecer según las especificaciones de DTDL, los valores no se aplican Azure Digital Twins.

Para que un modelo de DTDL sea compatible con Azure Digital Twins, tiene que cumplir estos requisitos:

  • Todos los elementos de DTDL de nivel superior de un modelo deben ser de tipo Interface. El motivo para este requisito es que las API del modelo de Azure Digital Twins pueden recibir objetos JSON que representan una interfaz o una matriz de interfaces. Como resultado, no se permite ningún otro tipo de elemento de DTDL en el nivel superior.
  • DTDL para Azure Digital Twins no debe definir ningún comando.
  • Azure Digital Twins solo permite un único nivel de anidamiento de componentes; es decir, una interfaz que se usa como componente no puede tener ningún componente en sí.
  • Las interfaces no pueden ser definidas insertadas en línea dentro de otras interfaces de DTDL, sino que deben definirse como entidades independientes de nivel superior con sus propios identificadores. A continuación, cuando otra interfaz quiere incluir esa interfaz como componente o a través de la herencia, puede hacer referencia a su identificador.

Herramientas de creación de modelos y prácticas recomendadas

En esta sección se describen consideraciones y recomendaciones adicionales para el modelado.

Uso de ontologías existentes estándar del sector

Una ontología es un conjunto de modelos que describen de manera completa un dominio determinado, como la construcción, la creación de estructuras, los sistemas IoT, las ciudades inteligentes, las redes eléctricas, el contenido web, etc.

Si la solución es para un determinado sector que usa cualquier tipo de estándar de modelado, considere la posibilidad de empezar con un conjunto preexistente de modelos diseñados para el sector en lugar de diseñar los modelos desde cero. Microsoft se ha asociado con expertos en dominios para crear ontologías de modelos de DTDL basados en estándares del sector, con el fin de ayudar a minimizar la reinvención y alentar la coherencia y la simplificación en las soluciones del sector. Puede leer más sobre estos ontologías, incluido cómo usarlas y qué ontologías están disponibles ahora, en ¿Qué es una ontología?.

Consideración de las implicaciones de las consultas

Al diseñar modelos para que reflejen las entidades de su entorno, puede resultar útil realizar una búsqueda anticipada y considerar las implicaciones de consulta del diseño. Si lo desea, puede diseñar las propiedades de forma que se evite que grandes conjuntos de resultados atraviesen un grafo. También puede crear modelos de relaciones que será preciso que se respondan en una consulta individual como relaciones de nivel único.

Validación de modelos

Después de crear un modelo, se recomienda validar los modelos sin conexión antes de cargarlos en la instancia de Azure Digital Twins.

Para ayudarle a validar los modelos, se proporciona una biblioteca de análisis de DTDL del lado cliente de .NET en NuGet: DTDLParser. Puede usar la biblioteca del analizador directamente en el código de C#. También puede ver el uso de ejemplo del analizador en DTDLParserResolveSample en GitHub.

Carga y eliminación de modelos en masa

Una vez que haya terminado de crear, extender o seleccionar los modelos, debe cargarlos en la instancia de Azure Digital Twins para que estén disponibles para su uso en la solución.

Puede cargar muchos modelos en una sola llamada API mediante la API de trabajos de importación. La API puede aceptar simultáneamente hasta el límite de Azure Digital Twins para el número de modelos de una instancia y reordena automáticamente los modelos si es necesario para resolver las dependencias entre ellos. Para obtener instrucciones detalladas y ejemplos que usan esta API, consulte instrucciones de importación en bloque para modelos.

Una alternativa a la API de trabajos de importación es el ejemplo del cargador de modelos, que usa las API de modelo individual para cargar varios archivos de modelo a la vez. El ejemplo también implementa la reordenación automática para resolver las dependencias del modelo. Actualmente solo funciona con la versión 2 de DTDL.

Si necesita eliminar todos los modelos de una instancia de Azure Digital Twins a la vez, puede usar el Eliminador de modelos de ejemplo. Este es un proyecto que contiene lógica recursiva para controlar las dependencias del modelo a través del proceso de eliminación. Actualmente solo funciona con la versión 2 de DTDL.

O bien, si desea borrar los datos de una instancia mediante la eliminación de todos los modelos junto con todos los gemelos y las relaciones, puede usar la API de trabajos de eliminación.

Visualización de modelos

Una vez que haya cargado modelos en la instancia de Azure Digital Twins, puede usar Azure Digital Twins Explorer para verlos. El explorador contiene una lista de todos los modelos de la instancia, así como un grafo de modelos que ilustra cómo se relacionan entre sí, incluidas las relaciones de herencia y modelo.

Nota:

Actualmente, Azure Digital Twins Explorer es totalmente compatible con modelos DTDL v2 y admite funcionalidad limitada para los modelos DTDL v3.

Los modelos de DTDL v3 se pueden ver en el panel Modelos y los gemelos creados con modelos de DTDL v3 se pueden ver y editar (incluidos los que tienen propiedades de matriz). Sin embargo, los modelos DTDL v3 no se mostrarán en el panel Gráfico de modelos y no se pueden importar mediante Azure Digital Twins Explorer. Para importar modelos DTDL v3 a la instancia, use otra interfaz de desarrollador, como las API y los SDK o la CLI de Azure.

El ejemplo siguiente muestra el aspecto que podría tener el grafo de modelos:

Captura de pantalla de Azure Digital Twins Explorer. El panel Grafo de modelos está resaltado.

Para obtener más información sobre la experiencia de modelos en Azure Digital Twins Explorer, consulte Exploración de modelos y grafo de modelos.

Pasos siguientes