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

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

项目
04/05/2023

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

入门

目前支持的环境

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

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

先决条件

Azure 数字孪生实例。

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

使用 npm安装适用于 JavaScript 的数字孪生核心客户端库：

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有关可以使用的不同身份验证选项的详细信息，请参阅。

const { DefaultAzureCredential } = require("@azure/identity");
const { DigitalTwinsClient } = require("@azure/digital-twins-core");

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

创建、列出、获取、解除授权和删除模型

创建模型

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

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 列出所有模型。

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

获取模型

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

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

停用模型

我们可以使用 decomissionModel 和模型 ID 来解除模型授权。

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

删除模型

可以使用和模型 deleteModel ID 一起使用来删除模型。

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

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

创建数字孪生体

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

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

获取数字孪生

可以使用数字孪生 ID getDigitalTwin 获取数字孪生体。

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

查询数字孪生

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

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

删除数字孪生体

可以使用带有数字孪生体 deleteDigitalTwin ID 删除数字孪生体。

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

获取和更新数字孪生组件

获取数字孪生组件

可以使用数字孪生体 getComponent ID 和组件路径获取数字孪生组件。

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 要更新的数字孪生组件的路径。对于“替换”和“添加”操作， value 属性应包含在组件属性的所需值中。

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”的属性，以指定关系的目标。

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

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

列出数字孪生关系

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

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

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

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

创建事件路由

若要创建事件路由，请提供事件路由的 ID (在本例中，“myEventRouteId”) ，以及包含终结点和可选筛选器的事件路由数据，如下所示。有关筛选事件的详细信息，请参阅此文档。

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

获取事件路由

可以使用和事件路由 getEventRoute ID 获取事件路由。

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

列出事件路由

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

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

删除事件路由

可以使用带有事件路由 deleteEventRoute ID 删除事件路由。

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

发布数字孪生的遥测消息

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

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

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

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

其他示例

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

疑难解答

日志记录

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

const { setlogLevel } = require("@azure/logger");

setLogLevel("info");

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

后续步骤

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

贡献

若要为此库做出贡献，请阅读贡献指南，详细了解如何生成和测试代码。

Microsoft Azure SDK for Javascript

通过