Adicionar tags a gêmeos digitais
Este artigo descreve como adicionar diferentes tipos de tags a modelos e gêmeos digitais e como consultar usando as tags.
Você pode usar o conceito de tags para identificar e categorizar ainda mais seus gêmeos digitais. Em particular, os usuários podem querer replicar tags de sistemas existentes, como Haystack Tags, em suas instâncias do Azure Digital Twins.
Este documento descreve padrões que podem ser usados para implementar tags em gêmeos digitais.
As tags são adicionadas primeiro como propriedades dentro do modelo que descreve um gêmeo digital. Essa propriedade é então definida no gêmeo quando é criada com base no modelo. Depois disso, as tags podem ser usadas em consultas para identificar e filtrar seus gêmeos.
Tags de marcador
Uma tag de marcador é uma cadeia de caracteres simples que é usada para marcar ou categorizar um gêmeo digital, como "azul" ou "vermelho". Essa cadeia de caracteres é o nome da tag e as tags de marcador não têm valor significativo — a tag é significativa apenas por sua presença (ou ausência).
Adicionar tags de marcador ao modelo
As tags de marcador são modeladas como um Mapa DTDL de string até boolean. O booleano mapValue é ignorado, pois a presença da tag é tudo o que é importante.
Aqui está um trecho de um modelo gêmeo implementando uma tag de marcador como uma propriedade:
{
"@type": "Property",
"name": "tags",
"schema": {
"@type": "Map",
"mapKey": {
"name": "tagName",
"schema": "string"
},
"mapValue": {
"name": "tagValue",
"schema": "boolean"
}
}
},
Adicionar tags de marcador a gêmeos digitais
Uma vez que a propriedade faz parte do modelo de um gêmeo digital, você pode definir a tags marca de marcador no gêmeo digital definindo o valor dessa propriedade.
Aqui está um exemplo de código sobre como definir marcador tags para um gêmeo usando o SDK do .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);
Depois de criar um gêmeo com propriedades de tag de acordo com o exemplo acima, o gêmeo terá esta aparência:
{
"$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
}
}
Consulta com tags de marcador
Uma vez que as tags tenham sido adicionadas aos gêmeos digitais, elas podem ser usadas para filtrar os gêmeos em consultas.
Aqui está uma consulta para obter todos os gêmeos que foram marcados como "vermelhos":
SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)
Você também pode combinar tags para consultas mais complexas. Aqui está uma consulta para obter todos os gêmeos que são redondos, e não vermelhos:
SELECT * FROM DIGITALTWINS WHERE NOT IS_DEFINED(tags.red) AND IS_DEFINED(tags.round)
Tags de valor
Uma tag value é um par chave-valor que é usado para dar a cada tag um valor, como "color": "blue" ou "color": "red". Depois que uma tag de valor é criada, ela também pode ser usada como uma tag de marcador ignorando o valor da tag.
Adicionar tags de valor ao modelo
As tags de valor são modeladas como um Mapa DTDL de string até string. Tanto o como o mapKey mapValue são significativos.
Aqui está um trecho de um modelo gêmeo implementando uma marca de valor como uma propriedade:
{
"@type": "Property",
"name": "tags",
"schema": {
"@type": "Map",
"mapKey": {
"name": "tagName",
"schema": "string"
},
"mapValue": {
"name": "tagValue",
"schema": "string"
}
}
}
Adicione etiquetas de valor aos gêmeos digitais
Assim como acontece com as tags de marcador, você pode definir a tag de valor em um gêmeo digital definindo o valor dessa tags propriedade a partir do modelo. Para usar uma marca de valor como uma marca de marcador, você pode definir o campo como o tagValue valor de cadeia de caracteres vazia ("").
Abaixo estão os corpos JSON de dois gêmeos que têm tags de valor para representar seus tamanhos. Os gêmeos no exemplo também têm tags de valor para "vermelho" ou "roxo" que estão sendo usadas como tags de marcador.
Exemplo Twin1, com uma etiqueta de valor para tamanho grande e uma etiqueta de marcador de "vermelho":
{
"$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"
}
}
Exemplo Twin2, com uma etiqueta de valor para tamanho pequeno e uma etiqueta de marcador de "roxo":
{
"$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 com tags de valor
Assim como acontece com as tags de marcador, você pode usar tags de valor para filtrar os gêmeos em consultas. Você também pode usar tags de valor e tags de marcador juntas.
A partir do exemplo acima, red está sendo usado como uma tag de marcador. Lembre-se que esta é uma consulta para obter todos os gêmeos que foram marcados como "vermelho":
SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)
Aqui está uma consulta para obter todas as entidades que são pequenas (marca de valor) e não vermelhas:
SELECT * FROM DIGITALTWINS WHERE NOT IS_DEFINED(tags.red) AND tags.size = 'small'
Próximos passos
Leia mais sobre como projetar e gerenciar modelos de gêmeos digitais:
Leia mais sobre como consultar o gráfico gêmeo: