您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

了解 Azure 数字孪生中的克隆模型Understand twin models in Azure Digital Twins

Azure 数字孪生的一项重要特征是能够定义自己的词汇,并以业务的自定义条款构建克隆图形。A key characteristic of Azure Digital Twins is the ability to define your own vocabulary and build your twin graph in the self-defined terms of your business. 此功能是通过用户定义模型提供的。This capability is provided through user-defined models. 您可以将模型视为您的全球说明中的名词。You can think of models as the nouns in a description of your world.

模型类似于面向对象的编程语言中的,它定义了真实工作环境中一个特定概念的数据形状。A model is similar to a class in an object-oriented programming language, defining a data shape for one particular concept in your real work environment. 模型具有 ((如房间温度传感器) )的名称,并且包含属性、遥测/事件和命令等元素,这些元素描述了环境中此类型实体的作用。Models have names (such as Room or TemperatureSensor), and contain elements such as properties, telemetry/events, and commands that describe what this type of entity in your environment can do. 稍后,您将使用这些模型创建代表满足此类型说明的特定实体的数字孪生Later, you will use these models to create digital twins that represent specific entities that meet this type description.

使用基于 JSON LD 的**数字克隆定义语言 (DTDL) **来编写模型。Models are written using the JSON-LD-based Digital Twin Definition Language (DTDL).

数字克隆定义语言 (DTDL) 用于编写模型Digital Twin Definition Language (DTDL) for writing models

Azure 数字孪生的模型是使用数字孪生定义语言 (DTDL) 定义的。Models for Azure Digital Twins are defined using the Digital Twins Definition language (DTDL). DTDL 基于 JSON-LD,是独立于编程语言的。DTDL is based on JSON-LD and is programming-language independent. DTDL 不是 Azure 数字孪生独有的,但也用于表示iot 即插即用等其他 IoT 服务中的设备数据。DTDL is not exclusive to Azure Digital Twins, but is also used to represent device data in other IoT services such as IoT Plug and Play.

Azure 数字孪生使用DTDL_版本 2_Azure Digital Twins uses DTDL version 2. 有关此版本的 DTDL 的详细信息,请参阅 GitHub 中的规范文档:数字孪生定义语言 (DTDL) 版本 2For more information about this version of DTDL, see its spec documentation in GitHub: Digital Twins Definition Language (DTDL) - version 2. 在 Azure 数字孪生中使用 DTDL_版本 1_现已弃用。Use of DTDL version 1 with Azure Digital Twins has now been deprecated.

提示

并非所有使用 DTDL 的服务都实现 DTDL 的完全相同的功能。Not all services that use DTDL implement the exact same features of DTDL. 例如,IoT 即插即用不使用适用于图形的 DTDL 功能,而 Azure 数字孪生目前不实现 DTDL 命令。For example, IoT Plug and Play does not use the DTDL features that are for graphs, while Azure Digital Twins does not currently implement DTDL commands. 有关特定于 Azure 数字孪生的 DTDL 功能的详细信息,请参阅本文后面的Azure 数字孪生 DTDL 实现细节部分。For more information on the DTDL features that are specific to Azure Digital Twins, see the section later in this article on Azure Digital Twins DTDL implementation specifics.

模型的元素Elements of a model

在模型定义中,顶级代码项是一个接口Within a model definition, the top-level code item is an interface. 这将封装整个模型,并在接口中定义模型的其余部分。This encapsulates the entire model, and the rest of the model is defined within the interface.

