Biblioteca de clientes do Azure Digital Twins Core para JavaScript – versão 2.0.0

Este pacote contém um SDK isomórfico para a API dos Gêmeos Digitais do Azure para fornecer acesso ao serviço dos Gêmeos Digitais do Azure para gerenciar gêmeos, modelos, relações etc.

Como começar

Ambientes com suporte no momento

• Versões LTS do Node.js
• Versões mais recentes do Safari, Chrome, Edge e Firefox.

Consulte nossa política de suporte para obter mais detalhes.

Pré-requisitos

• Uma instância dos Gêmeos Digitais do Azure.

Instalar o pacote @azure/digital-twins-core

Instale a biblioteca de cliente do Digital Twins Core para JavaScript com npm:

npm install @azure/digital-twins-core

Suporte ao navegador

Pacote JavaScript

Para usar essa biblioteca de clientes no navegador, primeiro você precisa usar um empacotador. Para obter detalhes sobre como fazer isso, consulte nossa documentação de agrupamento .

CORS

Atualmente, os Gêmeos Digitais do Azure não dão suporte ao CORS (compartilhamento de recursos entre origens) . Como resultado, essa biblioteca não pode ser usada para fazer chamadas diretas para o serviço de modelo de um navegador. Consulte este documento para obter diretrizes.

Conceitos principais

Gêmeos Digitais do Azure

Os Gêmeos Digitais do Azure são um serviço do Azure IoT que cria modelos abrangentes do ambiente físico. Ele pode criar grafos de inteligência espacial para modelar as relações e interações entre pessoas, espaços e dispositivos. Você pode saber mais sobre os Gêmeos Digitais do Azure visitando a Documentação dos Gêmeos Digitais do Azure.

DigitalTwinsClient

DigitalTwinsClient é o objeto de cliente que os usuários dessa biblioteca usam para gerenciar sua instância dos Gêmeos Digitais do Azure.

Exemplos

Criar o DigitalTwinsClient

Para criar um novo DigitalTwinsClient, você precisa do ponto de extremidade para uma instância e credenciais dos Gêmeos Digitais do Azure. Aqui, usamos DefaultAzureCredential para credenciais do pacote @azure/identity. Ele oferece suporte a diferentes mecanismos de autenticação e determina o tipo de credencial apropriado com base no ambiente em que está sendo executado. Consulte o para readme for @azure/identity obter mais informações sobre as diferentes opções de autenticação que você pode usar.

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

Criar, listar, obter, desativar e excluir modelos

Criar modelos

Para criar modelos, passamos uma lista de modelos para createModels. Aqui, criamos apenas um modelo.

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]);

Listar modelos

Costumamos listModels listar todos os modelos.

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

Obter modelo

Podemos obter um modelo específico usando getModel com o ID do modelo.

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

Modelo de desativação

Podemos desativar um modelo usando decomissionModel com o ID do modelo.

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

Excluir modelo

Podemos excluir um modelo usando deleteModel com o ID do modelo.

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

Criar, obter, consultar e excluir gêmeos digitais

Criar gêmeo digital

Para criar um gêmeo, você precisará fornecer uma ID para o gêmeo digital e uma cadeia de caracteres JSON contendo o objeto do gêmeo digital.

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

Obter gêmeo digital

Podemos obter um gêmeo digital usando getDigitalTwin o ID do gêmeo digital.

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

Consultar os gêmeos digitais

Consulte a instância dos Gêmeos Digitais do Azure para gêmeos digitais usando a linguagem de consulta dos Gêmeos Digitais do Azure. Aqui está um exemplo de como consultar gêmeos digitais e como iterar sobre os resultados.

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

Excluir gêmeo digital

Podemos excluir um gêmeo digital usando deleteDigitalTwin a ID do gêmeo digital.

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

Obter e atualizar componentes de gêmeos digitais

Obtenha o componente de gêmeo digital

Podemos obter um componente de gêmeo digital usando getComponent o ID do gêmeo digital e o caminho do componente.

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

Atualizar componente de gêmeo digital

Para atualizar um componente de gêmeo digital (ou seja, substituir, remover ou adicionar uma propriedade ou subpropriedade de componente em um gêmeo digital), você precisa fornecer uma ID de gêmeo digital, um caminho de componente e uma lista de objetos de patch com as propriedades op e path. O valor de op é "substituir", "remover" ou "adicionar" e o valor de path é o caminho para o componente do gêmeo digital que está sendo atualizado. Para as operações "substituir" e "adicionar", a value propriedade deve ser incluída com o valor desejado da propriedade do componente.

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

Criar e listar relações de gêmeos digitais

Criar relações de gêmeos digitais

upsertRelationship cria uma relação em um gêmeo digital fornecido com a ID de um gêmeo digital, o nome da relação (nesse caso, "tem"), a ID de uma relação (nesse caso, "BuildingHasFloor") e o objeto que representa a relação a ser criada. O objeto deve conter a propriedade com a chave "$targetId" para especificar o destino da relação.

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

Listar relacionamentos de gêmeos digitais

Para um gêmeo listRelationships digital e liste listIncomingRelationships todas as relações e todas as relações de entrada, respectivamente.

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

Criar, obter, listar e excluir rotas de eventos

Criar rota de eventos

Para criar uma rota de eventos, forneça uma ID de uma rota de eventos (nesse caso, "myEventRouteId") e dados de rota de eventos que contenham o endpoint e o filtro opcional, como o exemplo mostrado abaixo. Para obter mais informações sobre como filtrar eventos, consulte esta documentação.

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

Obter rota do evento

Podemos obter uma rota de evento usando getEventRoute o ID da rota do evento.

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

Listar rotas de eventos

Podemos listar rotas de eventos usando 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}`);
}

Excluir rota de eventos

Podemos excluir uma rota de evento usando deleteEventRoute com o ID da rota do evento.

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

Publicar mensagens de telemetria para um gêmeo digital

Para publicar uma mensagem de telemetria para um gêmeo digital, você precisa fornecer a ID do gêmeo digital, a carga e uma ID exclusiva para a mensagem.

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

Você também pode publicar uma mensagem de telemetria para um componente específico em um gêmeo digital. Além da ID do gêmeo digital, da carga e da ID de mensagem exclusiva, você precisa especificar o caminho do componente de destino.

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

Exemplos adicionais

Exemplos adicionais podem ser encontrados no diretório samples.

Resolução de problemas

Registro

Habilitar o registro em log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de ambiente AZURE_LOG_LEVEL como info. Como alternativa, o registro em log pode ser habilitado em runtime chamando setLogLevel no @azure/logger:

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

setLogLevel("info");

Para obter instruções mais detalhadas sobre como habilitar logs, veja os documentos do pacote @azure/logger.

Próximas etapas

• Dê uma olhada no diretório samples para obter exemplos detalhados que demonstram como usar as bibliotecas de cliente.
• Explore a documentação dos Gêmeos Digitais do Azure

Contribuindo

Se você quiser contribuir com essa biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.

Projetos relacionados

• SDK do Microsoft Azure para Javascript