將標籤新增至數位對應項

發行項
05/11/2024

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

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

本文件描述可用在數位對應項上實作標籤的模式。

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

標記標籤

「標記標籤」是用來標記或分類數位對應項的簡單字串，例如 "blue" 或 "red"。此字串是標籤的名稱，而標記標籤並無有意義的值 - 標籤的意義只在於存在 (或不存在)。

將標記標籤新增至模型

標記標籤以string 到 boolean 的 DTDL 對應建立模型。 Boolean 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 表示法。

使用標記標籤進行查詢

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

以下查詢取得所有已標記為 "red" 的對應項：

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

您也可以合併標籤以形成更複雜的查詢。以下查詢取得所有是 round 而不是 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，具有 size large 的值標籤及 "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，具有 size 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 作為標記標籤。請記住，此查詢會取得所有已標記為 "red" 的對應項：

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

以下查詢取得所有是 small (值標籤) 而不是 red 的實體：

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

下一步

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

管理 DTDL 模型

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

查詢對應項圖形

Share via