Bibliothèque cliente Azure Azure Digital Twins Core pour JavaScript - version 2.0.0

Ce package contient un Kit de développement logiciel (SDK) isomorphe pour l’API Azure Digital Twins afin de fournir un accès au service Azure Digital Twins pour la gestion des jumeaux, des modèles, des relations, etc.

Mise en route

Environnements actuellement pris en charge

• Versions LTS de Node.js
• Dernières versions de Safari, Chrome, Edge et Firefox.

Pour plus d’informations, consultez notre de stratégie de support .

Conditions préalables

• Une instance Azure Digital Twins.

Installer le package @azure/digital-twins-core

Installez la bibliothèque cliente Digital Twins Core pour JavaScript avec npm:

npm install @azure/digital-twins-core

Support des navigateurs

Offre groupée JavaScript

Pour utiliser cette bibliothèque cliente dans le navigateur, vous devez d’abord utiliser un bundler. Pour plus d’informations sur la procédure à suivre, reportez-vous à notre documentation de regroupement .

CORS

Azure Digital Twins ne prend pas actuellement en charge le partage des ressources cross-origin (CORS). Par conséquent, cette bibliothèque ne peut pas être utilisée pour effectuer des appels directs au service de modèle à partir d’un navigateur. Reportez-vous à ce document pour obtenir des conseils.

Concepts clés

Azure Digital Twins

Azure Digital Twins est un service Azure IoT qui crée des modèles complets de l’environnement physique. Il peut créer des graphiques d’intelligence spatiale pour modéliser les relations et les interactions entre les personnes, les espaces et les appareils. Pour en savoir plus sur Azure Digital Twins, consultez la documentation d’Azure Digital Twins.

DigitalTwinsClient

DigitalTwinsClient est l’objet client que les utilisateurs de cette bibliothèque utilisent pour gérer leur instance Azure Digital Twins.

Exemples

Créer le DigitalTwinsClient

Pour créer un , DigitalTwinsClientvous avez besoin du point de terminaison d’une instance Azure Digital Twins et d’informations d’identification. Ici, nous utilisons DefaultAzureCredential pour les informations d’identification du paquet @azure/identity. Il prend en charge différents mécanismes d’authentification et détermine le type d’informations d’identification approprié en fonction de l’environnement dans lequel il s’exécute. Consultez la readme for @azure/identity pour plus d’informations sur les différentes options d’authentification que vous pouvez utiliser.

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

Créer, répertorier, obtenir, désactiver et supprimer des modèles

Créer des modèles

Pour créer des modèles, nous passons une liste de modèles à createModels. Ici, nous ne créons qu’un seul modèle.

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

Lister les modèles

Nous avons l’habitude listModels de lister tous les modèles.

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

Obtenir le modèle

Nous pouvons obtenir un modèle spécifique en utilisant l’ID getModel du modèle.

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

Modèle de démantèlement

Nous pouvons désactiver un modèle à l’aide decomissionModel de l’ID du modèle.

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

Supprimer le modèle

Nous pouvons supprimer un modèle en utilisant l’ID deleteModel du modèle.

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

Créer, obtenir, interroger et supprimer des jumeaux numériques

Créer un jumeau numérique

Pour créer un jumeau, vous devez fournir un ID pour le jumeau numérique et une chaîne JSON contenant l’objet du jumeau numérique.

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

Obtenir le jumeau numérique

Nous pouvons obtenir un jumeau numérique en utilisant getDigitalTwin l’identifiant du jumeau numérique.

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

Interroger des jumeaux numériques

Interrogez l’instance Azure Digital Twins pour les jumeaux numériques à l’aide du langage de requête Azure Digital Twins. Voici un exemple de recherche de jumeaux numériques et d’itération sur les résultats.

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

Supprimer le jumeau numérique

Nous pouvons supprimer un jumeau numérique à l’aide de l’ID deleteDigitalTwin du jumeau numérique.

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

Obtenir et mettre à jour les composants du jumeau numérique

