Adicionar marcas aos gêmeos digitais
Este artigo descreve como adicionar diferentes tipos de marcas a modelos e gêmeos digitais e como consultar usando as marcas.
Você pode usar o conceito de marcas para identificar e categorizar ainda mais seus gêmeos digitais. Em particular, os usuários podem querer replicar marcas de sistemas existentes, como Marcas Haystack, em suas instâncias de Gêmeos Digitais do Azure.
Este documento descreve os padrões que podem ser usados para implementar marcas nos gêmeos digitais.
As marcas são adicionadas pela primeira vez como propriedades dentro do modelo que descrevem um gêmeo digital. Em seguida, essa propriedade é definida no gêmeo quando ele é criado com base no modelo. Depois disso, as marcas podem ser usadas em consultas para identificar e filtrar seus gêmeos.
Marcas de marcador
Uma marca 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 marca e as marcas de marcador não têm nenhum valor significativo, pois a marca é significativa apenas por sua presença (ou ausência).
Adicionar marcas de marcador ao modelo
Marcas de marcador são modeladas como um mapa de DTDL de string para boolean. O booliano mapValue é ignorado, já que a presença da marca é a única coisa importante.
Aqui está um trecho de um modelo de gêmeo que implementa uma marca de marcador como uma propriedade:
{
"@type": "Property",
"name": "tags",
"schema": {
"@type": "Map",
"mapKey": {
"name": "tagName",
"schema": "string"
},
"mapValue": {
"name": "tagValue",
"schema": "boolean"
}
}
},
Adicionar marcas de marcador aos gêmeos digitais
Uma vez que a propriedade tags fizer parte de um modelo de gêmeo digital, você pode definir a marca de marcador no gêmeo digital, definindo o valor dessa propriedade.
Confira um exemplo de código sobre como definir o 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á a seguinte 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
}
}
Dica
Você pode ver a representação JSON de um gêmeo consultando-a com o CLI ou as APIs.
Consulta com marcas de marcador
Uma vez que marcas tenham sido adicionadas aos gêmeos digitais, as marcas poderão ser usadas para filtrar o gêmeos em consultas.
Aqui está uma consulta para obter todos os gêmeos que foram marcados como "vermelho":
SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)
Também é possível combinar marcas 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)
Marcas de valor
Uma marca de valor é um par chave-valor usado para fornecer a cada marca um valor, como "color": "blue" ou "color": "red". Quando uma marca de valor é criada, ela também pode ser usada como uma marca de marcador, ignorando o valor da marca.
Adicionar marcas de valor ao modelo
Marcas de valor são modeladas como um mapa de DTDL de string para string. Tanto mapKey quanto mapValue são significativos.
Aqui está um trecho de um modelo de gêmeo que implementa uma marca de valor como uma propriedade:
{
"@type": "Property",
"name": "tags",
"schema": {
"@type": "Map",
"mapKey": {
"name": "tagName",
"schema": "string"
},
"mapValue": {
"name": "tagValue",
"schema": "string"
}
}
}
Adicionar marcas de valor a gêmeos digitais
Assim como nas marcas de marcador, você pode configurar a marca de valor em um gêmeo digital definindo o valor dessa propriedade tags do modelo. Para usar uma marca de valor como marca de marcador, você pode definir o campo tagValue como o valor da cadeia de caracteres vazia ("").
Abaixo estão os corpos JSON de dois gêmeos que têm marcas de valor para representar seus tamanhos. Os gêmeos no exemplo também têm marcas de valor para "vermelho" ou "roxo" que estão sendo usados como marcas de marcador.
Exemplo do Twin1, com uma marca de valor para tamanho grande e uma marca de marcador para "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 marca de valor para tamanho pequeno e uma marca de marcador para "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 marcas de valor
Assim como nas marcas de marcador, você pode usar marcas de valor para filtrar os gêmeos em consultas. Também é possível usar marcas de valor e marcas de marcador juntas.
No exemplo acima, red está sendo usado como uma marca de marcador. Lembre-se de que essa é 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óximas etapas
Leia mais sobre como criar e gerenciar modelos de gêmeo digital:
Leia mais sobre como consultar o grafo de gêmeos: