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

了解孪生体模型以及如何在 Azure 数字孪生中定义它们

Azure 数字孪生的一个重要特征是能够定义你自己的词汇,并以你自定义的业务字词生成孪生图。 此功能是通过用户提供的模型提供的。 你可以将模型视为有关你的世界的说明中的名词。 Azure 数字孪生模型以基于 JSON-LD 的数字孪生定义语言 (DTDL) 表示。

模型类似于面向对象的编程语言中的,用于定义真实工作环境中一个特定概念的数据形状。 模型具有名称(如 Room 或 TemperatureSensor),并包含属性、组件和关系等元素,用于描述环境中此类实体的作用。 稍后,你将使用这些模型来创建数字孪生体,这些孪生体代表符合此类型说明的特定实体。

用于模型的数字孪生定义语言 (DTDL)

Azure 数字孪生的模型是使用数字孪生定义语言 (DTDL) 定义的。

可以在 GitHub 中查看 DTDL v3 的完整语言说明:DTDL 版本 3 语言说明。 此页面包含 DTDL 参考详细信息和示例,可帮助你开始编写自己的 DTDL 模型。

DTDL 基于 JSON-LD,独立于编程语言。 DTDL 并非 Azure 数字孪生独占。 它还用于表示其他 IoT 服务(如 IoT 即插即用)中的设备数据。

本文的余下内容总结了如何在 Azure 数字孪生中使用该语言。

支持的 DTDL 版本

Azure 数字孪生支持 DTDL 版本 2 和 3(在文档中分别缩短为 v2 和 v3)。 V3 是 Azure 数字孪生中基于其扩展功能进行建模的建议选择,包括:

在文档中讨论这些功能时,会附带说明它们仅在 DTDL v3 中可用。 有关 DTDL v2 和 v3 之间的差异的完整列表,请参阅 DTDL v3 语言说明:版本 2 的更改

Azure 数字孪生还支持在同一实例中使用 v2 和 v3 模型的组合。 同时使用这两个版本的模型时,请记住以下限制:

  • v2 接口无法扩展 v3 接口,也不能有 v3 接口的组件作为其架构。
  • 相反,v3 接口可以扩展 v2 接口,v3 接口可以具有 v2 接口作为其架构的组件。
  • 关系可以指向任一方向,从 v2 模型源到 v3 模型目标,反之亦然,从 v3 模型源到 v2 模型目标。

还可以将现有 v2 模型迁移到 v3。 有关如何执行此操作的说明,请参阅将 v2 模型转换为 v3

注意

当前,Azure Digital Twins Explorer 完全支持 DTDL v2 模型,并支持 DTDL v3 模型的有限功能。

可以在“模型”面板中查看 DTDL v3 模型,并且可以查看和编辑使用 DTDL v3 模型创建的孪生体(包括具有数组属性的孪生体)。 但是,DTDL v3 模型不会显示在“模型图”面板中,也无法使用 Azure Digital Twins Explorer 导入。 要将 DTDL v3 模型导入实例,请使用另一个开发人员接口,例如 API 和 SDKAzure CLI

模型概述

可以在任何文本编辑器中编写孪生类型模型。 DTDL 语言遵循 JSON 语法,因此你应使用扩展名 .json 存储模型。 使用 JSON 扩展名可使许多编程文本编辑器在你的 DTDL 文档中提供基本语法检查和突出显示。 还有一个适用于 Visual Studio CodeDTDL 扩展名

下面是模型接口中的字段:

字段 说明
@id 模型的数字孪生模型标识符 (DTMI),格式为 dtmi:<domain>:<unique-model-identifier>;<model-version-number>。 在 DTDL v3 中,可以省略版本号,也可以结构化为两部分式的(<major>.<minor>)版本号。
@type 标识所要描述的信息类型。 对于接口,类型为 Interface
@context 设置 JSON 文档的上下文。 模型应对 DTDL v2 使用 dtmi:dtdl:context;2,而对 DTDL v3 使用 dtmi:dtdl:context;3。 DTDL v3 模型还可以在此字段中命名其他功能扩展
displayName [可选] 提供用于定义模型的易记名称的选项。 如果不使用此字段,模型将使用其完整的 DTMI 值。
contents 所有剩余的接口数据将作为特性定义数组放在此处。 每个属性都必须提供一个 @typePropertyRelationshipComponent)来标识它描述的接口信息的排序,然后提供一组用于定义实际属性的属性。 下一部分详细介绍模型特性