Obtenir le composant de jumeau numérique

Nous pouvons obtenir un composant de jumeau numérique en utilisant getComponent l’ID du jumeau numérique et le chemin d’accès du composant.

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

Mettre à jour le composant de jumeau numérique

Pour mettre à jour un composant de jumeau numérique (c’est-à-dire remplacer, supprimer ou ajouter une propriété ou une sous-propriété de composant au sein d’un jumeau numérique), vous devez fournir un ID de jumeau numérique, un chemin d’accès au composant et une liste d’objets patch avec les propriétés op et path. La valeur de op est « remplacer », « supprimer » ou « ajouter », et la valeur de est le chemin d’accès path au composant de jumeau numérique en cours de mise à jour. Pour les opérations « remplacer » et « ajouter », la propriété doit être incluse avec la value valeur souhaitée de la propriété du composant.

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

Créer et répertorier des relations de jumeau numérique

Créer des relations de jumeau numérique

upsertRelationship crée une relation sur un jumeau numérique muni de l’ID d’un jumeau numérique, du nom de la relation (dans ce cas, « has »), de l’ID d’une relation (dans ce cas, « BuildingHasFloor ») et de l’objet représentant la relation à créer. L’objet doit contenir une propriété avec la clé « $targetId » pour spécifier la cible de la relation.

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

Répertorier les relations de jumeau numérique

Pour un jumeau numérique, listRelationships répertoriez listIncomingRelationships respectivement toutes les relations et toutes les relations entrantes.

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

Créer, obtenir, répertorier et supprimer des itinéraires d’événements

Créer un itinéraire d’événement

Pour créer un itinéraire d’événement, fournissez l’ID d’un itinéraire d’événement (dans ce cas, « myEventRouteId ») et des données d’itinéraire d’événement contenant le point de terminaison et le filtre facultatif, comme dans l’exemple ci-dessous. Pour plus d’informations sur le filtrage des événements, consultez cette documentation.

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

Obtenir l’itinéraire de l’événement

Nous pouvons obtenir un itinéraire d’événement en utilisant getEventRoute l’ID de l’itinéraire d’événement.

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

Répertorier les itinéraires d’événements

Nous pouvons lister les itinéraires d’événements à l’aide de 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}`);
}

Supprimer l’itinéraire de l’événement

Nous pouvons supprimer un itinéraire d’événement à l’aide deleteEventRoute de l’ID de l’itinéraire d’événement.

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

Publier des messages de télémétrie pour un jumeau numérique

Pour publier un message de télémétrie pour un jumeau numérique, vous devez fournir l’ID du jumeau numérique, la charge utile et un ID unique pour le message.

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

Vous pouvez également publier un message de télémétrie pour un composant spécifique dans un jumeau numérique. En plus de l’ID du jumeau numérique, de la charge utile et de l’ID de message unique, vous devez spécifier le chemin d’accès au composant cible.

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

Exemples supplémentaires

Des exemples supplémentaires peuvent être trouvés dans le répertoire samples.

Résolution des problèmes

Exploitation forestière

L’activation de la journalisation peut vous aider à découvrir des informations utiles sur les échecs. Pour avoir un journal des requêtes et réponses HTTP, définissez la variable d’environnement AZURE_LOG_LEVEL sur info. Vous pouvez également activer la journalisation au moment de l’exécution en appelant setLogLevel dans @azure/logger :

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

setLogLevel("info");

Pour obtenir des instructions plus détaillées sur l’activation des journaux, consultez les documents relatifs au package @azure/logger.

Étapes suivantes

• Jetez un coup d’œil au répertoire samples pour obtenir des exemples détaillés qui montrent comment utiliser les bibliothèques clientes.
• Explorer la documentation d’Azure Digital Twins

Contribuer

Si vous souhaitez contribuer à cette bibliothèque, lisez le guide de contribution pour en savoir plus sur la génération et le test du code.

Projets connexes

• Kit de développement logiciel (SDK) Microsoft Azure pour Javascript