Ajouter des étiquettes à des jumeaux numériques

  • Article

Cet article explique comment ajouter différents types de balises aux modèles et aux jumeaux numériques, et comment effectuer des interrogations à l’aide des balises.

Vous pouvez utiliser le concept d’étiquettes pour identifier et catégoriser davantage vos jumeaux numériques. En particulier, les utilisateurs peuvent être amenés à répliquer des étiquettes à partir de systèmes existants, tels que les étiquettes Haystack, dans leurs instances Azure Digital Twins.

Ce document décrit les modèles qui peuvent être utilisés pour implémenter des étiquettes sur des jumeaux numériques.

Les étiquettes sont d’abord ajoutées en tant que propriétés dans le modèle qui décrit un jumeau numérique. Cette propriété est ensuite définie sur le jumeau lorsqu’il est créé en fonction du modèle. Après cela, les étiquettes peuvent être utilisées dans les requêtes pour identifier et filtrer vos jumeaux.

Étiquettes de marqueur

Une étiquette de marqueur est une chaîne simple utilisée pour marquer ou catégoriser un jumeau numérique, telle que « bleu » ou « rouge ». Cette chaîne est le nom de l’étiquette et les étiquettes de marqueur n’ont pas de valeur significative : l’étiquette est significative par sa seule présence (ou absence).

Ajouter des étiquettes de marqueur à un modèle

Les balises de marqueur sont modélisées sous la forme d’un mappage DTDL de string en boolean. La valeur booléenne mapValue est ignorée, car la présence de la balise est tout ce qui est importe.

Voici un extrait d’un modèle de jumeau qui implémente une balise de marqueur en tant que propriété :

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

Ajouter des balises de marqueur à des jumeaux numériques

Une fois que la propriété tags fait partie d’un modèle de jumeau numérique, vous pouvez définir la balise de marqueur dans le jumeau numérique en définissant la valeur de cette propriété.

Voici un exemple de code permettant de définir le marqueur tags pour un jumeau à l’aide du SDK .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);

Une fois que vous avez créé un jumeau avec des propriétés de balise en fonction de l’exemple ci-dessus, le jumeau se présente comme suit :

{
  "$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
  }
}

Conseil

Vous pouvez visualiser une représentation JSON de jumeau en l’interrogeantvia l’interface CLI ou les API.

Requête avec des balises de marqueur

Une fois que des balises ont été ajoutées aux jumeaux numériques, les balises peuvent être utilisées pour filtrer les jumeaux dans des requêtes.

Voici une requête permettant d’obtenir tous les jumeaux qui sont marqués comme rouges (avec la balise « red ») :

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

Vous pouvez également combiner des balises pour créer des requêtes plus complexes. Voici une requête permettant d’obtenir tous les jumeaux qui sont ronds et pas rouges :

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

Balises de valeur

Une balise de valeur est une paire clé-valeur utilisée pour attribuer une valeur à chaque balise, telle que "color": "blue" ou "color": "red". Une fois qu’une balise de valeur a été créée, vous pouvez également l’utiliser comme balise de marqueur en ignorant sa valeur.

Ajouter des balises de valeur à un modèle

Les balises de valeur sont modélisées sous la forme d’un mappage DTDL de string en string. Les éléments mapKey et mapValue sont tous les deux significatifs.

Voici un extrait d’un modèle de jumeau qui implémente une balise de valeur en tant que propriété :

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

Ajouter des balises de valeur à des jumeaux numériques

Comme avec les balises de marqueur, vous pouvez définir la balise de valeur dans un jumeau numérique en définissant la valeur de cette propriété tags à partir du modèle. Pour utiliser une balise de valeur comme balise de marqueur, vous pouvez définir le champ tagValue sur la valeur de chaîne vide ("").

Voici les corps JSON de deux jumeaux qui ont des balises de valeur pour représenter leurs tailles. Les jumeaux dans l’exemple ont également des balises de valeur pour « rouge » ou « violet » qui sont utilisées comme balises de marqueur.

Exemple Twin1, avec une balise de valeur pour Grande taille et une balise de marqueur « rouge » :

{
  "$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"
  }
}

Exemple Twin2, avec une balise de valeur de Petite taille et une balise de marqueur « violet » :

{
  "$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"
  }
}

Requête avec des balises de valeur

Comme avec les balises de marqueur, vous pouvez utiliser des balises de valeur pour filtrer les jumeaux dans des requêtes. Vous pouvez également utiliser des balises de valeur et des balises de marqueur ensemble.

Dans l’exemple ci-dessus, red est utilisé en tant que balise de marqueur. Voici une requête permettant d’obtenir tous les jumeaux qui sont rouges (marqués de la balise « red ») :

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

Voici une requête permettant d’obtenir toutes les entités qui sont de petite taille (balise de valeur) et pas rouges :

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

Étapes suivantes

Découvrez plus d’informations sur la conception et la gestion de modèles de jumeaux numériques :

Découvrez plus d’informations sur l’interrogation du graphe de jumeaux :