下面是基本 DTDL 模型的示例。 此模型描述了一个住宅,其中每个 ID 都有一个属性。 住宅模型还定义了与楼层模型的关系,用于指示住宅孪生体连接到了特定的楼层孪生体。

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "contents": [
    {
      "@type": "Property",
      "name": "id",
      "schema": "string"     
    },    
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1"
    }
  ]
}

模型特性

有关模型的主要信息由其特性提供,这些特性在模型接口的 contents 节中定义。

下面是 Azure 数字孪生中支持的 DTDL 中提供的属性。 用于 Azure 数字孪生的 DTDL 模型接口可能包含以下每个字段中的零个、一个或多个:

  • 属性 - 属性是表示实体状态的数据字段(类似于许多面向对象的编程语言中的属性)。 属性具有后备存储,随时可供读取。 有关详细信息,请参阅下面的属性

  • 关系 - 使用关系可以表示一个数字孪生与其他数字孪生的关连方式。 关系可以表示不同的语义含义,例如 contains ("floor contains room")、cools ("hvac cools room")、isBilledTo ("compressor is billed to user") 等等。 解决方案可以使用关系来提供相互关联的实体的图。 关系还可具有其自己的属性。 有关详细信息,请参阅下面的关系

  • 组件 - 如果需要,可以使用组件生成你的模型接口作为其他接口的程序集。 组件的一个示例是一个 frontCamera 接口(以及另一个组件接口 backCamera),用于为手机定义模型。 先定义 frontCamera 的接口,就像它是其自己的模型一样,然后在定义 Phone 时引用该接口。

    使用组件可以描述这样的对象:它属于解决方案不可或缺的一部分,但不需要单独的标识,且不需要在孪生图中单独创建、删除或重新排列。 如果你希望实体在孪生体图中独立存在,请将其表示为通过关系连接的不同模型的单独数字孪生体。

    提示

    组件还可用于进行组织,以便在模型接口中将相关属性集分组到一起。 在这种情况下,可以将每个组件视为该接口中的命名空间或“文件夹”。

    有关详细信息,请参阅下面的组件

DTDL v3 语言说明还定义了命令遥测,但它们均未在 Azure 数字孪生中使用。 不支持命令。另外,尽管在模型定义中允许使用遥测,但在 Azure 数字孪生建模中没有唯一的用例。 应使用 DTDL 属性来存储孪生状态信息,而不是使用 DTDL 遥测。

注意

尽管无需在 DTDL 模型中定义遥测字段来存储传入的设备数据,但 Azure 数字孪生可以使用 SendTelemetry API 将事件作为遥测发出。 这会触发一个数字孪生遥测消息事件,该事件可由事件处理程序接收,以便对其他孪生执行操作或触发下游服务。

属性

本部分详细介绍了 DTDL 模型中的属性

有关可能作为属性的一部分显示的字段的综合信息,请参阅 DTDL v3 语言说明中的属性

注意

Azure 数字孪生当前不支持属性的 writable DTDL 特性。 可以将它添加到模型中,但 Azure 数字孪生不会强制使用它。 有关详细信息,请参阅特定于服务的 DTDL 说明

架构

根据 DTDL,属性属性的架构可以是标准基元类型(integerdoublestringboolean)以及其他类型,例如 dateTimeduration

除了基元类型外,属性字段还可以具有以下复杂类型

  • Object
  • Map
  • Enum
  • Array,仅在 DTDL v3 中。 属性的 Array 类型在 DTDL v2 中不支持。

它们也可以是语义类型,这样便可批注带单位的值。 在 DTDL v2 中,本机支持语义类型;在 DTDL v3 中,可以将它们包含在功能扩展中。

基本属性示例

下面是 DTDL 模型中属性的基本示例。 此示例显示住宅的 ID 属性。

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "contents": [
    {
      "@type": "Property",
      "name": "id",
      "schema": "string"     
    },    
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1"
    }
  ]
}

复杂对象类型示例

属性可以是复杂类型,包括 Object 类型。

下面的示例演示住宅模型的另一个版本,其地址具有一个属性。 address 是一个对象,有其自己的街道、城市、省/市/自治区和邮政编码字段。

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {
      "@type": "Property",
      "name": "address",
      "schema": {
        "@type": "Object",
        "fields": [
          {
            "name": "street",
            "schema": "string"
          },
          {
            "name": "city",
            "schema": "string"
          },
          {
            "name": "state",
            "schema": "string"
          },
          {
            "name": "zip",
            "schema": "string"
          }
        ]
      }
    },
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1",
      "properties": [
        {
          "@type": "Property",
          "name": "lastOccupied",
          "schema": "dateTime"
        }
      ]
    }
  ]
}

DTDL v2 语义类型示例

语义类型用于用单位表达值。 Azure 数字孪生的属性可以使用 DTDL 支持的任何语义类型。

在 DTDL v2 中,本机支持语义类型。 有关 DTDL v2 中的语义类型的详细信息,请参阅 DTDL v2 语言说明中的语义类型。 若要了解 DTDL v3 中的语义类型,请参阅 QuantitativeTypes DTDL v3 功能扩展

以下示例显示了 DTDL v2 传感器模型,该模型具有湿度和温度的语义类型属性。

{
  "@id": "dtmi:com:adt:dtsample:v2sensor;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;2",
  "displayName": "Sensor (v2 model)",
  "contents": [
    {
      "@type": ["Property", "Temperature"],
      "name": "Temperature",
      "schema": "double",
      "unit": "degreeFahrenheit"    
    },
    {
      "@type": ["Property", "Humidity"],
      "name": "Humidity",
      "schema": "double",
      "unit": "gramPerCubicMetre" 
    }
  ]
}

重要

“Property”必须是 @type 数组的第一个元素,后跟语义类型。 否则,该字段可能无法显示在 Azure Digital Twins Explorer 中。

关系

本部分详细介绍 DTDL 模型中的关系

有关可能作为关系的一部分显示的字段的综合列表,请参阅 DTDL v3 语言说明中的关系

注意

Azure 数字孪生当前不支持关系的 writableminMultiplicitymaxMultiplicity DTDL 特性。 可以将它们添加到模型中,但 Azure 数字孪生不会强制使用它们。 有关详细信息,请参阅特定于服务的 DTDL 说明

基本关系示例

下面是 DTDL 模型中关系的基本示例。 此示例展示了住宅模型上的关系,通过这种关系,住宅模型可以连接到楼层模型。

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "contents": [
    {
      "@type": "Property",
      "name": "id",
      "schema": "string"     
    },    
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1"
    }
  ]
}

注意

对于关系,@id 是一个可选字段。 如果未提供 @id,则数字孪生体接口处理器会分配一个。

目标和非目标关系

可定义含目标或不含目标的关系。 目标指定关系可以涉及的孪生体类型。 例如,可以包含一个目标,指定住宅模型只能与楼层孪生体之间具有 rel_has_floors 关系。

有时最好定义不含特定目标的关系,以便关系可以连接到许多不同类型的孪生体。

下面是 DTDL 模型上不含目标的关系示例。 在此例中,关系用于定义房间可能具有哪些传感器,关系可以连接到任意类型。

{
  "@id": "dtmi:com:adt:dtsample:room;1",
  "@type": "Interface",
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:dtdl:extension:quantitativeTypes;1"
  ],
  "displayName": "Room",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {
      "@type": ["Property", "Humidity"],
      "name": "humidity",
      "schema": "double",
      "unit": "gramPerCubicMetre"
    },
    {
      "@type": "Component",
      "name": "thermostat",
      "schema": "dtmi:com:adt:dtsample:thermostat;1"
    },
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:room:rel_has_sensors;1",
      "name": "rel_has_sensors",
      "displayName": "Room has sensors"
    }
  ]
},

关系的属性

DTDL 还允许关系具有其自己的属性。 在 DTDL 模型中定义关系时,关系可以有自己的 properties 字段,你可以在其中定义自定义属性来描述关系特定的状态。

下面的示例演示了住宅模型的另一个版本,其中 rel_has_floors 关系具有一个属性,用于表示相关楼层上次被占用的时间。

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {
      "@type": "Property",
      "name": "address",
      "schema": {
        "@type": "Object",
        "fields": [
          {
            "name": "street",
            "schema": "string"
          },
          {
            "name": "city",
            "schema": "string"
          },
          {
            "name": "state",
            "schema": "string"
          },
          {
            "name": "zip",
            "schema": "string"
          }
        ]
      }
    },
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1",
      "properties": [
        {
          "@type": "Property",
          "name": "lastOccupied",
          "schema": "dateTime"
        }
      ]
    }
  ]
}

组件

本部分详细介绍 DTDL 模型中的组件

有关可能作为组件一部分显示的字段的综合列表,请参阅 DTDL v3 语言说明中的组件

基本组件示例

下面是 DTDL 模型中组件的基本示例。 此示例演示使用恒温器模型作为组件的 Room 模型。

[
  {
    "@id": "dtmi:com:adt:dtsample:room;1",
    "@type": "Interface",
    "@context": [
      "dtmi:dtdl:context;3",
      "dtmi:dtdl:extension:quantitativeTypes;1"
    ],
    "displayName": "Room",
    "extends": "dtmi:com:adt:dtsample:core;1",
    "contents": [
      {
        "@type": ["Property", "Humidity"],
        "name": "humidity",
        "schema": "double",
        "unit": "gramPerCubicMetre"
      },
      {
        "@type": "Component",
        "name": "thermostat",
        "schema": "dtmi:com:adt:dtsample:thermostat;1"
      },
      {
        "@type": "Relationship",
        "@id": "dtmi:com:adt:dtsample:room:rel_has_sensors;1",
        "name": "rel_has_sensors",
        "displayName": "Room has sensors"
      }
    ]
  },
  {
    "@context": [
      "dtmi:dtdl:context;3",
      "dtmi:dtdl:extension:quantitativeTypes;1"
    ],
    "@id": "dtmi:com:adt:dtsample:thermostat;1",
    "@type": "Interface",
    "displayName": "thermostat",
    "contents": [
      {
        "@type": ["Property", "Temperature"],
        "name": "temperature",
        "schema": "double",
        "unit": "degreeFahrenheit"
      }
    ]
  }
]

如果此解决方案中的其他模型也应该包含恒温器,那么这些模型可以在自己的定义中引用相同的恒温器模型作为组件,就像 Room 所做的那样。

重要

组件接口(上面示例中的恒温器)必须与任何使用它的接口(上面示例中的 Room)定义在同一个数组中,以便找到组件引用。

模型继承

有时你可能想要进一步将模型专用化。 例如,使用一个泛型模型 Room 以及专用化变体 ConferenceRoom 和 Gym 可能会很有用。 为了表示专用化,DTDL 支持继承。 接口可从一个或多个接口继承。 为此可将一个 extends 字段添加到模型。

extends 节是接口名称或接口名称的数组(允许扩展接口从多个父模型继承)。 单个父模型可以充当多个扩展接口的基础模型。

注意

在 DTDL v2 中,每个 extends 接口最多可以列出两个接口。 在 DTDL v3 中,对 extends 的即时值没有数量限制。

在 DTDL v2 和 v3 中,extends 层次结构的总深度限制为 10。

以下示例将前面 DTDL 示例中的住宅模型重新假设为更大的“核心”模型的子类型。 首先定义父模型(核心),然后使用 extends 在父模型的基础之上构建子模型(住宅)。

{
    "@id": "dtmi:com:adt:dtsample:core;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;3",
    "displayName": "Core",
    "contents": [
        {
            "@type": "Property",
            "name": "id",
            "schema": "string"
        },
        {
            "@type": "Property",
            "name": "name",
            "schema": "string"
        }
    ]
}
{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {

在这种情况下,核心模型向住宅模型提供 ID 和名称。 其他模型也可以扩展核心模型以同样获取这些属性。 下面是扩展同一父接口的住宅模型:

{
  "@id": "dtmi:com:adt:dtsample:room;1",
  "@type": "Interface",
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:dtdl:extension:quantitativeTypes;1"
  ],
  "displayName": "Room",
  "extends": "dtmi:com:adt:dtsample:core;1",

应用继承后,扩展接口会公开整个继承链中的所有属性。

扩展接口不能更改父接口的任何定义;只能在父接口中添加定义。 此外,扩展接口不能重新定义已在其任何父接口中定义的功能(即使定义的功能相同)。 例如,如果父接口定义了 double 属性 mass,则扩展接口不能包含 mass 的声明,即使该声明也是 double

DTDL v3 功能扩展

DTDL v3 支持定义其他元模型类的语言扩展,你可以使用这些类编写更丰富的模型。 本部分介绍可用于向 DTDL v3 模型添加非核心功能的功能扩展类。

每个功能扩展都由其上下文说明符标识,它是唯一的数字孪生模型标识符 (DTMI) 值。 若要在模型中启用功能扩展,请将扩展的上下文说明符添加到模型的 @context 字段(以及 dtmi:dtdl:context;3的 常规 DTDL 上下文说明符)。 可以将多个功能扩展添加到同一模型。

下面的示例说明了该 @context 字段在启用功能扩展后的样子。 以下摘录摘自使用 QuantitativeTypes 扩展Annotation 扩展的模型。

  "@context": [
      "dtmi:dtdl:context;3",
      "dtmi:dtdl:extension:quantitativeTypes;1",
      "dtmi:dtdl:extension:annotation;1"
  ]

将功能扩展添加到模型后,你将有权在模型中访问该扩展的辅助类型。 可以将辅助类型添加到 DTDL 元素的 @type 字段,以便为元素提供附加功能。 辅助类型可能会向元素添加其他属性。

例如,下面是使用 Annotation 扩展的模型的摘录。 此扩展具有一个名为 ValueAnnotation 的辅助类型,该类型在下面的示例中添加到属性元素中。 将此辅助类型添加到属性元素允许该元素具有一个附加 annotates 字段,该字段用于指示此元素注释的另一个属性。

{
  "@type": [ "Property", "ValueAnnotation" ],
  "name": "currentTempAccuracy",
  "annotates": "currentTemp",
  "schema": "double"
  },

本部分的其余部分更详细地介绍了批注扩展和其他 DTDL v3 功能扩展。

批注扩展

批注扩展用于将自定义元数据添加到 DTDL v3 模型中的属性元素。 其上下文说明符为 dtmi:dtdl:extension:annotation;1

此扩展包括 ValueAnnotation 辅助类型,可添加到 DTDL 属性元素。 ValueAnnotation 类型向 annotates 元素添加一个字段,该字段允许命名由当前元素批注的另一个属性。

有关此扩展的更多详细信息和示例,请参阅 DTDL v3 语言说明中的批注扩展

历史化扩展

历史化扩展用于将 DTDL v3 模型中的属性指定为应进行历史化的属性(这意味着应记录其值的历史序列,以及值更改的时间)。 其上下文说明符为 dtmi:dtdl:extension:historization;1

此扩展包括 Historized 辅助类型,可将其作为共同类型添加到 DTDL 属性元素,以指示服务应保留元素的历史值,并使其可用于查询和分析。 Historized 辅助类型不会向元素添加任何字段。

有关此扩展的更多详细信息和示例,请参阅 DTDL v3 语言说明中的 Historization 扩展

重写扩展

重写扩展用于使用实例值替代 DTDL V3 模型中的属性。 它与批注扩展结合使用,其上下文说明符为 dtmi:dtdl:extension:overriding;1

此扩展包括 Override 辅助类型,可将其添加到ValueAnnotation(来自注释扩展)共同键入的 DTDL 属性。 Override 类型向元素添加一个字段 overrides,该字段用于命名由当前元素的值重写的带批注元素的字段。

有关此扩展的更多详细信息和示例,请参阅 DTDL v3 语言说明中的替代扩展

QuantitativeTypes 扩展

QuantitativeTypes 扩展 用于在 DTDL v3 模型中启用语义类型、单元类型和单位。 其上下文说明符为 dtmi:dtdl:extension:quantitativeTypes;1

此扩展允许将许多语义类型用作辅助类型,这些类型可以添加到 CommandRequest、Field、MapValue 或 DTDL v3 中的属性。 语义类型向元素添加一个字段 unit,该字段接受与语义类型相对应的有效单位。

有关扩展的更多详细信息,包括示例和受支持的语义类型和单元的完整列表,请参阅 DTDL v3 语言说明中的量化类型扩展

特定于服务的 DTDL 说明

并非使用 DTDL 的所有服务都实现完全相同的 DTDL 功能。 Azure 数字孪生目前不支持某些 DTDL 功能,包括:

  • DTDL 命令
  • 属性或关系的 writable 特性。 尽管可以根据 DTDL 规范设置此特性,但 Azure 数字孪生不会使用该值。 这些特性始终被视为可供对 Azure 数字孪生服务拥有常规写入权限的外部客户端写入。
  • 关系的 minMultiplicitymaxMultiplicity 属性。 尽管可以按 DTDL 规范设置这些特性,但这些值不会由 Azure 数字孪生强制使用。

DTDL 模型还必须满足以下要求才能与 Azure 数字孪生兼容:

  • 模型中的所有顶级 DTDL 元素必须是 Interface 类型。 提出此项要求的原因是,Azure 数字孪生模型 API 可以接收表示某个接口或接口数组的 JSON 对象。 因此,不允许在最高级别使用其他 DTDL 元素类型。
  • 用于 Azure 数字孪生的 DTDL 不得定义任何命令。
  • Azure 数字孪生只允许单个级别的组件嵌套,这意味着,用作组件的接口本身不能包含任何组件。
  • 不能在其他 DTDL 接口中以内联方式定义接口;接口必须定义为具有自身 ID 的独立顶级实体。 然后,当另一个接口想要以组件形式或通过继承包含该接口时,这另一个接口可以引用该接口的 ID。

建模工具和最佳做法

本部分介绍建模的其他注意事项和建议。

使用现有的行业标准本体

本体学是一组模型,用于全面描述给定领域,例如制造、建筑结构、IoT 系统、智能城市、能源网格、Web 内容等。

如果解决方案适用于使用任何类型的建模标准的特定行业,请考虑从为行业设计的预先存在的模型集开始,而不是从头开始设计模型。 Microsoft 与领域专家合作,根据行业标准创建 DTDL 模型本体,以帮助最大程度地减少重塑并鼓励跨行业解决方案的一致性和简单性。 有关这些本体的详细信息(包括如何使用本体以及现在提供哪些本体),可参阅什么是本体?

考虑查询含义

在设计模型以反映环境中的实体时,提前考虑你的设计的查询影响。 你可能想要以一种可避免图遍历后生成较大结果集的方式设计属性。 我们还建议你将需要在单个查询中解答的关系建模为单层关系。

验证模型

创建模型后,建议先离线对其进行验证,然后再将其上传到 Azure 数字孪生实例。

为了帮助你验证模型,NuGet 上提供了一个 .NET 客户端 DTDL 分析库:DTDLParser。 可以直接在 C# 代码中使用分析器库。 还可以在 GitHub 的 DTDLParserResolveSample 中查看分析器的示例用法。

批量上传和删除模型

创建、扩展或选择完模型后,需将其上传到 Azure 数字孪生实例,使其可在解决方案中使用。

可以使用导入作业 API 在单个 API 调用中上传许多模型。 API 可以同时接受实例中 Azure 数字孪生对于模型数的限制,并根据需要自动对模型重新排序以解析它们之间的依赖项。 有关使用此 API 的详细说明和示例,请参阅模型的批量导入说明

导入作业 API 的替代方法是模型上传程序示例,该示例使用单个模型 API 一次性上传多个模型文件。 此示例还实现自动重新排序以解析模型依赖项。 它当前仅适用于 DTDL 的版本 2

如果需要同时删除 Azure 数字孪生实例中的所有模型,可以使用模型删除器示例。 这是一个项目,其中包含递归逻辑,用于通过删除过程处理模型依赖项。 它当前仅适用于 DTDL 的版本 2

或者,如果要通过删除所有模型以及所有孪生体和关系来清除实例中的数据,可以使用删除作业 API

可视化模型

将模型上传到 Azure 数字孪生实例后,可以使用 Azure Digital Twins Explorer 查看它们。 资源管理器包含实例中所有模型的列表,以及说明它们如何相互关联的模型图,包括任何继承和模型关系。

注意

当前,Azure Digital Twins Explorer 完全支持 DTDL v2 模型,并支持 DTDL v3 模型的有限功能。

可以在“模型”面板中查看 DTDL v3 模型,并且可以查看和编辑使用 DTDL v3 模型创建的孪生体(包括具有数组属性的孪生体)。 但是,DTDL v3 模型不会显示在“模型图”面板中,也无法使用 Azure Digital Twins Explorer 导入。 要将 DTDL v3 模型导入实例,请使用另一个开发人员接口,例如 API 和 SDKAzure CLI

以下是模型图的示例:

Azure Digital Twins Explorer 的屏幕截图。“模型图”面板已突出显示。

有关 Azure Digital Twins Explorer 中的模型体验的详细信息,请参阅探索模型和模型图

后续步骤