Aggiungere tag ai gemelli digitali
Questo articolo descrive come aggiungere diversi tipi di tag ai modelli e ai gemelli digitali e come eseguire query usando i tag.
È possibile usare il concetto di tag per identificare e classificare ulteriormente i gemelli digitali. In particolare, gli utenti possono voler replicare tag da sistemi esistenti, ad esempio Tag Haystack, all'interno delle istanze di Gemelli digitali di Azure.
Questo documento descrive i modelli che possono essere usati per implementare tag nei gemelli digitali.
I tag vengono prima aggiunti come proprietà all'interno del modello che descrive un gemello digitale. Tale proprietà viene quindi impostata sul gemello quando viene creata in base al modello. Successivamente, i tag possono essere usati nelle query per identificare e filtrare i gemelli.
Tag marcatore
Un tag marcatore è una stringa semplice usata per contrassegnare o classificare un gemello digitale, ad esempio "blu" o "rosso". Questa stringa è il nome del tag e i tag marcatore non hanno alcun valore significativo. Il tag è significativo solo per la sua presenza (o assenza).
Aggiungere tag di marcatore al modello
I tag marcatori vengono modellati come mappa DTDL da string a boolean. Il valore booleano mapValue viene ignorato, perché la presenza del tag è tutto ciò che è importante.
Ecco un estratto di un modello gemello che implementa un tag marcatore come proprietà:
{
"@type": "Property",
"name": "tags",
"schema": {
"@type": "Map",
"mapKey": {
"name": "tagName",
"schema": "string"
},
"mapValue": {
"name": "tagValue",
"schema": "boolean"
}
}
},
Aggiungere tag di marcatore a gemelli digitali
Quando la tags proprietà fa parte del modello di un gemello digitale, è possibile impostare il tag marcatore nel gemello digitale impostando il valore di questa proprietà.
Ecco un esempio di codice su come impostare l'indicatore tags per un gemello usando .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);
Dopo aver creato un gemello con proprietà tag in base all'esempio precedente, il gemello avrà un aspetto simile al seguente:
{
"$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
}
}
Suggerimento
È possibile visualizzare la rappresentazione JSON di un gemello eseguendo una query con l'interfaccia della riga di comando o le API.
Eseguire una query con tag marcatore
Dopo aver aggiunto tag ai gemelli digitali, i tag possono essere usati per filtrare i gemelli nelle query.
Ecco una query per ottenere tutti i gemelli contrassegnati come "rosso":
SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)
È anche possibile combinare tag per query più complesse. Ecco una query per ottenere tutti i gemelli arrotondati e non rossi:
SELECT * FROM DIGITALTWINS WHERE NOT IS_DEFINED(tags.red) AND IS_DEFINED(tags.round)
Tag valore
Un tag valore è una coppia chiave-valore usata per assegnare a ogni tag un valore, ad esempio "color": "blue" o "color": "red". Dopo aver creato un tag di valore, può essere usato anche come tag marcatore ignorando il valore del tag.
Aggiungere tag di valore al modello
I tag valore vengono modellati come mappa DTDL da string a string. Sia l'oggetto mapKey che il mapValue sono significativi.
Di seguito è riportato un estratto di un modello gemello che implementa un tag di valore come proprietà:
{
"@type": "Property",
"name": "tags",
"schema": {
"@type": "Map",
"mapKey": {
"name": "tagName",
"schema": "string"
},
"mapValue": {
"name": "tagValue",
"schema": "string"
}
}
}
Aggiungere tag di valore ai gemelli digitali
Come per i tag marcatore, è possibile impostare il tag valore in un gemello digitale impostando il valore di questa tags proprietà dal modello. Per usare un tag valore come tag marcatore, è possibile impostare il tagValue campo sul valore stringa vuoto ("").
Di seguito sono riportati i corpi JSON di due gemelli con tag di valore per rappresentare le dimensioni. I gemelli nell'esempio hanno anche tag di valore per "rosso" o "viola" usati come tag marcatore.
Esempio di Twin1, con un tag di valore per dimensioni grandi e un tag marcatore "red":
{
"$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"
}
}
Esempio di Twin2, con un tag di valore per le dimensioni ridotte e un tag marcatore "viola":
{
"$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"
}
}
Eseguire query con tag valore
Come per i tag marcatore, è possibile usare tag valore per filtrare i gemelli nelle query. È anche possibile usare tag di valore e tag marcatore insieme.
Nell'esempio precedente viene red usato come tag marcatore. Tenere presente che si tratta di una query per ottenere tutti i gemelli contrassegnati come "rosso":
SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)
Ecco una query per ottenere tutte le entità piccole (tag valore) e non rosse:
SELECT * FROM DIGITALTWINS WHERE NOT IS_DEFINED(tags.red) AND tags.size = 'small'
Passaggi successivi
Altre informazioni sulla progettazione e la gestione dei modelli di gemelli digitali:
Altre informazioni sull'esecuzione di query sul grafo del gemello: