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

  • Artigo

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

Introdução

Ambientes com suporte no momento

Confira nossa política de suporte para mais detalhes.

Pré-requisitos

Instalar o pacote @azure/digital-twins-core

Instale a biblioteca de clientes 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.

Principais conceitos

Gêmeos Digitais do Azure

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

DigitalTwinsClient

DigitalTwinsClient é o objeto cliente que os usuários dessa biblioteca usam para gerenciar a 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 dá 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 readme for @azure/identity para obter mais informações sobre as diferentes opções de autenticação que você pode usar.

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

Criar, listar, obter, desativar e excluir modelos

Criar modelos

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

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.

const models = await 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 a ID do modelo.

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

Desativar modelo

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

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

Excluir modelo

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

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 que contém o objeto gêmeo digital.

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

Obter o gêmeo digital

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

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

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.

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 a ID do gêmeo digital.

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

Obter e atualizar componentes do gêmeo digital

Obter componente de gêmeo digital

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

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 de componente ou subpropriedade dentro de 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 é "replace", "remove" ou "add" e o valor de path é o caminho para o componente de 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 do componente.

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êmeo digital

Criar relações de gêmeo digital

upsertRelationship cria uma relação em um gêmeo digital fornecido com a ID de um gêmeo digital, nome da relação (nesse caso, "tem"), ID de uma relação (neste 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.

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

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

Listar relações de gêmeo digital

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

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

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 (nesse caso, "myEventRouteId") e dados de rota de evento que contêm o ponto de extremidade e o filtro opcional, como o exemplo mostrado abaixo. Para obter mais informações sobre como filtrar eventos, consulte esta documentação.

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

Obter rota de evento

Podemos obter uma rota de evento usando getEventRoute com a ID da rota de evento.

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

Listar rotas de eventos

Podemos listar rotas de evento usando listEventRoutes.

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 da rota de evento.

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, o conteúdo e uma ID exclusiva para a mensagem.

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, do conteúdo e da ID de mensagem exclusiva, você precisa especificar o caminho do componente de destino.

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

Log

A habilitação do 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 log pode ser habilitado no runtime chamando setLogLevel em @azure/logger:

const { setlogLevel } = require("@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 de exemplos para obter exemplos detalhados que demonstram como usar as bibliotecas de cliente.
  • Explorar a documentação dos Gêmeos Digitais do Azure

Contribuição

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