Partilhar via

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

  • Artigo

Este pacote contém um SDK isomórfico para a API do Azure Digital Twins para fornecer acesso ao serviço Azure Digital Twins para gerir duplos, modelos, relações, etc.

Introdução

Ambientes atualmente suportados

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

Pré-requisitos

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

Browser support (Suporte do browser)

Pacote JavaScript

Para utilizar esta biblioteca de cliente no browser, primeiro tem de utilizar um bundler. Para obter detalhes sobre como fazê-lo, veja a nossa documentação de agrupamento.

CORS

Atualmente, o Azure Digital Twins não suporta a Partilha de Recursos Transversais à Origem (CORS). Como resultado, esta biblioteca não pode ser utilizada para fazer chamadas diretas para o serviço de modelo a partir de um browser. Veja este documento para obter orientações.

Conceitos-chave

Azure Digital Twins

O Azure Digital Twins é um serviço do Azure IoT que cria modelos abrangentes do ambiente físico. Pode criar gráficos de inteligência espacial para modelar as relações e interações entre pessoas, espaços e dispositivos. Pode saber mais sobre o Azure Digital Twins ao visitar a Documentação do Azure Digital Twins.

DigitalTwinsClient

DigitalTwinsClient é o objeto de cliente que os utilizadores desta biblioteca utilizam para gerir a respetiva instância do Azure Digital Twins.

Exemplos

Criar o DigitalTwinsClient

Para criar um novo DigitalTwinsClient, precisa do ponto final para uma instância e credenciais do Azure Digital Twins. Aqui, utilizamos DefaultAzureCredential para credenciais do pacote @azure/identity. Suporta diferentes mecanismos de autenticação e determina o tipo de credencial adequado com base no ambiente em que está a ser executado. Veja para readme for @azure/identity obter mais informações sobre as diferentes opções de autenticação que pode utilizar.

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 eliminar modelos

Criar modelos

Para criar modelos, transmitimos uma lista de modelos para createModels. Aqui, só criamos 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

listModels Utilizamos 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 com getModel o ID de modelo.

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

Modelo de desativação

Podemos desativar um modelo com decomissionModel o ID do modelo.

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

Eliminar modelo

Podemos eliminar um modelo com deleteModel o ID do modelo.

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

Criar, obter, consultar e eliminar duplos digitais

Criar duplo digital

Para criar um duplo duplo, terá de fornecer um ID para o duplo digital e uma cadeia JSON que contenha o objeto duplo digital.

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

Obter duplo digital

Podemos obter um duplo digital com getDigitalTwin o ID do duplo digital.

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

Consultar duplos digitais

Consulte a instância do Azure Digital Twins para duplos digitais com a linguagem de consulta do Azure Digital Twins. Eis um exemplo de como consultar duplos digitais e como iterar os resultados.

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

Eliminar duplo digital

Podemos eliminar um duplo digital com deleteDigitalTwin o ID do duplo digital.

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

Obter e atualizar componentes de duplo digital

Obter componente de duplo digital

Podemos obter um componente de duplo digital com getComponent o ID do duplo 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 duplo digital

Para atualizar um componente de duplo digital (ou seja, substituir, remover ou adicionar uma propriedade de componente ou subprop propriedade num duplo digital), tem de fornecer um ID de duplo 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 de duplo digital que está a ser atualizado. Para operações de "substituir" e "adicionar", a value propriedade deve ser incluída com o valor pretendido 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 duplo digital

Criar relações de duplo digital

upsertRelationship cria uma relação num duplo digital fornecido com o ID de um duplo digital, o nome da relação (neste caso, "tem"), o ID de uma relação (neste caso"BuildingHasFloor") e o objeto que representa a relação a ser criada. O objeto tem de 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 duplos digitais

Para um duplo listRelationships digital e listIncomingRelationships lista todas as relações e todas as relações recebidas, respetivamente.

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 eliminar rotas de eventos

Criar rota de evento

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

Podemos obter uma rota de evento com getEventRoute o ID da rota de eventos.

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

Listar rotas de eventos

Podemos listar rotas de eventos com listEventRoutes.

const eventRoutes = serviceClient.listEventRoutes();
for await (const eventRoute of eventRoutes) {
  console.log(`EventRoute: ${eventRoute}`);
}

Eliminar rota de eventos

Podemos eliminar uma rota de evento com deleteEventRoute o ID da rota de eventos.

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

Publicar mensagens de telemetria para um duplo digital

Para publicar uma mensagem de telemetria para um duplo digital, tem de fornecer o ID do duplo digital, o payload e um ID exclusivo para a mensagem.

const digitalTwinId = "<digital twin ID>";
const telemetryPayload = '{"Telemetry1": 5}';
const response = await serviceClient.publishTelemetry(
  digitalTwinId,
  telemetryPayload,
  "<unique message ID>"
);

Também pode publicar uma mensagem de telemetria para um componente específico num duplo digital. Além do ID do duplo digital, payload e ID de mensagem exclusivo, tem de 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

Podem ser encontrados exemplos adicionais no diretório de exemplos.

Resolução de problemas

Registo

Ativar o registo pode ajudar a descobrir informações úteis sobre falhas. Para ver um registo de pedidos e respostas HTTP, defina a variável de AZURE_LOG_LEVEL ambiente como info. Em alternativa, o registo pode ser ativado no runtime ao chamar setLogLevel no @azure/logger:

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

setLogLevel("info");

Para obter instruções mais detalhadas sobre como ativar os registos, pode ver os documentos do pacote @azure/logger.

Passos seguintes

Contribuir

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