Azure Azure Azure Digitální Twins Základní klientská knihovna pro JavaScript – verze 2.0.0

Tento balíček obsahuje izomorfní sadu SDK pro rozhraní API Azure Digital Twins, která poskytuje přístup ke službě Azure Digital Twins pro správu dvojčat, modelů, vztahů atd.

Začínáme

Aktuálně podporovaná prostředí

• LTS verze Node.js
• Nejnovější verze Safari, Chrome, Edge a Firefox.

Další podrobnosti najdete v zásadách podpory.

Požadavky

• Instance služby Azure Digital Twins.

Nainstalujte balíček @azure/digital-twins-core.

Nainstalujte klientskou knihovnu Digital Twins Core pro JavaScript pomocí npm:

npm install @azure/digital-twins-core

Podpora prohlížečů

JavaScriptový balíček

Pokud chcete tuto klientskou knihovnu použít v prohlížeči, musíte nejprve použít bundler. Podrobnosti o tom, jak to udělat, najdete v naší dokumentaci k sdružování.

Sdílení zdrojů mezi doménami (CORS)

Azure Digital Twins v současné době nepodporuje sdílení prostředků mezi zdroji (CORS). V důsledku toho nelze tuto knihovnu použít k přímému volání služby šablon z prohlížeče. Pokyny najdete v tomto dokumentu.

Klíčové koncepty

Azure Digital Twins (digitální dvojčata Azure)

Azure Digital Twins je služba Azure IoT, která vytváří komplexní modely fyzického prostředí. Může vytvářet grafy prostorové inteligence, které modelují vztahy a interakce mezi lidmi, prostory a zařízeními. Další informace o službě Azure Digital Twins najdete v dokumentaci ke službě Azure Digital Twins.

DigitalTwinsClient

DigitalTwinsClient je objekt klienta, který uživatelé této knihovny používají ke správě své instance Azure Digital Twins.

Příklady

Vytvoření klienta DigitalTwins

Chcete-li vytvořit nový DigitalTwinsClient, potřebujete koncový bod k instanci Azure Digital Twins a přihlašovací údaje. Zde používáme DefaultAzureCredential pro přihlašovací údaje z balíčku @azure/identity. Podporuje různé mechanismy ověřování a určuje vhodný typ přihlašovacích údajů na základě prostředí, ve kterém se spouští. Další informace o různých možnostech ověřování, které můžete použít, najdete v části readme for @azure/identity .

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

Vytváření, vypsávání, získávání, vyřazování a odstraňování modelů

Vytváření modelů

Abychom mohli vytvářet modely, předáváme seznam modelů do createModels. Zde vytvoříme pouze jeden model.

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

Výpis modelů

Používáme listModels k výpisu všechny modely.

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

Získat model

Můžeme získat konkrétní model pomocí getModel ID modelu.

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

Model vyřazení z provozu

Model můžeme vyřadit z provozu pomocí decomissionModel ID modelu.

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

Odstranění modelu

Model můžeme smazat pomocí deleteModel s ID modelu.

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

Vytváření, získávání, dotazování a odstraňování digitálních dvojčat

Vytvořte digitální dvojče

Chcete-li vytvořit dvojče, budete muset zadat ID digitálního dvojčete a řetězec JSON obsahující objekt digitálního dvojčete.

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

Získejte digitální dvojče

Digitální dvojče můžeme získat pomocí getDigitalTwin ID digitálního dvojčete.

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

Dotazování na digitální dvojčata

Zadejte dotaz na instanci Azure Digital Twins pro digitální dvojčata pomocí dotazovacího jazyka Azure Digital Twins. Zde je příklad, jak dotazovat na digitální dvojčata a jak iterovat výsledky.

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

Odstranění digitálního dvojčete

Digitální dvojče můžeme odstranit pomocí deleteDigitalTwin ID digitálního dvojčete.

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

Získání a aktualizace komponent digitálního dvojčete

Získejte komponentu digitálního dvojčete

Komponentu digitálního dvojčete můžeme získat pomocí getComponent ID digitálního dvojčete a cesty komponenty.

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

Aktualizace součásti digitálního dvojčete

Chcete-li aktualizovat komponentu digitálního dvojčete (tj. nahradit, odebrat nebo přidat vlastnost nebo podvlastnost komponenty v rámci digitálního dvojčete), musíte zadat ID digitálního dvojčete, cestu komponenty a seznam objektů záplaty s vlastnostmi op a path. Hodnota op je "nahradit", "odebrat" nebo "přidat" a hodnota je path cesta k aktualizované komponentě digitálního dvojčete. U operací value "nahradit" a "přidat" by měla být vlastnost zahrnuta do požadované hodnoty vlastnosti komponenty.

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

Vytvoření a výpis vztahů digitálních dvojčat

Vytváření vztahů digitálních dvojčat

upsertRelationship vytvoří relaci na digitálním dvojčeti poskytnutém ID digitálního dvojčete, názvem relace (v tomto případě "has"), ID relace (v tomto případě "BuildingHasFloor") a objektem představujícím relaci, která má být vytvořena. Objekt musí obsahovat vlastnost s klíčem "$targetId" pro určení cíle vztahu.

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

Výpis vztahů digitálních dvojčat

V případě digitálního dvojčete listRelationships uveďte listIncomingRelationships všechny vztahy a všechny příchozí vztahy.

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

Vytváření, získávání, vypsání a odstraňování tras událostí

Vytvoření trasy události

Chcete-li vytvořit trasu události, zadejte ID trasy události (v tomto případě "myEventRouteId") a data trasy události obsahující koncový bod a volitelný filtr, jako je příklad uvedený níže. Další informace o filtrování událostí naleznete v této dokumentaci.

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

Získat trasu akce

Trasu události můžeme získat pomocí getEventRoute ID trasy události.

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

Seznam tras událostí

Trasy událostí můžeme vypsat pomocí 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}`);
}

Smazat trasu události

Trasu události můžeme odstranit pomocí deleteEventRoute ID trasy události.

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

Publikování telemetrických zpráv pro digitální dvojče

Chcete-li publikovat telemetrickou zprávu pro digitální dvojče, musíte zadat ID digitálního dvojčete, datovou část a jedinečné ID zprávy.

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

Můžete také publikovat zprávu telemetrie pro konkrétní komponentu v digitálním dvojčeti. Kromě ID digitálního dvojčete, datové části a jedinečného ID zprávy je třeba zadat cestu cílové komponenty.

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

Další příklady

Další příklady lze nalézt v adresáři samples.

Řešení problémů

Logování

Povolení protokolování může pomoct odhalit užitečné informace o chybách. Pokud chcete zobrazit protokol požadavků HTTP a odpovědí, nastavte proměnnou AZURE_LOG_LEVEL prostředí na infohodnotu . Případně můžete protokolování povolit za běhu voláním setLogLevel příkazu @azure/logger:

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

setLogLevel("info");

Podrobnější pokyny k povolení protokolů najdete v dokumentaci k @azure/protokolovacímu balíčku.

Další kroky

• Podívejte se do adresáře samples, kde najdete podrobné příklady, které ukazují, jak používat klientské knihovny.
• Prozkoumejte dokumentaci ke službě Azure Digital Twins

Přispění

Pokud chcete přispívat do této knihovny, přečtěte si průvodce pro přispívání a přečtěte si další informace o tom, jak sestavit a otestovat kód.

Související projekty

• Microsoft Azure SDK pro JavaScript