你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

向数字孪生体添加标记

项目
06/29/2023

本文介绍如何向模型和数字孪生体添加不同类型的标签，以及如何使用标签进行查询。

你可以使用标记概念进一步识别你的数字孪生体并对其进行归类。特别是，用户可能希望在其 Azure 数字孪生实例中复制现有系统中的标记，例如 Haystack 标记。

本文档介绍了可用于在数字孪生体中实施标记的模式。

首先将标记作为属性添加到描述数字孪生体的模型中。然后，在基于模型创建孪生体时，在孪生体上设置该属性。之后，可以在查询中使用标记来标识和筛选孪生体。

记号标记

记号标记是一个简单字符串，用来对数字孪生体进行标记或归类，例如“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 表示形式。

使用记号标记进行查询

将记号添加到数字孪生体后，可以在查询中使用标记来筛选孪生体。

下面的查询获取已标记为“red”的所有孪生体：

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，包含表示小的值标记和一个“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)

下面的查询获取所有小型（值标签）且非红色的实体：

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

后续步骤

详细了解如何设计和管理数字孪生体模型：

管理 DTDL 模型

详细了解如何查询孪生图：

查询孪生图