DTDL 模型接口可能包含以下每个字段中的零个、一个或多个字段:A DTDL model interface may contain zero, one, or many of each of the following fields:

  • 属性-属性是表示实体的状态的数据字段 (类似于许多面向对象的编程语言) 中的属性。Property - Properties are data fields that represent the state of an entity (like the properties in many object-oriented programming languages). 与遥测(这是时间绑定的数据事件)不同,属性具有后备存储并且可随时读取。Unlike telemetry, which is a time-bound data event, properties have backing storage and can be read at any time.

  • 遥测-遥测字段表示度量值或事件,通常用于描述设备传感器读数。Telemetry - Telemetry fields represent measurements or events, and are often used to describe device sensor readings. 遥测数据不会存储在数字克隆上;它更像是准备发送到某个位置的数据事件流。Telemetry is not stored on a digital twin; it is more like a stream of data events ready to be sent somewhere.

  • 如果需要,组件组件允许将模型接口构建为其他接口的程序集。Component - Components allow you to build your model interface as an assembly of other interfaces, if you want. 组件的一个示例是 (的frontCamera接口,另一个组件接口backCamera) 用于为手机定义模型。An example of a component is a frontCamera interface (and another component interface backCamera) that are used in defining a model for a phone. 必须先为frontCamera定义一个接口,就像它是其自己的模型一样,然后在定义手机时可以引用它。You must first define an interface for frontCamera as though it were its own model, and then you can reference it when defining Phone.

    使用组件来描述作为解决方案不可分割但不需要单独标识的内容,而无需单独在克隆图形中创建、删除或重新排列。Use a component to describe something that is an integral part of your solution but doesn't need a separate identity, and doesn't need to be created, deleted, or rearranged in the twin graph independently. 如果希望实体在 existences 图中具有独立的,则将其表示为不同模型的单独数字孪生,通过关系进行连接 (参阅下一项目符号) 。If you want entities to have independent existences in the twin graph, represent them as separate digital twins of different models, connected by relationships (see next bullet).

    提示

    组件还可用于组织,以对模型接口中的相关属性集进行分组。Components can also be used for organization, to group sets of related properties within a model interface. 在这种情况下,你可以将每个组件视为命名空间,或将 "文件夹" 视为接口。In this situation, you can think of each component as a namespace or "folder" inside the interface.

  • 关系-关系使你可以表示数字克隆如何与其他数字孪生一起使用。Relationship - Relationships let you represent how a digital twin can be involved with other digital twins. 关系可以表示不同的语义含义,如contains ( "楼层包含空间" ) ,冷却 ( "hvac 冷却房间" ) , isBilledTo ( "为用户向用户计费" ) 等。关系允许解决方案提供关联实体的关系图。Relationships can represent different semantic meanings, such as contains ("floor contains room"), cools ("hvac cools room"), isBilledTo ("compressor is billed to user"), etc. Relationships allow the solution to provide a graph of interrelated entities.

备注

DTDL 规范还定义命令,这些命令可以在数字克隆 ((如 reset 命令)或用于切换风扇) 的命令。The spec for DTDL also defines Commands, which are methods that can be executed on a digital twin (like a reset command, or a command to switch a fan on or off). 但是, Azure 数字孪生目前不支持命令。However, commands are not currently supported in Azure Digital Twins.

Azure 数字孪生 DTDL 实现细节Azure Digital Twins DTDL implementation specifics

要使 DTDL 模型与 Azure 数字孪生兼容,必须满足这些要求。For a DTDL model to be compatible with Azure Digital Twins, it must meet these requirements.

  • 模型中的所有顶级 DTDL 元素必须属于类型接口All top-level DTDL elements in a model must be of type interface. 这是因为 Azure 数字孪生模型 Api 可以接收表示接口或接口数组的 JSON 对象。This is because Azure Digital Twins model APIs can receive JSON objects that represent either an interface or an array of interfaces. 因此,不允许在顶级使用其他 DTDL 元素类型。As a result, no other DTDL element types are allowed at the top level.
  • DTDL for Azure 数字孪生不能定义任何命令DTDL for Azure Digital Twins must not define any commands.
  • Azure 数字孪生只允许使用单个级别的组件嵌套。Azure Digital Twins only allows a single level of component nesting. 这意味着用作组件的接口不能有任何组件本身。This means that an interface that's being used as a component can't have any components itself.
  • 无法在其他 DTDL 接口内以内联方式定义接口;它们必须定义为具有自己的 Id 的单独顶级实体。Interfaces can't be defined inline within other DTDL interfaces; they must be defined as separate top-level entities with their own IDs. 然后,当另一个接口要将该接口包含为组件或继承时,它可以引用其 ID。Then, when another interface wants to include that interface as a component or through inheritance, it can reference its ID.

示例模型代码Example model code

