Biblioteca cliente principal de Azure Digital Twins para JavaScript: versión 2.0.0

2025-05-28

Este paquete contiene un SDK isomórfico para la API de Azure Digital Twins para proporcionar acceso al servicio Azure Digital Twins para administrar gemelos, modelos, relaciones, etc.

Cómo empezar

Entornos admitidos actualmente

Versiones de LTS de Node.js
Versiones más recientes de Safari, Chrome, Edge y Firefox.

Consulte nuestra de directiva de soporte técnico de para obtener más información.

Prerrequisitos

Una instancia de Azure Digital Twins.

Instalación del paquete `@azure/digital-twins-core`

Instale la biblioteca cliente principal de Digital Twins para JavaScript con npm:

npm install @azure/digital-twins-core

Compatibilidad con navegadores

Agrupación de JavaScript

Para usar esta biblioteca cliente en el explorador, primero debe usar un agrupador. Para más información sobre cómo hacerlo, consulte nuestra documentación de agrupación.

CORS

Azure Digital Twins no admite actualmente el uso compartido de recursos entre orígenes (CORS). Como resultado, esta biblioteca no se puede utilizar para realizar llamadas directas al servicio de plantillas desde un explorador. Consulte este documento para obtener instrucciones.

Conceptos clave

Azure Digital Twins (Gemelos Digitales de Azure)

Azure Digital Twins es un servicio de Azure IoT que crea modelos completos del entorno físico. Puede crear gráficos de inteligencia espacial para modelar las relaciones e interacciones entre personas, espacios y dispositivos. Para obtener más información sobre Azure Digital Twins, consulte Documentación de Azure Digital Twins.

`DigitalTwinsClient`

DigitalTwinsClient es el objeto de cliente que los usuarios de esta biblioteca usan para administrar su instancia de Azure Digital Twins.

Ejemplos

Creación de DigitalTwinsClient

Para crear un nuevo DigitalTwinsClient, necesita el punto de conexión de una instancia de Azure Digital Twins y sus credenciales. Aquí, usamos DefaultAzureCredential para las credenciales del paquete @azure/identity. Admite diferentes mecanismos de autenticación y determina el tipo de credencial adecuado en función del entorno en el que se está ejecutando. Consulte para readme for @azure/identity obtener más información sobre las diferentes opciones de autenticación que puede utilizar.

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

Crear, enumerar, obtener, retirar y eliminar modelos

Crear modelos

Para crear modelos, pasamos una lista de modelos a createModels. Aquí, solo creamos un 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]);

Enumeración de modelos

Usamos listModels para enumerar todos los 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}`);
}

Obtener modelo

Podemos obtener un modelo específico usando getModel con el ID del 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 desmantelamiento

Podemos retirar un modelo usando decomissionModel con el ID de 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>");

Eliminación de un modelo

Podemos eliminar un modelo usando deleteModel con el ID del 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>");

Crear, obtener, consultar y eliminar gemelos digitales

Crear gemelo digital

Para crear un gemelo, deberá proporcionar un identificador para el gemelo digital y una cadena JSON que contenga el objeto gemelo 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);

Obtener el gemelo digital

Podemos obtener un gemelo digital usando getDigitalTwin con el ID de gemelo 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}`);

Consulta de los gemelos digitales

Consulte la instancia de Azure Digital Twins para obtener gemelos digitales mediante el lenguaje de consulta de Azure Digital Twins. Este es un ejemplo de cómo consultar gemelos digitales y cómo iterar sobre los 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}`);
}

Eliminar gemelo digital

Podemos eliminar un gemelo digital usando deleteDigitalTwin con el ID del gemelo 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);

Obtención y actualización de componentes de gemelos digitales

Obtener un componente de gemelo digital

Podemos obtener un componente de gemelo digital usando getComponent el ID del gemelo digital y la ruta del 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}`);

Actualización del componente de gemelo digital

Para actualizar un componente de gemelo digital (es decir, reemplazar, eliminar o agregar una propiedad o subpropiedad de componente dentro de un gemelo digital), debe proporcionar un ID de gemelo digital, una ruta de acceso del componente y una lista de objetos de parche con las propiedades op y path. El valor de op es "reemplazar", "eliminar" o "agregar", y el valor de es la ruta de path acceso al componente del gemelo digital que se está actualizando. Para las operaciones "reemplazar" y "agregar", la propiedad debe incluirse con el value valor deseado de la propiedad del 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,
]);

Crear y enumerar relaciones de gemelos digitales

Crear relaciones de gemelos digitales

upsertRelationship crea una relación en un gemelo digital provisto de un identificador de un gemelo digital, el nombre de la relación (en este caso, "tiene"), el identificador de una relación (en este caso "BuildingHasFloor") y el objeto que representa la relación que se va a crear. El objeto debe contener una propiedad con la clave "$targetId" para especificar el destino de la relación.

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

Enumerar las relaciones de los gemelos digitales

Para un gemelo digital, listRelationships y listIncomingRelationships enumere todas las relaciones y todas las relaciones entrantes, 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}`);
}

Crear, obtener, enumerar y eliminar rutas de eventos

Crear ruta de evento

Para crear una ruta de eventos, proporcione un identificador de una ruta de eventos (en este caso, "myEventRouteId") y datos de ruta de eventos que contengan el punto de conexión y el filtro opcional, como se muestra en el ejemplo que se muestra a continuación. Para obtener más información sobre el filtrado de eventos, consulte esta documentación.

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

Obtener ruta del evento

Podemos obtener una ruta de evento usando getEventRoute con el ID de ruta del 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}`);

Enumerar las rutas de los eventos

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

Eliminar ruta de evento

Podemos eliminar una ruta de evento usando deleteEventRoute con el ID de ruta del 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);

Publicación de mensajes de telemetría para un gemelo digital

Para publicar un mensaje de telemetría para un gemelo digital, debe proporcionar el identificador del gemelo digital, la carga y un identificador único para el mensaje.

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

También puede publicar un mensaje de telemetría para un componente específico de un gemelo digital. Además del ID de gemelo digital, la carga útil y el ID de mensaje único, debe especificar la ruta del 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>",
);

Ejemplos adicionales

Se pueden encontrar ejemplos adicionales en el directorio de muestras.

Solución de problemas

Registro

Habilitar el registro puede ayudar a descubrir información útil sobre errores. Para ver un registro de solicitudes y respuestas HTTP, establezca la AZURE_LOG_LEVEL variable infode entorno en . Como alternativa, el registro se puede habilitar en tiempo de ejecución llamando a setLogLevel en :@azure/logger

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

setLogLevel("info");

Para obtener instrucciones más detalladas sobre cómo habilitar los registros, consulte los documentos del paquete @azure/logger.

Pasos siguientes

Eche un vistazo al directorio de ejemplos para obtener ejemplos detallados que muestran cómo usar las bibliotecas cliente.
Exploración de la documentación de Azure Digital Twins

Contribución

Si desea contribuir a esta biblioteca, lea la guía de contribución de para obtener más información sobre cómo compilar y probar el código.

SDK de Microsoft Azure para Javascript