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

适用于 JavaScript 的 Azure Azure 数字孪生核心客户端库 - 版本 2.0.0

2025-05-28

此包包含适用于 Azure 数字孪生 API 的同构 SDK，用于提供对 Azure 数字孪生服务的访问权限，以管理孪生体、模型、关系等。

入门指南

当前支持的环境

LTS 版本的 Node.js
Safari、Chrome、Edge 和 Firefox 的最新版本。

有关详细信息，请参阅我们的支持策略。

先决条件

一个 Azure 数字孪生实例。

安装 `@azure/digital-twins-core` 包

使用以下命令 npm安装适用于 JavaScript 的 Digital Twins Core 客户端库：

npm install @azure/digital-twins-core

浏览器支持

JavaScript 捆绑包

若要在浏览器中使用此客户端库，首先需要使用捆绑程序。有关如何执行此操作的详细信息，请参阅我们的捆绑文档。

CORS

Azure 数字孪生目前不支持跨域资源共享 (CORS)。因此，此库不能用于从浏览器直接调用模板服务。有关指导，请参阅本文档。

重要概念

Azure 数字孪生

Azure 数字孪生是一项 Azure IoT 服务，用于创建物理环境的综合模型。它可以创建空间智能图来建模人员、空间和设备之间的关系和交互。可以通过访问 Azure 数字孪生文档了解有关 Azure 数字孪生的更多信息。

`DigitalTwinsClient`

DigitalTwinsClient 是此库的用户用于管理其 Azure 数字孪生实例的客户端对象。

例子

创建 DigitalTwinsClient

若要创建新的 DigitalTwinsClient，需要 Azure 数字孪生实例的终结点和凭据。在这里，我们使用 DefaultAzureCredential 包 @azure/identity中的凭据。它支持不同的身份验证机制，并根据执行环境确定适当的凭证类型。有关您可以使用的不同身份验证选项的更多信息，请参阅。readme for @azure/identity

import { DefaultAzureCredential } from "@azure/identity";
import { DigitalTwinsClient } from "@azure/digital-twins-core";

const url = "<URL to Azure Digital Twins instance>";
const credential = new DefaultAzureCredential();
const serviceClient = new DigitalTwinsClient(url, credential);

创建、列出、获取、停用和删除模型

创建模型

为了创建模型，我们将模型 createModels列表传递给。在这里，我们只创建一个模型。

import { DefaultAzureCredential } from "@azure/identity";
import { DigitalTwinsClient } from "@azure/digital-twins-core";

const url = "<URL to Azure Digital Twins instance>";
const credential = new DefaultAzureCredential();
const serviceClient = new DigitalTwinsClient(url, credential);

const myComponent = {
  "@id": "dtmi:my_component;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;2",
  displayName: "Component1",
  contents: [
    {
      "@type": "Property",
      name: "ComponentProp1",
      schema: "string",
    },
  ],
};

const models = await serviceClient.createModels([myComponent]);

列出模型

我们用来 listModels 列出所有模型。

import { DefaultAzureCredential } from "@azure/identity";
import { DigitalTwinsClient } from "@azure/digital-twins-core";

const url = "<URL to Azure Digital Twins instance>";
const credential = new DefaultAzureCredential();
const serviceClient = new DigitalTwinsClient(url, credential);

const models = serviceClient.listModels();
for await (const model of models) {
  console.log(`Model ID: ${model.id}`);
}

获取模型

我们可以使用模型 ID 来获取特定模型 getModel 。

import { DefaultAzureCredential } from "@azure/identity";
import { DigitalTwinsClient } from "@azure/digital-twins-core";

const url = "<URL to Azure Digital Twins instance>";
const credential = new DefaultAzureCredential();
const serviceClient = new DigitalTwinsClient(url, credential);

const model = await serviceClient.getModel("<model ID>");

停用模型

我们可以使用模型 ID 停用模型 decomissionModel 。

import { DefaultAzureCredential } from "@azure/identity";
import { DigitalTwinsClient } from "@azure/digital-twins-core";

const url = "<URL to Azure Digital Twins instance>";
const credential = new DefaultAzureCredential();
const serviceClient = new DigitalTwinsClient(url, credential);

await serviceClient.decomissionModel("<model ID>");

删除模型

我们可以使用模型 ID 删除模型 deleteModel 。

import { DefaultAzureCredential } from "@azure/identity";
import { DigitalTwinsClient } from "@azure/digital-twins-core";

const url = "<URL to Azure Digital Twins instance>";
const credential = new DefaultAzureCredential();
const serviceClient = new DigitalTwinsClient(url, credential);

await serviceClient.deleteModel("<model ID>");

创建、获取、查询和删除数字孪生

创建数字孪生

若要创建孪生体，需要提供数字孪生体的 ID 和包含数字孪生体对象的 JSON 字符串。

import { DefaultAzureCredential } from "@azure/identity";
import { DigitalTwinsClient } from "@azure/digital-twins-core";

const url = "<URL to Azure Digital Twins instance>";
const credential = new DefaultAzureCredential();
const serviceClient = new DigitalTwinsClient(url, credential);

const digitalTwinId = "myTwin";
const newTwin = "<JSON containing the digitalTwin object>";
const createdTwin = await serviceClient.upsertDigitalTwin(digitalTwinId, newTwin);

获取数字孪生

我们可以使用数字孪生 ID 来获得数字孪生 getDigitalTwin 。

import { DefaultAzureCredential } from "@azure/identity";
import { DigitalTwinsClient } from "@azure/digital-twins-core";

const url = "<URL to Azure Digital Twins instance>";
const credential = new DefaultAzureCredential();
const serviceClient = new DigitalTwinsClient(url, credential);

const digitalTwinId = "myTwin";
const twin = await serviceClient.getDigitalTwin(digitalTwinId);
console.log(`DigitalTwin's etag: ${twin.etag}`);
console.log(`DigitalTwin: ${twin}`);

查询数字孪生

使用 Azure 数字孪生查询语言查询数字孪生的 Azure 数字孪生实例。下面是如何查询数字孪生体以及如何迭代结果的示例。

import { DefaultAzureCredential } from "@azure/identity";
import { DigitalTwinsClient } from "@azure/digital-twins-core";

const url = "<URL to Azure Digital Twins instance>";
const credential = new DefaultAzureCredential();
const serviceClient = new DigitalTwinsClient(url, credential);

const query = "SELECT * FROM digitaltwins";
const queryResult = serviceClient.queryTwins(query);
for await (const item of queryResult) {
  console.log(`DigitalTwin: ${item}`);
}

删除数字孪生体

我们可以使用数字孪生体 ID 删除数字孪生 deleteDigitalTwin 体。

import { DefaultAzureCredential } from "@azure/identity";
import { DigitalTwinsClient } from "@azure/digital-twins-core";

const url = "<URL to Azure Digital Twins instance>";
const credential = new DefaultAzureCredential();
const serviceClient = new DigitalTwinsClient(url, credential);

const digitalTwinId = "myTwin";
await serviceClient.deleteDigitalTwin(digitalTwinId);

获取和更新数字孪生组件

获取数字孪生组件

我们可以使用数字孪生 ID 和组件的路径来获取数字孪生组件 getComponent 。

import { DefaultAzureCredential } from "@azure/identity";
import { DigitalTwinsClient } from "@azure/digital-twins-core";

const url = "<URL to Azure Digital Twins instance>";
const credential = new DefaultAzureCredential();
const serviceClient = new DigitalTwinsClient(url, credential);

const digitalTwinId = "myTwin";
const componentPath = "Component1";
const component = await serviceClient.getComponent(digitalTwinId, componentPath);
console.log(`Component: ${component}`);

更新数字孪生组件

要更新数字孪生体组件（即替换、删除或添加数字孪生体中的组件属性或子属性），您需要提供数字孪生体 ID、组件路径以及具有属性 op 和 path的补丁对象列表。的 op 值为 “replace”、“remove” 或 “add”，值的 path 是要更新的数字孪生组件的路径。对于 “replace” 和 “add”作，该 value 属性应包含在所需的 component 属性值中。

import { DefaultAzureCredential } from "@azure/identity";
import { DigitalTwinsClient } from "@azure/digital-twins-core";

const url = "<URL to Azure Digital Twins instance>";
const credential = new DefaultAzureCredential();
const serviceClient = new DigitalTwinsClient(url, credential);

const digitalTwinId = "myTwin";
const componentPath = "Component1";
const patch = {
  op: "replace",
  path: "/ComponentProp1",
  value: "value2",
};
const updateComponentResponse = await serviceClient.updateComponent(digitalTwinId, componentPath, [
  patch,
]);

创建和列出数字孪生关系

创建数字孪生关系

upsertRelationship 在数字孪生体上创建关系，该数字孪生体提供了数字孪生体的 ID、关系名称（在本例中为“has”）、关系的 ID（在本例中为“BuildingHasFloor”）以及表示要创建的关系的对象。对象必须包含键为“$targetId”的属性，以指定关系的目标。

import { DefaultAzureCredential } from "@azure/identity";
import { DigitalTwinsClient } from "@azure/digital-twins-core";

const url = "<URL to Azure Digital Twins instance>";
const credential = new DefaultAzureCredential();
const serviceClient = new DigitalTwinsClient(url, credential);

const relationship = {
  $relationshipId: "BuildingHasFloor",
  $sourceId: "BuildingTwin",
  $relationshipName: "has",
  $targetId: "FloorTwin",
  isAccessRestricted: false,
};

await serviceClient.upsertRelationship(
  relationship["$sourceId"],
  relationship["$relationshipId"],
  relationship,
);

列出数字孪生关系

对于数字孪生体， listRelationships 请 listIncomingRelationships 分别列出所有关系和所有传入关系。

import { DefaultAzureCredential } from "@azure/identity";
import { DigitalTwinsClient } from "@azure/digital-twins-core";

const url = "<URL to Azure Digital Twins instance>";
const credential = new DefaultAzureCredential();
const serviceClient = new DigitalTwinsClient(url, credential);

const digitalTwinId = "myTwin";
const relationships = serviceClient.listRelationships(digitalTwinId);
for await (const relationship of relationships) {
  console.log(`Relationship: ${relationship}`);
}

import { DefaultAzureCredential } from "@azure/identity";
import { DigitalTwinsClient } from "@azure/digital-twins-core";

const url = "<URL to Azure Digital Twins instance>";
const credential = new DefaultAzureCredential();
const serviceClient = new DigitalTwinsClient(url, credential);

const digitalTwinId = "myTwin";
const incomingRelationships = serviceClient.listIncomingRelationships(digitalTwinId);
for await (const incomingRelationship of incomingRelationships) {
  console.log(`Relationship: ${incomingRelationship}`);
}

创建、获取、列出和删除事件路由

创建事件路由

要创建事件路由，请提供事件路由的 ID（在本例中为“myEventRouteId”）和包含终端节点和可选筛选条件的事件路由数据，如下例所示。有关筛选事件的更多信息，请参阅此文档。

import { DefaultAzureCredential } from "@azure/identity";
import { DigitalTwinsClient } from "@azure/digital-twins-core";

const url = "<URL to Azure Digital Twins instance>";
const credential = new DefaultAzureCredential();
const serviceClient = new DigitalTwinsClient(url, credential);

const eventHubEndpointName = "myEventHubEndpointName";
const eventRouteId = "myEventRouteId";
const eventFilter =
  "$eventType = 'DigitalTwinTelemetryMessages' or $eventType = 'DigitalTwinLifecycleNotification'";
await serviceClient.upsertEventRoute(eventRouteId, eventHubEndpointName, eventFilter);

获取事件路由

我们可以将事件路由与事件路由 ID 结合使用 getEventRoute 。

import { DefaultAzureCredential } from "@azure/identity";
import { DigitalTwinsClient } from "@azure/digital-twins-core";

const url = "<URL to Azure Digital Twins instance>";
const credential = new DefaultAzureCredential();
const serviceClient = new DigitalTwinsClient(url, credential);

const eventRouteId = "myEventRouteId";
const eventRoute = serviceClient.getEventRoute(eventRouteId);
console.log(`EventRoute: ${eventRoute}`);

列出事件路由

我们可以使用 listEventRoutes列出事件路由。

import { DefaultAzureCredential } from "@azure/identity";
import { DigitalTwinsClient } from "@azure/digital-twins-core";

const url = "<URL to Azure Digital Twins instance>";
const credential = new DefaultAzureCredential();
const serviceClient = new DigitalTwinsClient(url, credential);

const eventRoutes = serviceClient.listEventRoutes();
for await (const eventRoute of eventRoutes) {
  console.log(`EventRoute: ${eventRoute}`);
}

删除事件路由

我们可以使用 event route ID 删除事件路由 deleteEventRoute 。

import { DefaultAzureCredential } from "@azure/identity";
import { DigitalTwinsClient } from "@azure/digital-twins-core";

const url = "<URL to Azure Digital Twins instance>";
const credential = new DefaultAzureCredential();
const serviceClient = new DigitalTwinsClient(url, credential);

const eventRouteId = "myEventRouteId";
await serviceClient.deleteEventRoute(eventRouteId);

发布数字孪生体的遥测消息

要发布数字孪生体的遥测消息，您需要提供数字孪生体 ID、有效负载和消息的唯一 ID。

import { DefaultAzureCredential } from "@azure/identity";
import { DigitalTwinsClient } from "@azure/digital-twins-core";

const url = "<URL to Azure Digital Twins instance>";
const credential = new DefaultAzureCredential();
const serviceClient = new DigitalTwinsClient(url, credential);

const digitalTwinId = "<digital twin ID>";
const telemetryPayload = { Telemetry1: 5 };
const response = await serviceClient.publishTelemetry(
  digitalTwinId,
  telemetryPayload,
  "<unique message ID>",
);

您还可以为数字孪生中的特定组件发布遥测消息。除了数字孪生 ID、负载和唯一消息 ID 外，您还需要指定目标组件路径。

import { DefaultAzureCredential } from "@azure/identity";
import { DigitalTwinsClient } from "@azure/digital-twins-core";

const url = "<URL to Azure Digital Twins instance>";
const credential = new DefaultAzureCredential();
const serviceClient = new DigitalTwinsClient(url, credential);

const digitalTwinId = "<digital twin ID>";
const componentPath = "<component path>";
const telemetryPayload = { Telemetry1: 5 };
const response = await serviceClient.publishComponentTelemetry(
  digitalTwinId,
  componentPath,
  telemetryPayload,
  "<unique message ID>",
);

其他示例

其他示例可以在 samples 目录中找到。

故障排除

伐木业

启用日志记录可能有助于发现有关故障的有用信息。若要查看 HTTP 请求和响应的日志，请将 AZURE_LOG_LEVEL 环境变量设置为 info。或者，可以通过在 setLogLevel中调用 @azure/logger 在运行时启用日志记录：

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

有关如何启用日志的更详细说明，请查看 @azure/logger 包文档。

后续步骤

查看 samples 目录，了解演示如何使用客户端库的详细示例。
浏览 Azure 数字孪生文档

贡献

若要参与此库，请阅读贡献指南了解有关如何生成和测试代码的详细信息。

适用于 Javascript 的 Microsoft Azure SDK

通过