Compartir a través de

Biblioteca cliente de Azure Digital Twins Core para JavaScript: versión 1.1.0

  • Artículo

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

Introducción

Entornos admitidos actualmente

Para más información, consulte la directiva de compatibilidad.

Prerrequisitos

Instalar el paquete @azure/digital-twins-core

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

npm install @azure/digital-twins-core

Compatibilidad con exploradores

Paquete 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 usar para realizar llamadas directas al servicio de plantilla desde un explorador. Consulte este documento para obtener instrucciones.

Conceptos clave

Azure Digital Twins

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

DigitalTwinsClient

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

Ejemplos

Creación de DigitalTwinsClient

Para crear un nuevo DigitalTwinsClient, necesita el punto de conexión a una instancia y credenciales de Azure Digital Twins. Aquí, usamos DefaultAzureCredential para las credenciales del paquete @azure/identity. Admite diferentes mecanismos de autenticación y determina el tipo de credencial adecuado basado en el entorno en el que se ejecuta. Consulte para readme for @azure/identity obtener más información sobre las diferentes opciones de autenticación que puede 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);

Crear, enumerar, obtener, retirar y eliminar modelos

Crear modelos

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

Enumeración de modelos

listModels Usamos para enumerar todos los modelos.

const models = await serviceClient.listModels();
for await (const model of models) {
  console.log(`Model ID: ${model.id}`);
}

Obtener modelo

Podemos obtener un modelo específico mediante getModel con el identificador del modelo.

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

Modelo de retirada

Podemos retirar un modelo mediante decomissionModel con el identificador del modelo.

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

Eliminación de un modelo

Podemos eliminar un modelo mediante deleteModel con el identificador de modelo.

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

Creación, obtención, consulta y eliminación de gemelos digitales

Creación de gemelos digitales

Para crear un gemelo, deberá proporcionar un identificador para el gemelo digital y una cadena JSON que contenga el objeto de gemelo digital.

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

Obtención del gemelo digital

Podemos obtener un gemelo digital mediante getDigitalTwin con el identificador del gemelo digital.

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

Consulta de los gemelos digitales

Consulte la instancia de Azure Digital Twins para 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 los resultados.

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

Eliminación de gemelos digitales

Podemos eliminar un gemelo digital mediante deleteDigitalTwin con el identificador de gemelo digital.

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

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

Obtención del componente de gemelo digital

Podemos obtener un componente de gemelo digital mediante getComponent con el identificador de gemelo digital y la ruta de acceso del componente.

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, quitar o agregar una propiedad de componente o una subpropiedad dentro de un gemelo digital), debe proporcionar un identificador de gemelo digital, una ruta de acceso de componente y una lista de objetos de revisión con las propiedades op y path. El valor de op es "replace", "remove" o "add", y el valor de es la ruta de path acceso al componente de gemelo digital que se está actualizando. Para las operaciones "replace" y "add", la value propiedad debe incluirse con el valor deseado de la propiedad component.

const digitalTwinId = "myTwin";
const componentPath = "Component1";
const patch = {
  op: "replace",
  path: "/ComponentProp1",
  value: "value2"
};
const updateComponentResponse = await serviceClient.updateComponent(digitalTwinId, componentPath, [
  patch
]);

Creación y enumeración de relaciones de gemelos digitales

Creación de relaciones de gemelos digitales

upsertRelationship crea una relación en un gemelo digital proporcionado con el 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 la propiedad con la clave "$targetId" para especificar el destino de la relación.

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

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

Enumeración de relaciones de gemelos digitales

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

Crear, obtener, enumerar y eliminar rutas de eventos

Creación de una ruta de eventos

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

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

Obtención de la ruta de eventos

Podemos obtener una ruta de evento mediante getEventRoute con el identificador de ruta de evento.

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

Enumerar rutas de eventos

Podemos enumerar las rutas de eventos mediante listEventRoutes.

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

Eliminar ruta de eventos

Podemos eliminar una ruta de eventos mediante deleteEventRoute con el identificador de ruta de evento.

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 de gemelo digital, la carga y un identificador único para el mensaje.

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 en un gemelo digital. Además del identificador de gemelo digital, la carga y el identificador de mensaje único, debe especificar la ruta de acceso del 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>"
);

Otros ejemplos

Puede encontrar ejemplos adicionales en el directorio samples.

Solución de problemas

Registro

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

const { setlogLevel } = require("@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

Contribuciones

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