Freigeben über

Azure Digital Twins Core-Clientbibliothek für JavaScript– Version 1.1.0

  • Artikel

Dieses Paket enthält ein isomorphes SDK für die Azure Digital Twins-API, um Zugriff auf den Azure Digital Twins-Dienst zum Verwalten von Zwillingen, Modellen, Beziehungen usw. bereitzustellen.

Erste Schritte

Die derzeitig unterstützten Umgebungen

Ausführlichere Informationen finden Sie in der Supportrichtlinie.

Voraussetzungen

Installieren Sie das Paket @azure/digital-twins-core.

Installieren Sie die Digital Twins Core-Clientbibliothek für JavaScript mit npm:

npm install @azure/digital-twins-core

Browserunterstützung

JavaScript-Paket

Um diese Clientbibliothek im Browser verwenden zu können, müssen Sie zunächst einen Bundler verwenden. Ausführliche Informationen dazu finden Sie in unserer Bündelungsdokumentation.

CORS

CORS (Cross-Origin Resource Sharing) wird in Azure Digital Twins derzeit nicht unterstützt. Daher kann diese Bibliothek nicht für direkte Aufrufe des Vorlagendiensts aus einem Browser verwendet werden. Weitere Informationen finden Sie in diesem Dokument .

Wichtige Begriffe

Azure Digital Twins

Azure Digital Twins ist ein Azure IoT-Dienst zur Erstellung umfassender Modelle der physischen Umgebung. Er kann Raumintelligenzgraphen erstellen, um die Beziehungen und Interaktionen zwischen Personen, Bereichen und Geräten zu modellieren. Weitere Informationen zu Azure Digital Twins finden Sie in der Dokumentation zu Azure Digital Twins.

DigitalTwinsClient

DigitalTwinsClient ist das Clientobjekt, das Benutzer dieser Bibliothek zum Verwalten ihrer Azure Digital Twins-Instanz verwenden.

Beispiele

Erstellen des DigitalTwinsClient

Um eine neue DigitalTwinsClientzu erstellen, benötigen Sie den Endpunkt für eine Azure Digital Twins-Instanz und Anmeldeinformationen. Hier verwenden DefaultAzureCredential wir für Anmeldeinformationen aus dem Paket @azure/identity. Es unterstützt verschiedene Authentifizierungsmechanismen und bestimmt den geeigneten Anmeldeinformationstyp basierend auf der Umgebung, in der er ausgeführt wird. readme for @azure/identity Weitere Informationen zu den verschiedenen Authentifizierungsoptionen, die Sie verwenden können, finden Sie unter .

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

Erstellen, Auflisten, Abrufen, Außerbetriebnahme und Löschen von Modellen

Erstellen von Modellen

Um Modelle zu erstellen, übergeben wir eine Liste von Modellen an createModels. Hier erstellen wir nur ein Modell.

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

Auflisten von Modellen

Wir verwenden listModels zum Auflisten aller Modelle.

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

Modell abrufen

Wir können ein bestimmtes Modell mit getModel der Modell-ID abrufen.

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

Außerbetriebnahmemodell

Wir können ein Modell mit decomissionModel mit der Modell-ID außer Betrieb setzen.

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

Löschen des Modells

Wir können ein Modell mit mit deleteModel der Modell-ID löschen.

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

Erstellen, Abrufen, Abfragen und Löschen von digitalen Zwillingen

Erstellen eines digitalen Zwillings

Um einen Zwilling zu erstellen, müssen Sie eine ID für den digitalen Zwilling und eine JSON-Zeichenfolge angeben, die das Objekt des digitalen Zwillings enthält.

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

Abrufen des digitalen Zwillings

Wir können einen digitalen Zwilling mit getDigitalTwin der ID des digitalen Zwillings erhalten.

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

Abfragen von digitalen Zwillingen

Fragen Sie die Azure Digital Twins-Instanz mithilfe der Azure Digital Twins-Abfragesprache nach digitalen Zwillingen ab. Hier sehen Sie ein Beispiel dafür, wie Sie digitale Zwillinge abfragen und die Ergebnisse durchlaufen.

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

Löschen des digitalen Zwillings

Wir können einen digitalen Zwilling mit deleteDigitalTwin mit der ID des digitalen Zwillings löschen.

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

Abrufen und Aktualisieren von Komponenten für digitale Zwillinge

Abrufen einer Komponente für digitale Zwillinge

Wir können eine Komponente des digitalen Zwillings mit getComponent der ID des digitalen Zwillings und dem Pfad der Komponente abrufen.

const digitalTwinId = "myTwin";
const componentPath = "Component1";
const component = await serviceClient.getComponent(digitalTwinId, componentPath);
console.log(`Component: ${component}`);

Aktualisieren der Komponente für digitale Zwillinge

Zum Aktualisieren einer Komponente für digitale Zwillinge (d. h. ersetzen, entfernen oder hinzufügen einer Komponenteneigenschaft oder -untereigenschaft innerhalb eines digitalen Zwillings) müssen Sie eine ID des digitalen Zwillings, einen Komponentenpfad und eine Liste von Patchobjekten mit den Eigenschaften op und pathangeben. Der Wert von op ist "replace", "remove" oder "add", und der Wert von path ist der Pfad zur Komponente des digitalen Zwillings, die aktualisiert wird. Bei "Replace"- und "add"-Vorgängen sollte die value -Eigenschaft in den gewünschten Wert der Komponenteneigenschaft eingeschlossen werden.

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

Erstellen und Auflisten von Beziehungen zu digitalen Zwillingen

Erstellen von Beziehungen zu digitalen Zwillingen

upsertRelationship erstellt eine Beziehung zu einem digitalen Zwilling, der mit der ID eines digitalen Zwillings, dem Namen der Beziehung (in diesem Fall "has"), der ID einer Beziehung (in diesem Fall "BuildingHasFloor") und dem Objekt bereitgestellt wird, das die zu erstellende Beziehung darstellt. Das -Objekt muss die -Eigenschaft mit dem Schlüssel "$targetId" enthalten, um das Ziel der Beziehung anzugeben.

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

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

Auflisten von Beziehungen mit digitalen Zwillingen

Für einen digitalen Zwilling listRelationships und listIncomingRelationships listen Sie alle Beziehungen bzw. alle eingehenden Beziehungen auf.

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

Erstellen, Abrufen, Auflisten und Löschen von Ereignisrouten

Erstellen einer Ereignisroute

Um eine Ereignisroute zu erstellen, geben Sie eine ID einer Ereignisroute (in diesem Fall "myEventRouteId") und Ereignisroutendaten an, die den Endpunkt und optionalen Filter enthalten, wie im folgenden Beispiel gezeigt. Weitere Informationen zum Filtern von Ereignissen finden Sie in dieser Dokumentation.

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

Ereignisroute abrufen

Wir können eine Ereignisroute mit der getEventRoute Ereignisrouten-ID abrufen.

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

Auflisten von Ereignisrouten

Wir können Ereignisrouten mit listEventRoutesauflisten.

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

Ereignisroute löschen

Wir können eine Ereignisroute mit mit deleteEventRoute der Ereignisrouten-ID löschen.

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

Veröffentlichen von Telemetriemeldungen für einen digitalen Zwilling

Um eine Telemetrienachricht für einen digitalen Zwilling zu veröffentlichen, müssen Sie die ID des digitalen Zwillings, die Nutzlast und eine eindeutige ID für die Nachricht angeben.

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

Sie können auch eine Telemetrienachricht für eine bestimmte Komponente in einem digitalen Zwilling veröffentlichen. Zusätzlich zur ID des digitalen Zwillings, der Nutzlast und der eindeutigen Nachrichten-ID müssen Sie den Pfad der Zielkomponente angeben.

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

Zusätzliche Beispiele

Weitere Beispiele finden Sie im Beispielverzeichnis.

Problembehandlung

Protokollierung

Die Aktivierung der Protokollierung kann hilfreiche Informationen über Fehler aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die Umgebungsvariable AZURE_LOG_LEVEL auf info fest. Alternativ kann die Protokollierung zur Laufzeit aktiviert werden, indem Sie setLogLevel in @azure/logger aufrufen:

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

setLogLevel("info");

Ausführlichere Anweisungen zum Aktivieren von Protokollen finden Sie in der Paketdokumentation zu @azure/logger.

Nächste Schritte

  • Sehen Sie sich das Beispielverzeichnis an, um detaillierte Beispiele zu finden, die die Verwendung der Clientbibliotheken veranschaulichen.
  • Erkunden der Dokumentation zu Azure Digital Twins

Mitwirken

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie die Anleitung für Mitwirkende, um mehr darüber zu erfahren, wie Sie den Code erstellen und testen können.