Compartir a través de

Adición de etiquetas a gemelos digitales

En este artículo se describe cómo agregar diferentes tipos de etiquetas a modelos y gemelos digitales y cómo realizar consultas mediante las etiquetas.

Puede usar el concepto de etiquetas para identificar y clasificar aún más los gemelos digitales. Por ejemplo, es posible que quiera replicar etiquetas de sistemas existentes, como Haystack Tags, en la instancia de Azure Digital Twins.

En este documento se describen los patrones que se pueden usar para implementar etiquetas en gemelos digitales.

Las etiquetas se agregan primero como propiedades dentro del modelo que describe un gemelo digital. A continuación, esa propiedad se establece en el gemelo cuando se crea en función del modelo. Después, las etiquetas se pueden usar en consultas para identificar y filtrar los gemelos.

Etiquetas de marcador

Una etiqueta de marcador es una cadena simple que se usa para marcar o clasificar un gemelo digital, como azul o rojo. Esta cadena es el nombre de la etiqueta y las etiquetas de marcador no tienen ningún valor significativo; la etiqueta es significativa solo por su presencia (o ausencia).

Adición de etiquetas de marcador al modelo

Las etiquetas de marcador se modelan como un mapa del Lenguaje de Definición de Gemelos Digitales (DTDL) de string a boolean. El valor booleano mapValue se omite, ya que la presencia de la etiqueta es todo lo que es importante.

Este es un extracto de un modelo gemelo que implementa una etiqueta de marcador como una propiedad:

{
      "@type": "Property",
      "name": "tags",
      "schema": {
        "@type": "Map",
        "mapKey": {
          "name": "tagName",
          "schema": "string"
        },
        "mapValue": {
          "name": "tagValue",
          "schema": "boolean"
        }
      }
    },

Adición de etiquetas de marcador a gemelos digitales

Cuando la propiedad tags ya forme parte de un modelo de gemelos digitales, configure el valor de esta propiedad para establecer la etiqueta del marcador en el gemelo digital.

Este es un ejemplo de código sobre cómo establecer un marcador tags para un gemelo mediante el SDK de .NET:

IDictionary<string, bool> tags = new Dictionary<string, bool>
{
    { "oceanview", true },
    { "VIP", true }
};
var twin = new BasicDigitalTwin
{
    Metadata = { ModelId = "dtmi:example:Room;1" },
    Contents =
    {
        { "Temperature", 75 },
        { "tags", tags },
    },
};
await client.CreateOrReplaceDigitalTwinAsync<BasicDigitalTwin>("myTwinID", twin);

Después de crear un gemelo con propiedades de etiqueta según el ejemplo anterior, el gemelo tendrá este aspecto:

{
  "$dtId": "myTwinID",
  "$etag": "W/\"e7429259-6833-46b4-b443-200a77a468c2\"",
  "$metadata": {
    "$model": "dtmi:example:Room;1",
    "Temperature": {
      "lastUpdateTime": "2021-08-03T14:24:42.0850614Z"
    },
    "tags": {
      "lastUpdateTime": "2021-08-03T14:24:42.0850614Z"
    }
  },
  "Temperature": 75,
  "tags": {
    "VIP": true,
    "oceanview": true
  }
}

Sugerencia

Puede ver la representación JSON de un gemelo haciéndole una consulta con la CLI o las API.

Consulta con etiquetas de marcador

Una vez que se agregan etiquetas a gemelos digitales, las etiquetas se pueden usar para filtrar los gemelos en las consultas.

Esta es una consulta para obtener todos los gemelos etiquetados como rojo:

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

También puede combinar etiquetas para consultas más complejas. Esta es una consulta para obtener todos los gemelos que son redondos y no son rojos:

SELECT * FROM DIGITALTWINS WHERE NOT IS_DEFINED(tags.red) AND IS_DEFINED(tags.round)

Etiquetas de valor

Una etiqueta de valor es un par clave-valor que se usa para asignar a cada etiqueta un valor, como "color": "blue" o "color": "red". Una vez creada una etiqueta de valor, también se puede usar como etiqueta de marcador ignorando el valor de la etiqueta.

Adición de etiquetas de valor al modelo

Las etiquetas de valor se modelan como un mapa DTDL de string a string. Tanto el mapKey como el mapValue son significativos.

Este es un extracto de un modelo gemelo que implementa una etiqueta de valor como una propiedad:

{
  "@type": "Property",
  "name": "tags",
  "schema": {
    "@type": "Map",
    "mapKey": {
      "name": "tagName",
      "schema": "string"
    },
    "mapValue": {
      "name": "tagValue",
      "schema": "string"
    }
  }
}

Adición de etiquetas de valor a gemelos digitales

Al igual que con las etiquetas de marcador, puede establecer la etiqueta de valor en un gemelo digital estableciendo el valor de esta propiedad tags del modelo. Para usar una etiqueta de valor como una etiqueta de marcador, puede establecer el campo tagValue en el valor de cadena vacío ("").

En el ejemplo siguiente se muestran los cuerpos JSON de dos gemelos que tienen etiquetas de valor para representar sus tamaños. Los gemelos del ejemplo también tienen etiquetas de valor para rojo o púrpura que se usan como etiquetas de marcador.

Ejemplo de Twin1, con una etiqueta de valor para el tamaño grande y una etiqueta de marcador de rojo:

{
  "$dtId": "Twin1",
  "$etag": "W/\"d3997593-cc5f-4d8a-8683-957becc2bcdd\"",
  "$metadata": {
    "$model": "dtmi:example:ValueTags;1",
    "tags": {
      "lastUpdateTime": "2021-08-03T14:43:02.3150852Z"
    }
  },
  "tags": {
    "red": "",
    "size": "large"
  }
}

Ejemplo de Twin2, con una etiqueta de valor para tamaño pequeño y una etiqueta de marcador de púrpura:

{
  "$dtId": "Twin2",
  "$etag": "W/\"e215e586-b14a-4234-8ddb-be69ebfef878\"",
  "$metadata": {
    "$model": "dtmi:example:ValueTags;1",
    "tags": {
      "lastUpdateTime": "2021-08-03T14:43:53.1517123Z"
    }
  },
  "tags": {
    "purple": "",
    "size": "small"
  }
}

Consulta con etiquetas de valor

Al igual que con las etiquetas de marcador, puede usar etiquetas de valor para filtrar los gemelos en las consultas. También puede usar etiquetas de valor y etiquetas de marcador juntas.

En el ejemplo anterior, red se usa como etiqueta de marcador. Recuerde que esta consulta obtiene todos los gemelos etiquetados como rojo:

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

Esta es una consulta para obtener todas las entidades pequeñas (etiqueta de valor) y no rojas:

SELECT * FROM DIGITALTWINS WHERE NOT IS_DEFINED(tags.red) AND tags.size = 'small'

Pasos siguientes