可以在任何文本编辑器中编写克隆类型模型。Twin type models can be written in any text editor. DTDL 语言遵循 JSON 语法,因此应存储扩展名为JSON的模型。The DTDL language follows JSON syntax, so you should store models with the extension .json. 使用 JSON 扩展会使许多编程文本编辑器为你的 DTDL 文档提供基本语法检查和突出显示。Using the JSON extension will enable many programming text editors to provide basic syntax checking and highlighting for your DTDL documents. 还有一个可用于Visual Studio CodeDTDL 扩展There is also a DTDL extension available for Visual Studio Code.

本部分包含以 DTDL 接口形式编写的典型模型的示例。This section contains an example of a typical model, written as a DTDL interface. 此模型描述行星,每个行星都具有名称、质量和温度。The model describes planets, each with a name, a mass, and a temperature.

请考虑行星还可能会与卫星一起交互,其中可能包含cratersConsider that planets may also interact with moons that are their satellites, and may contain craters. 在下面的示例中,该 Planet 模型通过引用两个外部模型(和)来表示与这些其他实体的连接 Moon CraterIn the example below, the Planet model expresses connections to these other entities by referencing two external models—Moon and Crater. 下面的示例代码中也定义了这些模型,但它们非常简单,因此不会降低主要的 Planet 示例。These models are also defined in the example code below, but are kept very simple so as not to detract from the primary Planet example.

[
  {
    "@id": "dtmi:com:contoso:Planet;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;2",
    "displayName": "Planet",
    "contents": [
      {
        "@type": "Property",
        "name": "name",
        "schema": "string"
      },
      {
        "@type": "Property",
        "name": "mass",
        "schema": "double"
      },
      {
        "@type": "Telemetry",
        "name": "Temperature",
        "schema": "double"
      },
      {
        "@type": "Relationship",
        "name": "satellites",
        "target": "dtmi:com:contoso:Moon;1"
      },
      {
        "@type": "Component",
        "name": "deepestCrater",
        "schema": "dtmi:com:contoso:Crater;1"
      }
    ]
  },
  {
    "@id": "dtmi:com:contoso:Crater;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;2"
  },
  {
    "@id": "dtmi:com:contoso:Moon;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;2"
  }
]

模型的字段为:The fields of the model are:

字段Field 说明Description
@id 模型的标识符。An identifier for the model. 必须采用格式 dtmi:<domain>:<unique model identifier>;<model version number>Must be in the format dtmi:<domain>:<unique model identifier>;<model version number>.
@type 标识所描述的信息的类型。Identifies the kind of information being described. 对于接口,类型为interfaceFor an interface, the type is Interface.
@context 设置 JSON 文档的上下文Sets the context for the JSON document. 模型应使用 dtmi:dtdl:context;2Models should use dtmi:dtdl:context;2.
displayName 可有可无允许您为模型指定友好名称(如果需要)。[optional] Allows you to give the model a friendly name if desired.
contents 所有剩余的接口数据都放置在此处,作为特性定义的数组。All remaining interface data is placed here, as an array of attribute definitions. 每个属性都必须 @type 提供* (属性*、遥测命令关系组件) ,以标识它所描述的接口信息的排序,然后是定义实际 (属性的一组属性(例如) name ,并 schema 定义*属性*) 。Each attribute must provide a @type (Property, Telemetry, Command, Relationship, or Component) to identify the sort of interface information it describes, and then a set of properties that define the actual attribute (for example, name and schema to define a Property).

备注

请注意,在此示例中 (Crater的组件接口) 与 (行星) 使用该接口的接口在同一阵列中定义。Note that the component interface (Crater in this example) is defined in the same array as the interface that uses it (Planet). 必须以这种方式在 API 调用中定义组件,才能找到接口。Components must be defined this way in API calls in order for the interface to be found.

可能的架构Possible schemas

根据 DTDL,属性遥测属性的架构可以是标准基元类型( integerdouble 、和),也可以是 string Boolean 其他类型(如 DateTime 和) DurationAs per DTDL, the schema for Property and Telemetry attributes can be of standard primitive types—integer, double, string, and Boolean—and other types such as DateTime and Duration.

除了基元类型外,属性遥测字段还可以具有以下复杂类型:In addition to primitive types, Property and Telemetry fields can have these complex types:

  • Object
  • Map
  • Enum

遥测字段也支持 ArrayTelemetry fields also support Array.

模型继承Model inheritance

