Biblioteca de cliente do Azure Azure Digital Twins Core para JavaScript - versão 2.0.0

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

Como Começar

Ambientes atualmente suportados

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

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

Pré-requisitos

• Uma instância do Azure Digital Twins.

Instalar o pacote @azure/digital-twins-core

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

npm install @azure/digital-twins-core

Suporte de navegador

Pacote JavaScript

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

CORS

Atualmente, o Azure Digital Twins não suporta CORS (Cross-Origin Resource Sharing). Como resultado, essa biblioteca não pode ser usada para fazer chamadas diretas para o serviço de modelo a partir de um navegador. Consulte este documento para obter orientações.

Conceitos-chave

Gêmeos Digitais do Azure

O Azure Digital Twins é um serviço do Azure IoT que cria modelos abrangentes do ambiente físico. Ele pode criar gráficos 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 do Azure Digital Twins.

Exemplos

Criar o DigitalTwinsClient

Para criar um novo DigitalTwinsClient, você precisa do ponto de extremidade para uma instância e credenciais do Azure Digital Twins. Aqui, usamos DefaultAzureCredential para credenciais do pacote @azure/identity. Ele suporta diferentes mecanismos de autenticação e determina o tipo de credencial apropriado com base no ambiente em que está sendo executado. Consulte o readme for @azure/identity para 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

Usamos listModels para 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 desmantelamento

Podemos desativar um modelo usando decomissionModel 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 de 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 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 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 com 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";
await serviceClient.deleteDigitalTwin(digitalTwinId);

Obter e atualizar componentes de gêmeos digitais

Obter componente de gêmeo digital

Podemos obter um componente de gêmeo digital usando getComponent com o ID de 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 dentro de um gêmeo digital), você precisa fornecer uma ID de gêmeo digital, caminho do 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 gêmeo digital que está sendo atualizado. Para operações "substituir" e "adicionar", a value propriedade deve ser incluída com o valor desejado da propriedade 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 relacionamentos de gêmeos digitais

Crie relações de gêmeos digitais

upsertRelationship cria um relacionamento em um gêmeo digital fornecido com ID de um gêmeo digital, nome do relacionamento (neste caso, "tem"), ID de um relacionamento (neste caso "BuildingHasFloor") e o objeto que representa o relacionamento a ser criado. 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 digital, listRelationships e liste listIncomingRelationships todos os relacionamentos e todos os relacionamentos recebidos, 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 evento

Para criar uma rota de evento, forneça uma ID de uma rota de evento (neste caso, "myEventRouteId") e dados de rota de evento contendo o ponto de extremidade e o filtro opcional, como o exemplo mostrado abaixo. Para obter mais informações sobre filtragem de 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 de 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 listEventRouteso .

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 evento

Podemos excluir uma rota de evento usando deleteEventRoute com a ID de 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 o ID do gêmeo digital, a carga útil e um ID exclusivo 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 do ID do gêmeo digital, da carga útil e do ID de mensagem exclusivo, 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 de exemplos.

Solução de problemas

Exploração Florestal

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 AZURE_LOG_LEVEL variável de ambiente como info. Como alternativa, o registro em log pode ser habilitado em tempo de execução chamando setLogLevel o @azure/logger:

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

setLogLevel("info");

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

Próximos passos

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

Contribuir

Se você quiser contribuir para esta 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