將標籤新增至數位對應項

發行項
10/27/2023

本文說明如何將不同類型的標籤新增至模型和數位對應項，以及如何使用標記進行查詢。

您可以使用標記的概念進一步識別和分類您的數位對應項。特別是，使用者可能會想要在其 Azure Digital Twins 實例內複寫現有系統的標籤，例如 Haystack Tags 。

本檔說明可用來在數位對應項上實作標記的模式。

標記會先新增為描述數位對應項之模型中的屬性。然後，該屬性會在根據模型建立時，于對應項上設定。之後，標籤可用於查詢中，以識別及篩選對應項。

標記標記

標記標記 是用來標記或分類數位對應項的簡單字串，例如「blue」或「red」。此字串是標記的名稱，而標記標籤沒有有意義的值，標記只會因其存在而顯著（或不存在）。

將標記標記新增至模型

標記標記會模型化為從 string 到的 boolean DTDL 對應。布林值 mapValue 會被忽略，因為標記的存在很重要。

以下是實作標記標記做為屬性之對應項模型的摘錄：

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

將標記標記新增至數位對應項

屬性 tags 是數位對應項模型的一部分之後，您可以藉由設定此屬性的值，在數位對應項中設定標記標記。

以下是如何使用 .NET SDK 設定對應項標記 tags 的程式碼範例：

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);

根據上述範例建立具有標籤屬性的對應項之後，對應項看起來會像這樣：

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

提示

您可以使用 CLI 或 API 來查詢對應項的 JSON 標記法。

使用標記標記進行查詢

將標籤新增至數位對應項之後，標籤就可以用來篩選查詢中的對應項。

以下是一個查詢，可取得已標記為「紅色」的所有對應項：

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

您也可以結合標記以進行更複雜的查詢。以下是一個查詢，可取得所有四捨五入且不是紅色的對應項：

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

值標記

值標記 是索引鍵/值組，用來為每個標記提供值，例如 "color": "blue" 或 "color": "red" 。建立值標記之後，它也可以忽略標記的值來做為標記標記。

將值標記新增至模型

值標記會模型化為從 string 到的 string DTDL 對應。 mapKey和 mapValue 都很重要。

以下是實作值標記做為屬性之對應項模型的摘錄：

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

將值標記新增至數位對應項

如同標記標記，您可以從模型設定此屬性 tags 的值，以在數位對應項中設定值標記。若要使用值標記做為標記標記，您可以將欄位設定 tagValue 為空字串值（ "" ）。

以下是兩個對應項的 JSON 主體，這些對應項具有值標記來表示其大小。此範例中的對應項也有用於標記標記之「red」或「purple」的值標記。

範例 Twin1，具有大小大的值標記，以及「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"
  }
}

範例 Twin2，其大小為 small 的值標記，以及「purple」的標記標記：

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

使用值標籤進行查詢

如同標記標記，您可以使用值標記來篩選查詢中的對應項。您也可以同時使用值標記和標記標記。

在上述範例中， red 正做為標記標記使用。請記住，這是一個查詢，可取得所有標記為「紅色」的對應項：

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

以下是可取得小（值標記）且不是紅色的所有實體的查詢：

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

下一步

深入瞭解設計和管理數位對應項模型：

管理 DTDL 模型

深入瞭解查詢對應項圖表：

查詢對應項圖表