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

Статья
04/05/2023

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

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

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

LTS версии Node.js
Последние версии 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 Digital Twins представляет собой службу Интернета вещей, с помощью которой можно создать комплексные модели физического окружения. С ее помощью можно создавать пространственные интеллектуальные графы для моделирования связей и взаимодействий между людьми, пространствами и устройствами. Дополнительные сведения об Azure Digital Twins см. в документации по Azure Digital Twins.

`DigitalTwinsClient`

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

Примеры

Создание DigitalTwinsClient

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

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

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

Модель можно списыть с помощью decomissionModel идентификатора модели.

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

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

Мы можем удалить модель с помощью deleteModel идентификатора модели.

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

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

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

Чтобы создать двойник, необходимо указать идентификатор цифрового двойника и строку JSON, содержащую объект цифрового двойника.

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

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

Мы можем получить цифрового двойника с помощью getDigitalTwin идентификатора цифрового двойника.

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

Запрашивание цифровых двойников

Запросите экземпляр Azure Digital Twins для цифровых двойников с помощью языка запросов Azure Digital Twins. Ниже приведен пример того, как запрашивать цифровые двойники и как выполнять итерацию по результатам.

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

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

Мы можем удалить цифрового двойника с помощью deleteDigitalTwin идентификатора цифрового двойника.

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

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

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

Мы можем получить компонент цифрового двойника с помощью getComponent идентификатора цифрового двойника и пути к компоненту.

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

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

Чтобы обновить компонент цифрового двойника (т. е. заменить, удалить или добавить свойство компонента или подсвойства внутри цифрового двойника), необходимо указать идентификатор цифрового двойника, путь к компоненту и список объектов исправлений со свойствами 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 создает связь для цифрового двойника с идентификатором цифрового двойника, именем связи (в данном случае —has), идентификатором связи (в данном случае —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}`);
}

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

Создание маршрута событий

Чтобы создать маршрут событий, укажите идентификатор маршрута события (в данном случае myEventRouteId) и данные маршрута событий, содержащие конечную точку и необязательный фильтр, как показано в примере ниже. Дополнительные сведения о фильтрации событий см. в этой документации.

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

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

Мы можем получить маршрут события с помощью getEventRoute идентификатора маршрута события.

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 идентификатора маршрута события.

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

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

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

const digitalTwinId = "<digital twin ID>";
const telemetryPayload = '{"Telemetry1": 5}';
const response = await serviceClient.publishTelemetry(
  digitalTwinId,
  telemetryPayload,
  "<unique message 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. Кроме того, ведение журнала можно включить во время выполнения, вызвав setLogLevel в @azure/logger:

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

setLogLevel("info");

Более подробные инструкции по включению журналов см. в документации по пакету @azure и средства ведения журнала.

Дальнейшие действия

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

Участие

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

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

Поделиться через