Lägga till taggar i digitala tvillingar

Artikel
06/30/2023

Den här artikeln beskriver hur du lägger till olika typer av taggar i modeller och digitala tvillingar och hur du frågar med hjälp av taggarna.

Du kan använda begreppet taggar för att ytterligare identifiera och kategorisera dina digitala tvillingar. I synnerhet kan användare vilja replikera taggar från befintliga system, till exempel Haystack-taggar, i sina Azure Digital Twins-instanser.

Det här dokumentet beskriver mönster som kan användas för att implementera taggar på digitala tvillingar.

Taggar läggs först till som egenskaper i modellen som beskriver en digital tvilling. Den egenskapen anges sedan på tvillingen när den skapas baserat på modellen. Därefter kan taggarna användas i frågor för att identifiera och filtrera dina tvillingar.

Markörtaggar

En markörtagg är en enkel sträng som används för att markera eller kategorisera en digital tvilling, till exempel "blå" eller "röd". Den här strängen är taggens namn och markörtaggar har inget meningsfullt värde – taggen är betydande bara av dess närvaro (eller frånvaro).

Lägga till markörtaggar i modellen

Markörtaggar modelleras som en DTDL-karta från string till boolean. Det booleska mapValue objektet ignoreras eftersom taggens närvaro är allt som är viktigt.

Här är ett utdrag från en tvillingmodell som implementerar en markörtagg som en egenskap:

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

Lägga till markörtaggar till digitala tvillingar

När egenskapen tags är en del av en digital tvillings modell kan du ange markörtaggen i den digitala tvillingen genom att ange värdet för den här egenskapen.

Här är ett kodexempel på hur du anger markör tags för en tvilling med hjälp av .NET SDK:

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

När du har skapat en tvilling med taggegenskaper enligt exemplet ovan ser tvillingen ut så här:

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

Dricks

Du kan se en tvillings JSON-representation genom att fråga den med CLI eller API:er.

Fråga med markörtaggar

När taggar har lagts till i digitala tvillingar kan taggarna användas för att filtrera tvillingarna i frågor.

Här är en fråga för att hämta alla tvillingar som har taggats som "röda":

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

Du kan också kombinera taggar för mer komplexa frågor. Här är en fråga för att hämta alla tvillingar som är runda och inte röda:

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

Värdetaggar

En värdetagg är ett nyckel/värde-par som används för att ge varje tagg ett värde, till exempel "color": "blue" eller "color": "red". När en värdetagg har skapats kan den också användas som en markörtagg genom att ignorera taggens värde.

Lägga till värdetaggar i modellen

Värdetaggar modelleras som en DTDL-karta från string till string. mapKey Både och mapValue är betydande.

Här är ett utdrag från en tvillingmodell som implementerar en värdetagg som en egenskap:

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

Lägga till värdetaggar till digitala tvillingar

Precis som med markörtaggar kan du ange värdetaggen i en digital tvilling genom att ange värdet för den här tags egenskapen från modellen. Om du vill använda en värdetagg som en markörtagg kan du ange tagValue fältet till det tomma strängvärdet ("").

Nedan visas JSON-organen för två tvillingar som har värdetaggar som representerar deras storlekar. Tvillingarna i exemplet har också värdetaggar för "röd" eller "lila" som används som markörtaggar.

Exempel twin1, med en värdetagg för stor storlek och en markörtagg med "röd":

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

Exempel på Twin2, med en värdetagg för liten storlek och en markörtagg med "lila":

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

Fråga med värdetaggar

Precis som med markörtaggar kan du använda värdetaggar för att filtrera tvillingarna i frågor. Du kan också använda värdetaggar och markörtaggar tillsammans.

I exemplet ovan red används som en markörtagg. Kom ihåg att det här är en fråga för att hämta alla tvillingar som har taggats som "röda":

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

Här är en fråga för att hämta alla entiteter som är små (värdetaggen) och inte röda:

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

Nästa steg

Läs mer om att utforma och hantera digitala tvillingmodeller:

Hantera DTDL-modeller

Läs mer om att fråga tvillingdiagrammet:

Fråga tvillingdiagrammet

Dela via