Condividi tramite


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: