Biblioteka klienta azure Digital Twins Core dla języka JavaScript — wersja 1.1.0

Artykuł
04/05/2023

Ten pakiet zawiera izomorficzny zestaw SDK dla interfejsu API usługi Azure Digital Twins w celu zapewnienia dostępu do usługi Azure Digital Twins do zarządzania bliźniaczymi reprezentacjami, modelami, relacjami itp.

Wprowadzenie

Obecnie obsługiwane środowiska

Wersje LTS Node.js
Najnowsze wersje przeglądarek Safari, Chrome, Edge i Firefox.

Aby uzyskać więcej informacji, zobacz nasze zasady pomocy technicznej .

Wymagania wstępne

Wystąpienie usługi Azure Digital Twins.

Instalowanie pakietu `@azure/digital-twins-core`

Zainstaluj bibliotekę klienta usługi Digital Twins Core dla języka JavaScript przy użyciu polecenia npm:

npm install @azure/digital-twins-core

Obsługa przeglądarki

Pakiet JavaScript

Aby użyć tej biblioteki klienta w przeglądarce, najpierw należy użyć narzędzia bundler. Aby uzyskać szczegółowe informacje o tym, jak to zrobić, zapoznaj się z naszą dokumentacją dotyczącą tworzenia pakietów.

CORS

Usługa Azure Digital Twins nie obsługuje obecnie współużytkowania zasobów między źródłami (CORS). W związku z tym tej biblioteki nie można używać do wykonywania wywołań bezpośrednich do usługi szablonu z przeglądarki. Aby uzyskać wskazówki, zapoznaj się z tym dokumentem .

Kluczowe pojęcia

Azure Digital Twins

Azure Digital Twins to usługa IoT platformy Azure, która umożliwia tworzenie kompleksowych modeli środowiska fizycznego. Umożliwia ona tworzenie grafów analizy przestrzennej do modelowania relacji i interakcji między osobami, obszarami i urządzeniami. Aby dowiedzieć się więcej na temat usługi Azure Digital Twins, zapoznaj się z dokumentacją usługi Azure Digital Twins.

`DigitalTwinsClient`

DigitalTwinsClient to obiekt klienta, którego użytkownicy tej biblioteki używają do zarządzania wystąpieniem usługi Azure Digital Twins.

Przykłady

Tworzenie elementu DigitalTwinsClient

Aby utworzyć nowy DigitalTwinsClientelement , potrzebujesz punktu końcowego do wystąpienia usługi Azure Digital Twins i poświadczeń. W tym miejscu używamy DefaultAzureCredential dla poświadczeń z pakietu @azure/identity. Obsługuje różne mechanizmy uwierzytelniania i określa odpowiedni typ poświadczeń w oparciu o środowisko, w których jest wykonywany. Więcej informacji na temat różnych opcji uwierzytelniania, których można użyć, można znaleźć w temacie readme for @azure/identity .

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

Tworzenie, wyświetlanie listy, pobieranie, likwidowanie i usuwanie modeli

Tworzenie modeli

Aby utworzyć modele, przekazujemy listę modeli do .createModels W tym miejscu utworzymy tylko jeden model.

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

Wyświetlanie listy modeli

Służymy listModels do wyświetlania listy wszystkich modeli.

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

Pobieranie modelu

Możemy uzyskać określony model przy użyciu identyfikatora getModel modelu.

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

Likwiduj model

Możemy zlikwidować model przy użyciu identyfikatora decomissionModel modelu.

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

Usuwanie modelu

Możemy usunąć model przy użyciu identyfikatora deleteModel modelu.

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

Tworzenie, pobieranie, wykonywanie zapytań i usuwanie cyfrowych reprezentacji bliźniaczych

Tworzenie cyfrowej reprezentacji bliźniaczej

Aby utworzyć reprezentację bliźniaczą, musisz podać identyfikator cyfrowej reprezentacji bliźniaczej i ciąg JSON zawierający obiekt cyfrowej reprezentacji bliźniaczej.

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

Uzyskiwanie cyfrowej reprezentacji bliźniaczej

Możemy uzyskać cyfrową reprezentację bliźniaczą przy użyciu getDigitalTwin identyfikatora cyfrowej reprezentacji bliźniaczej.

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

Wykonywanie zapytań dotyczących cyfrowych reprezentacji bliźniaczych

Wykonaj zapytanie dotyczące wystąpienia usługi Azure Digital Twins dla cyfrowych reprezentacji bliźniaczych przy użyciu języka zapytań usługi Azure Digital Twins. Oto przykład wykonywania zapytań dotyczących cyfrowych reprezentacji bliźniaczych i iteracji wyników.

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

Usuwanie cyfrowej reprezentacji bliźniaczej

Możemy usunąć cyfrową reprezentację bliźniaczą przy użyciu deleteDigitalTwin identyfikatora cyfrowej reprezentacji bliźniaczej.

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

