將標籤新增至數位對應項
本文說明如何將不同類型的標籤新增至模型和數位對應項,以及如何使用標籤進行查詢。
您可以使用標籤的概念來進一步識別和分類數位對應項。 特別是,使用者可能想要在其 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'
下一步
深入了解設計和管理數位對應項模型:
深入了解查詢對應項圖表: