Dodawanie tagów do cyfrowych reprezentacji bliźniaczych

W tym artykule opisano sposób dodawania różnych typów tagów do modeli i cyfrowych reprezentacji bliźniaczych oraz wykonywania zapytań przy użyciu tagów.

Możesz użyć koncepcji tagów, aby dalej identyfikować i kategoryzować cyfrowe reprezentacje bliźniacze. W szczególności użytkownicy mogą chcieć replikować tagi z istniejących systemów, takich jak tagi Haystack, w wystąpieniach usługi Azure Digital Twins.

W tym dokumencie opisano wzorce, których można użyć do implementowania tagów w cyfrowych reprezentacjach bliźniaczych.

Tagi są najpierw dodawane jako właściwości w modelu , który opisuje cyfrową reprezentację bliźniaczą. Ta właściwość jest następnie ustawiana na bliźniaczej reprezentacji, gdy jest tworzona na podstawie modelu. Następnie tagi mogą być używane w zapytaniach do identyfikowania i filtrowania reprezentacji bliźniaczych.

Znaczniki

Tag znacznika to prosty ciąg, który służy do oznaczania lub kategoryzowania cyfrowej reprezentacji bliźniaczej, takiej jak "niebieski" lub "czerwony". Ten ciąg jest nazwą tagu, a tagi znaczników nie mają znaczącej wartości — tag jest znaczący tylko przez jego obecność (lub nieobecność).

Dodawanie tagów znaczników do modelu

Tagi znaczników są modelowane jako mapa DTDL z string do boolean. Wartość logiczna mapValue jest ignorowana, ponieważ obecność tagu jest ważna.

Oto fragment modelu bliźniaczej reprezentacji implementowania tagu znacznika jako właściwości:

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

Dodawanie tagów znaczników do cyfrowych reprezentacji bliźniaczych

tags Gdy właściwość jest częścią modelu cyfrowej reprezentacji bliźniaczej, możesz ustawić tag znacznika w cyfrowej reprezentacji bliźniaczej, ustawiając wartość tej właściwości.

Oto przykładowy kod dotyczący ustawiania znacznika tags dla bliźniaczej reprezentacji przy użyciu zestawu SDK platformy .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);

Po utworzeniu bliźniaczej reprezentacji z właściwościami tagu zgodnie z powyższym przykładem bliźniacy będą wyglądać następująco:

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

Napiwek

Reprezentację JSON bliźniaczej reprezentacji bliźniaczej reprezentacji można wyświetlić, wykonując zapytanie względem interfejsu wiersza polecenia lub interfejsów API.

Wykonywanie zapytań przy użyciu tagów znaczników

Po dodaniu tagów do cyfrowych reprezentacji bliźniaczych tagi mogą służyć do filtrowania bliźniaczych reprezentacji w zapytaniach.

Oto zapytanie umożliwiające pobranie wszystkich reprezentacji bliźniaczych, które zostały oznaczone jako "czerwone":

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

Można również łączyć tagi dla bardziej złożonych zapytań. Oto zapytanie umożliwiające pobranie wszystkich bliźniaczych reprezentacji, które są zaokrąglone, a nie czerwone:

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

Tagi wartości

Tag wartości to para klucz-wartość, która służy do nadania każdemu tagowi wartości, takiej jak "color": "blue" lub "color": "red". Po utworzeniu tagu wartości można go również użyć jako tagu znacznika, ignorując wartość tagu.

Dodawanie tagów wartości do modelu

Tagi wartości są modelowane jako mapa DTDL z string do string. Zarówno te, jak mapKey i mapValue są znaczące.

Oto fragment modelu bliźniaczej reprezentacji implementowania tagu wartości jako właściwości:

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

Dodawanie tagów wartości do cyfrowych reprezentacji bliźniaczych

Podobnie jak w przypadku tagów znaczników, można ustawić tag wartości w cyfrowej reprezentacji bliźniaczej, ustawiając wartość tej tags właściwości z modelu. Aby użyć tagu wartości jako tagu znacznika, możesz ustawić tagValue pole na wartość pustego ciągu ("").

Poniżej przedstawiono elementy JSON dwóch reprezentacji bliźniaczych, które mają tagi wartości reprezentujące ich rozmiary. Bliźniacze reprezentacje w przykładzie mają również tagi wartości "czerwone" lub "purpurowe", które są używane jako tagi znaczników.

Przykład twin1 z tagiem wartości dla rozmiaru dużego i znacznikiem znacznika "czerwony":

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

Przykład twin2 z tagiem wartości dla rozmiaru małego i znacznikiem znacznika "purpurowy":

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

Wykonywanie zapytań przy użyciu tagów wartości

Podobnie jak w przypadku tagów znaczników, można użyć tagów wartości do filtrowania bliźniaczych reprezentacji w zapytaniach. Można również używać tagów wartości i tagów znaczników razem.

W powyższym red przykładzie jest używany jako tag znacznika. Pamiętaj, że jest to zapytanie umożliwiające pobranie wszystkich reprezentacji bliźniaczych, które zostały oznaczone jako "czerwone":

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

Oto zapytanie umożliwiające pobranie wszystkich jednostek, które są małe (tag wartości), a nie czerwone:

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

Następne kroki

Przeczytaj więcej na temat projektowania modeli cyfrowych reprezentacji bliźniaczych i zarządzania nimi:

• Zarządzanie modelami DTDL

Przeczytaj więcej na temat wykonywania zapytań względem grafu bliźniaczej reprezentacji:

• Wykonywanie zapytań względem grafu bliźniaczej reprezentacji