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

数字孪生体及其孪生体图

项目
01/03/2024

本文介绍在 Azure 数字孪生上下文中的数字孪生体是什么，以及它们之间的关系如何形成孪生体图。在 Azure 数字孪生解决方案中，环境中的实体是由数字孪生体表示的。数字孪生体是你自定义的模型之一的实例。可以通过关系将其连接到其他数字孪生体以形成孪生图：此孪生图是整个环境的表示形式。

提示

“Azure 数字孪生”是指作为一个整体的此 Azure 服务。 “数字孪生体”或“孪生体”是指此服务的实例中的单个孪生节点。

数字孪生

你需要将模型上传到此服务，然后才能在 Azure 数字孪生实例中创建数字孪生体。模型描述特定孪生体可以具有的属性和关系集，等等。有关在模型中定义的信息的类型，请参阅自定义模型。

创建并上传模型后，客户端应用就可以创建该类型的实例了。此实例是一个数字孪生体。例如，在创建“Floor”的模型后，你可以创建使用此类型的一个或几个数字孪生体（例如，“Floor”类型的一个孪生体称为“GroundFloor”，另一个称为“Floor2”，等等）。

注意

Azure 数字孪生中的数字孪生不同于IoT 中心中的设备孪生。 IoT 中心设备孪生通常专注于描述设备本身的各个方面和功能，而 Azure 数字孪生中的孪生则是更具概念性的表示形式，可以存储用户定义的有关设备或许多相关设备的见解。

IoT 中心中的设备可以连接到 Azure 数字孪生，作为端到端解决方案的一部分，该解决方案代表跨服务的设备。

关系：数字孪生体的图

孪生体通过其关系连接成为孪生图。孪生体可以具有的关系定义为其模型的一部分。

例如，模型 Floor 可以定义针对 Room 类型的孪生体的 contains 关系。有了此定义，你就可以通过 Azure 数字孪生创建从任何 Floor 孪生体到任何 Room 孪生体（包括属于 Room 子类型的孪生体）的 contains 关系。

此过程的结果是一组节点（数字孪生体），它们通过图中的边（它们的关系）连接在一起。

可视化效果

Azure Digital Twins Explorer 是一种可视化工具，用于浏览 Azure 数字孪生图中的数据。你可以使用此资源管理器查看、查询和编辑模型、孪生和关系。

若要了解 Azure Digital Twins Explorer 工具，请参阅 Azure Digital Twins Explorer。如需各项功能的详细使用步骤，请参阅使用 Azure Digital Twins Explorer。

下面展示了可视化效果：

使用 API 进行创建

本部分显示了从客户端应用程序创建数字孪生体和关系时的情况。它包含使用 DigitalTwins API 的 .NET SDK 示例，提供有关其中每个概念中发生的内容的更多上下文。

创建数字孪生

下面是客户端代码的一个片段，它使用 DigitalTwins API 来实例化 Room 类型的孪生体，并在实例化过程中定义 twinId。

你可以在创建孪生体时对其属性进行初始化，也可以稍后设置这些属性。若要创建具有已初始化属性的孪生体，请创建一个提供必要初始化值的 JSON 文档。

// Define a custom model type for the twin to be created

internal class CustomDigitalTwin
{
    [JsonPropertyName(DigitalTwinsJsonPropertyNames.DigitalTwinId)]
    public string Id { get; set; }

    [JsonPropertyName(DigitalTwinsJsonPropertyNames.DigitalTwinETag)]
    public string ETag { get; set; }

    [JsonPropertyName("temperature")]
    public double Temperature { get; set; }

    [JsonPropertyName("humidity")]
    public double Humidity{ get; set; }
}

// Initialize properties and create the twin
public class TwinOperationsCreateTwin
{
    public async Task CreateTwinAsync(DigitalTwinsClient client)
    {
        // Initialize the twin properties
        var myTwin = new CustomDigitalTwin
        {
            Temperature = 25.0,
            Humidity = 50.0,
        };

        // Create the twin
        const string twinId = "<twin-ID>";
        Response<CustomDigitalTwin> response = await client.CreateOrReplaceDigitalTwinAsync(twinId, myTwin);
        Console.WriteLine($"Temperature value: {response.Value.Temperature}");
    }
}

你还可以使用名为 BasicDigitalTwin 的帮助程序类更直接地将属性字段存储在“孪生体”对象中，这是一种替代字典的方法。有关帮助程序类及其用法示例的详细信息，请参阅创建数字孪生体。

注意

虽然孪生体属性被视为可选属性，因此不需要初始化，但在创建孪生体时，需要设置孪生体上的所有组件。它们可以是空对象，但组件本身必须存在。

创建关系

下面是一些示例客户端代码，这些代码使用 DigitalTwins API 构建从一个数字孪生体（“源”孪生体）到另一个数字孪生体（“目标”孪生体）的关系。

public async Task CreateRelationship(DigitalTwinsClient client)
{
    var rel = new BasicRelationship
    {
        TargetId = "myTargetTwin",
        Name = "contains", // a relationship with this name must be defined in the model
        // Initialize properties
        Properties =
        {
            { "active", true },
        },
    };
    await client.CreateOrReplaceRelationshipAsync("mySourceTwin", "rel001", rel);
}

使用导入作业 API 批量创建孪生体和关系

可以使用导入作业 API 在单个 API 调用中上传许多孪生体和关系。使用此 API 创建的孪生体和关系可以选择包括其属性的初始化。有关使用此 API 的详细说明和示例，请参阅孪生体和关系的批量导入说明。

删除图形元素

若要删除特定的孪生体和关系，请使用 DigitalTwins Delete 和 DigitalTwins DeleteRelationship API（也可作为 CLI 命令和 SDK 调用提供）。

若要一次性删除实例中的所有模型、孪生体和关系，请使用 “删除作业”API。

图形元素的 JSON 表示形式

数字孪生体数据和关系数据均以 JSON 格式存储，这意味着，当你在 Azure 数字孪生实例中查询孪生图时，结果将是你已创建的数字孪生体和关系的 JSON 表示形式。

数字孪生体 JSON 格式

当表示为 JSON 对象时，数字孪生体会显示以下字段：

字段名称	说明
`$dtId`	用户提供的字符串，表示数字孪生体的 ID
`$etag`	由 Web 服务器分配的标准 HTTP 字段
`$metadata.$model`	将此数字孪生体特征化的模型接口的 ID
`$metadata.<property-name>`	有关数字孪生体属性的其他元数据信息
`$metadata.<property-name>.lastUpdateTime`	Azure 数字孪生处理属性更新消息时的日期/时间。
`$metadata.<property-name>.sourceTime`	一个可选的可写属性，表示在现实世界中观察到属性更新时的时间戳。此属性只能使用 2022-05-31 版本的 Azure 数字孪生 API/SDK 写入，并且值必须符合 ISO 8601 日期和时间格式。若要详细了解如何更新此属性，请参阅更新属性的 sourceTime。
`<property-name>`	属性的值，表示为 JSON 形式（`string`、数字类型或对象）
`$relationships`	关系集合的路径的 URL。如果数字孪生体没有传出的关系边，则此字段不存在。
`<component-name>`	一个 JSON 对象，包含组件的属性值和元数据，类似于根对象的那些属性值和元数据。即使组件没有属性，此对象也存在。
`<component-name>.$metadata`	组件的元数据信息，类似于根级别 `$metadata`
`<component-name>.<property-name>`	组件的属性的值，表示为 JSON 形式（`string`、数字类型或对象）

下面是一个格式设置为 JSON 对象的数字孪生体的示例。此孪生体有两个属性：Humidity 和 Temperature，以及一个名为 Thermostat 的组件。

{
    "$dtId": "myRoomID",
    "$etag": "W/\"8e6d3e89-1166-4a1d-9a99-8accd8fef43f\"",
    "$metadata": {
        "$model": "dtmi:example:Room23;1",
        "Humidity": {
          "lastUpdateTime": "2021-11-30T18:47:53.7648958Z"
        },
        "Temperature": {
          "lastUpdateTime": "2021-11-30T18:47:53.7648958Z"
        }
    },
    "Humidity": 55,
    "Temperature": 35,
    "Thermostat": {
        "$metadata": {}
    }

关系 JSON 格式

当表示为 JSON 对象时，数字孪生体中的关系会显示以下字段：

字段名称	说明
`$relationshipId`	用户提供的字符串，表示此关系的 ID。此字符串在源数字孪生体的上下文中是唯一的，这也意味着 `sourceId` + `relationshipId` 在 Azure 数字孪生实例的上下文中是唯一的。
`$etag`	由 Web 服务器分配的标准 HTTP 字段
`$sourceId`	源数字孪生体的 ID
`$targetId`	目标数字孪生体的 ID
`$relationshipName`	关系的名称
`<property-name>`	[可选] 此关系的属性的值，表示为 JSON 形式（`string`、数字类型或对象）

下面是一个格式设置为 JSON 对象的关系的示例：

{
  "$relationshipId": "relationship-01",
  "$etag": "W/\"506e8391-2b21-4ac9-bca3-53e6620f6a90\"",
  "$sourceId": "GroundFloor",
  "$targetId": "Cafe",
  "$relationshipName": "contains",
  "startDate": "2020-02-04"
}

后续步骤

请参阅如何通过 Azure 数字孪生 API 管理图形元素：

或者，了解如何查询 Azure 数字孪生的孪生图来获取相关信息：

查询语言