Pobieranie i aktualizowanie składników cyfrowej reprezentacji bliźniaczej

Pobieranie składnika cyfrowej reprezentacji bliźniaczej

Możemy uzyskać składnik cyfrowej reprezentacji bliźniaczej przy użyciu getComponent identyfikatora cyfrowej reprezentacji bliźniaczej i ścieżki składnika.

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

Aktualizowanie składnika cyfrowej reprezentacji bliźniaczej

Aby zaktualizować składnik cyfrowej reprezentacji bliźniaczej (tj. zastąpić, usunąć lub dodać właściwość składnika lub właściwość podrzędną w cyfrowej reprezentacji bliźniaczej), musisz podać identyfikator cyfrowej reprezentacji bliźniaczej, ścieżkę składnika i listę obiektów poprawek z właściwościami op i path. Wartość op to "replace", "remove" lub "add", a wartość path to ścieżka do aktualizowanego składnika cyfrowej reprezentacji bliźniaczej. W przypadku operacji value "replace" i "add" właściwość powinna zostać dołączona do żądanej wartości właściwości składnika.

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

Tworzenie i wyświetlanie listy relacji cyfrowej reprezentacji bliźniaczej

Tworzenie relacji cyfrowej reprezentacji bliźniaczej

upsertRelationship Tworzy relację na cyfrowej reprezentacji bliźniaczej dostarczonej z identyfikatorem cyfrowej reprezentacji bliźniaczej, nazwą relacji (w tym przypadku "has"), identyfikatorem relacji (w tym przypadku "BuildingHasFloor") i obiektem reprezentującym relację do utworzenia. Obiekt musi zawierać właściwość z kluczem "$targetId", aby określić cel relacji.

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

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

Wyświetlanie listy relacji cyfrowej reprezentacji bliźniaczej

W przypadku cyfrowej reprezentacji bliźniaczej listRelationships należy listIncomingRelationships wyświetlić listę wszystkich relacji i wszystkich relacji przychodzących.

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

Tworzenie, pobieranie, wyświetlanie i usuwanie tras zdarzeń

Tworzenie trasy zdarzeń

Aby utworzyć trasę zdarzeń, podaj identyfikator trasy zdarzeń (w tym przypadku "myEventRouteId") i dane trasy zdarzeń zawierające punkt końcowy i opcjonalny filtr, jak pokazano poniżej. Aby uzyskać więcej informacji na temat filtrowania zdarzeń, zobacz tę dokumentację.

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

Pobieranie trasy zdarzeń

Możemy uzyskać trasę zdarzeń przy użyciu getEventRoute identyfikatora trasy zdarzenia.

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

Wyświetlanie listy tras zdarzeń

Możemy wyświetlić listę tras zdarzeń przy użyciu polecenia listEventRoutes.

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

Usuwanie trasy zdarzeń

Możemy usunąć trasę zdarzeń przy użyciu deleteEventRoute identyfikatora trasy zdarzenia.

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

Publikowanie komunikatów telemetrycznych dla cyfrowej reprezentacji bliźniaczej

Aby opublikować komunikat telemetryczny dla cyfrowej reprezentacji bliźniaczej, musisz podać identyfikator cyfrowej reprezentacji bliźniaczej, ładunek i unikatowy identyfikator komunikatu.

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

Możesz również opublikować komunikat telemetryczny dla określonego składnika w cyfrowej reprezentacji bliźniaczej. Oprócz identyfikatora cyfrowej reprezentacji bliźniaczej, ładunku i unikatowego identyfikatora komunikatu należy określić docelową ścieżkę składnika.

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

Dodatkowe przykłady

Dodatkowe przykłady można znaleźć w katalogu samples.

Rozwiązywanie problemów

Rejestrowanie

Włączenie rejestrowania może pomóc odkryć przydatne informacje o błędach. Aby wyświetlić dziennik żądań i odpowiedzi HTTP, ustaw zmienną AZURE_LOG_LEVEL środowiskową na info. Alternatywnie rejestrowanie można włączyć w czasie wykonywania, wywołując setLogLevel polecenie w pliku @azure/logger:

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

setLogLevel("info");

Aby uzyskać bardziej szczegółowe instrukcje dotyczące włączania dzienników, zapoznaj się z dokumentami dotyczącymi pakietów @azure/rejestratora.

Następne kroki

Zapoznaj się z katalogiem samples , aby zapoznać się ze szczegółowymi przykładami, które pokazują, jak używać bibliotek klienckich.
Zapoznaj się z dokumentacją usługi Azure Digital Twins

Współtworzenie

Jeśli chcesz współtworzyć tę bibliotekę, przeczytaj przewodnik współtworzenia , aby dowiedzieć się więcej na temat tworzenia i testowania kodu.

Zestaw Microsoft Azure SDK dla języka JavaScript

Udostępnij za pośrednictwem