Partager via

Bibliothèque de client Azure Digital Twins Core pour JavaScript - version 1.1.0

  • Article

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

Prise en main

Environnements actuellement pris en charge

Pour plus d’informations, consultez notre politique de support .

Prérequis

Installez le package @azure/digital-twins-core

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

npm install @azure/digital-twins-core

Prise en charge des navigateurs

Ensemble 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 sur le 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 permet de créer des modèles complets de l’environnement physique. Il peut créer des graphes d’intelligence spatiale afin de 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 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 DigitalTwinsClient, vous avez besoin du point de terminaison d’une instance Azure Digital Twins et des informations d’identification. Ici, nous utilisons DefaultAzureCredential pour les informations d’identification du package @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 pour readme for @azure/identity plus d’informations sur les différentes options d’authentification que vous pouvez utiliser.

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

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

Créer des modèles

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

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 utilisons listModels pour répertorier tous les modèles.

const models = await 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 à l’aide getModel de l’ID de modèle.

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

Désactiver le modèle

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

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

Supprimer le modèle

Nous pouvons supprimer un modèle à l’aide deleteModel de l’ID de modèle.

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 de jumeau numérique.

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 à l’aide getDigitalTwin de l’ID de jumeau numérique.

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

Interroger des jumeaux numériques

Interrogez l’instance Azure Digital Twins pour rechercher des jumeaux numériques à l’aide du langage de requête Azure Digital Twins. Voici un exemple montrant comment interroger des jumeaux numériques et comment itérer sur les résultats.

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

Supprimer un jumeau numérique

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

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

Obtenir et mettre à jour des composants de jumeau numérique

Obtenir le composant de jumeau numérique

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

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 (par exemple, remplacer, supprimer ou ajouter une propriété de composant ou une sous-propriété dans 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 « replace », « remove » ou « add », et la valeur de path est le chemin d’accès au composant de jumeau numérique en cours de mise à jour. Pour les opérations « remplacer » et « ajouter », la value propriété doit être incluse avec la valeur souhaitée de la propriété de composant.

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 fourni avec l’ID d’un jumeau numérique, le nom de la relation (dans ce cas, « a »), l’ID d’une relation (en l’occurrence « BuildingHasFloor ») et l’objet représentant la relation à créer. L’objet doit contenir la propriété avec la clé « $targetId » pour spécifier la cible de la relation.

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 et listIncomingRelationships répertoriez respectivement toutes les relations et toutes les relations entrantes.

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

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énements (dans ce cas, « myEventRouteId ») et les données de route 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.

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

Obtenir l’itinéraire des événements

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

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

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

Nous pouvons répertorier les itinéraires d’événements à l’aide de listEventRoutes.

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

Supprimer l’itinéraire des événements

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

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.

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 de jumeau numérique, de la charge utile et de l’ID de message unique, vous devez spécifier le chemin du composant cible.

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

Autres exemples

Vous trouverez d’autres exemples dans le répertoire samples.

Résolution des problèmes

Journalisation

L’activation de la journalisation peut vous aider à mieux comprendre 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 :

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

  • Consultez le répertoire d’exemples pour obtenir des exemples détaillés qui montrent comment utiliser les bibliothèques clientes.
  • Explorer la documentation Azure Digital Twins

Contribution

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.