有时,你可能需要进一步专用化模型。Sometimes, you may want to specialize a model further. 例如,有一个通用的模型房间,并使用专用变量ConferenceRoom健身房可能会很有用。For example, it might be useful to have a generic model Room, and specialized variants ConferenceRoom and Gym. 为了表达专用化,DTDL 支持继承:接口可以从一个或多个其他接口继承。To express specialization, DTDL supports inheritance: interfaces can inherit from one or more other interfaces.

下面的示例将 imagines 中的行星模型重新调整为更大CelestialBody模型的子类型。The following example re-imagines the Planet model from the earlier DTDL example as a subtype of a larger CelestialBody model. 首先定义 "parent" 模型,然后使用该字段在其上构建 "child" 模型 extendsThe "parent" model is defined first, and then the "child" model builds on it by using the field extends.

[
  {
    "@id": "dtmi:com:contoso:CelestialBody;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;2",
    "displayName": "Celestial body",
    "contents": [
      {
        "@type": "Property",
        "name": "name",
        "schema": "string"
      },
      {
        "@type": "Property",
        "name": "mass",
        "schema": "double"
      },
      {
        "@type": "Telemetry",
        "name": "temperature",
        "schema": "double"
      }
    ]
  },
  {
    "@id": "dtmi:com:contoso:Planet;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;2",
    "displayName": "Planet",
    "extends": "dtmi:com:contoso:CelestialBody;1",
    "contents": [
      {
        "@type": "Relationship",
        "name": "satellites",
        "target": "dtmi:com:contoso:Moon;1"
      },
      {
        "@type": "Component",
        "name": "deepestCrater",
        "schema": "dtmi:com:contoso:Crater;1"
      }
    ]
  },
  {
    "@id": "dtmi:com:contoso:Crater;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;2"
  }
]

在此示例中, CelestialBody行星提供名称、质量和温度。In this example, CelestialBody contributes a name, a mass, and a temperature to Planet. extends部分是接口名称或接口名称的数组, (允许扩展接口从多个父模型继承(如果需要)) 。The extends section is an interface name, or an array of interface names (allowing the extending interface to inherit from multiple parent models if desired).

应用继承后,扩展接口将公开整个继承链中的所有属性。Once inheritance is applied, the extending interface exposes all properties from the entire inheritance chain.

扩展接口无法更改父接口的任何定义;它只能添加到其中。The extending interface cannot change any of the definitions of the parent interfaces; it can only add to them. 即使将功能定义为同一) ,它也不能重新定义已在任何父接口中定义的功能 (。It also cannot redefine a capability already defined in any of its parent interfaces (even if the capabilities are defined to be the same). 例如,如果父接口定义了一个 double 属性质量,则扩展接口不能包含质量的声明,即使它也是 doubleFor example, if a parent interface defines a double property mass, the extending interface cannot contain a declaration of mass, even if it's also a double.

验证模型Validating models

提示

建议在将模型上传到 Azure 数字孪生实例之前,先对其进行验证。It's recommended to validate your models offline before uploading them to your Azure Digital Twins instance.

有一种与语言无关的示例可用于验证模型文档,以确保 DTDL 是正确的。There is a language-agnostic sample available for validating model documents to make sure the DTDL is correct. 其位置为: DTDL 验证器示例It is located here: DTDL Validator sample.

DTDL 验证器示例建立在一个 .NET DTDL 分析器库上,该库在 NuGet 上作为客户端库提供: DigitalTwinsThe DTDL validator sample is built on a .NET DTDL parser library, which is available on NuGet as a client-side library: Microsoft.Azure.DigitalTwins.Parser. 你还可以直接使用库来设计自己的验证解决方案。You can also use the library directly to design your own validation solution. 使用分析器库时,请确保使用与 Azure 数字孪生运行的版本兼容的版本。When using the parser library, make sure to use a version that is compatible with the version that Azure Digital Twins is running. 预览期间,此版本为3.7.0During preview, this is version 3.7.0.

可以在操作方法:分析和验证模型中了解有关分析器库的详细信息,包括用法示例。You can learn more about the parser library, including usage examples, in How-to: Parse and validate models.

后续步骤Next steps

请参阅如何通过 DigitalTwinsModels Api 管理模型:See how to manage models with the DigitalTwinsModels APIs:

或者,了解如何基于模型创建数字孪生:Or, learn about how digital twins are created based on models: