Клиентская библиотека Azure Digital Twins Core для JavaScript — версия 2.0.0

2025-05-28

Этот пакет содержит изоморфный пакет SDK для API Azure Digital Twins для предоставления доступа к службе Azure Digital Twins для управления двойниками, моделями, отношениями и т. д.

Начало работы

Поддерживаемые в настоящее время среды

Версии Node.js LTS
Последние версии Safari, Chrome, Edge и Firefox.

Чтобы получить дополнительные сведения, ознакомьтесь с нашей политикой поддержки.

Предпосылки

Экземпляр Azure Digital Twins.

Установите пакет `@azure/digital-twins-core`.

Установите клиентскую библиотеку Digital Twins Core для JavaScript с помощью npm:

npm install @azure/digital-twins-core

Поддержка веб-браузеров

Пакет JavaScript

Чтобы использовать эту клиентную библиотеку в браузере, сначала необходимо использовать пакет. Дополнительные сведения о том, как это сделать, см. в нашей документации по объединением.

CORS (Совместное использование ресурсов разных источников)

Azure Digital Twins сейчас не поддерживает Предоставление общего доступа к ресурсам независимо от источника (CORS). В результате эта библиотека не может быть использована для прямых обращений к сервису шаблонов из браузера. Дополнительные сведения см. в этом документе.

Основные понятия

Azure Digital Twins (Цифровые Двойники Azure)

Azure Digital Twins — это служба Azure IoT, которая создает комплексные модели физической среды. Он может создавать графы пространственной аналитики для моделирования связей и взаимодействий между людьми, пространствами и устройствами. Дополнительные сведения об Azure Digital Twins см. в документации по Azure Digital Twins.

`DigitalTwinsClient`

DigitalTwinsClient — это клиентский объект, который пользователи этой библиотеки используют для управления экземпляром Azure Digital Twins.

Примеры

Создание клиента DigitalTwins

Чтобы создать новый DigitalTwinsClientдомен, требуется конечная точка для экземпляра Azure Digital Twins и учетные данные. Здесь мы используем 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}`);
}

Получить модель

Мы можем получить конкретную модель, используя 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>");

Модель вывода из эксплуатации

Мы можем вывести модель из эксплуатации, используя 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>");

Удаление модели

Мы можем удалить модель с помощью 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>");

Создание, получение, запрос и удаление цифровых двойников

Создание цифрового двойника

Чтобы создать двойник, необходимо указать идентификатор цифрового двойника и строку 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);

Получить цифровой двойник

Мы можем получить цифровой двойник с помощью 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 Digital Twins для цифровых двойников с помощью языка запросов Azure Digital Twins. Ниже приведен пример запроса цифровых двойников и итерации результатов.

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}`);
}

Удаление цифрового двойника

Мы можем удалить цифрового двойника с помощью 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);

Получение и обновление компонентов цифровых двойников

Получить компонент цифрового двойника

Мы можем получить компонент цифрового двойника, используя 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}`);

Обновление компонента цифрового двойника

Чтобы обновить компонент цифрового двойника (т. е. заменить, удалить или добавить свойство компонента или вложенное свойство в цифровом двойнике), необходимо предоставить идентификатор цифрового двойника, путь к компоненту и список объектов патчей со свойствами op и path. Значение op равно "replace", "remove" или "add", а значение value path — это путь к обновляемому компоненту цифрового двойника. Для операций "replace" и "add" свойство должно быть включено value в желаемое значение свойства компонента.

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 создает связь на цифровом двойнике с идентификатором цифрового двойника, именем связи (в данном случае «has»), идентификатором связи (в данном случае «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}`);
}

Создание, получение, список и удаление маршрутов событий

Создание маршрута мероприятия

Чтобы создать маршрут события, укажите идентификатор маршрута события (в данном случае "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);

Получить маршрут события

Мы можем получить маршрут события, используя 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}`);
}

Удалить маршрут события

Мы можем удалить маршрут события с помощью 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);

Публикация телеметрических сообщений для цифрового двойника

Чтобы опубликовать сообщение телеметрии для цифрового двойника, необходимо указать идентификатор цифрового двойника, полезные данные и уникальный идентификатор для сообщения.

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>",
);

Вы также можете опубликовать сообщение телеметрии для определенного компонента в цифровом двойнике. Помимо идентификатора цифрового двойника, полезной нагрузки и уникального идентификатора сообщения, необходимо указать путь к целевому компоненту.

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/loger.

Дальнейшие шаги

В каталоге примеров приведены подробные примеры, демонстрирующие использование клиентских библиотек.
Ознакомьтесь с документацией по Azure Digital Twins

Вклад

Если вы хотите внести свой вклад в эту библиотеку, ознакомьтесь с руководством по созданию и тестированию кода.

Пакет SDK Microsoft Azure для JavaScript