Libreria client di Azure Digital Twins Core per JavaScript - versione 2.0.0

Questo pacchetto contiene un SDK isomorfico per l'API Gemelli digitali di Azure per fornire l'accesso al servizio Gemelli digitali di Azure per la gestione di gemelli, modelli, relazioni e così via.

Come iniziare

Ambienti attualmente supportati

• Versioni LTS di Node.js
• Versioni più recenti di Safari, Chrome, Edge e Firefox.

Per altri dettagli, vedere i criteri di supporto .

Prerequisiti

• Un'istanza di Gemelli digitali di Azure.

Installare il pacchetto @azure/digital-twins-core

Installare la libreria client di base di Gemelli digitali per JavaScript con npm:

npm install @azure/digital-twins-core

Supporto del browser

Pacchetto JavaScript

Per usare questa libreria client nel browser, è prima necessario usare un bundler. Per informazioni dettagliate su come eseguire questa operazione, vedere la documentazione di creazione di bundle .

Condivisione delle Risorse tra Origini Diverse (CORS)

Gemelli digitali di Azure attualmente non supporta la Condivisione risorse tra le origini (CORS). Di conseguenza, questa libreria non può essere utilizzata per effettuare chiamate dirette al servizio modello da un browser. Per indicazioni, vedere questo documento.

Concetti chiave

Gemelli digitali di Azure

Gemelli digitali di Azure è un servizio Azure IoT che crea modelli completi dell'ambiente fisico. Può creare grafici di intelligenza spaziale per modellare le relazioni e le interazioni tra persone, spazi e dispositivi. Per altre informazioni su Gemelli digitali di Azure, vedere la documentazione di Gemelli digitali di Azure.

DigitalTwinsClient

DigitalTwinsClient è l'oggetto client usato dagli utenti di questa libreria per gestire l'istanza di Gemelli digitali di Azure.

Esempi

Creare il DigitalTwinsClient

Per creare un nuovo DigitalTwinsClient, è necessario l'endpoint per un'istanza di Gemelli digitali di Azure e le credenziali. Qui, usiamo DefaultAzureCredential per le credenziali dal pacchetto @azure/identity. Supporta diversi meccanismi di autenticazione e determina il tipo di credenziali appropriato in base all'ambiente in cui viene eseguito. readme for @azure/identity Per ulteriori informazioni sulle diverse opzioni di autenticazione che è possibile utilizzare, vedere .

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

Creazione, elenco, acquisizione, rimozione delle autorizzazioni e eliminazione di modelli

Creare modelli

Per creare i modelli, passiamo un elenco di modelli a createModels. In questo caso, creiamo un solo modello.

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

Ottenere l'elenco dei modelli

listModels Elenchiamo tutti i modelli.

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

Ottieni il modello

Possiamo ottenere un modello specifico utilizzando getModel l'ID modello.

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

Modello di disattivazione

Possiamo dismettere un modello utilizzando decomissionModel l'ID modello.

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

Eliminare un modello

Possiamo eliminare un modello utilizzando deleteModel l'ID modello.

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

Creare, ottenere, eseguire query ed eliminare gemelli digitali

Crea gemello digitale

Per creare un gemello, è necessario fornire un ID per il gemello digitale e una stringa JSON contenente l'oggetto gemello digitale.

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

Ottieni il gemello digitale

Possiamo ottenere un gemello digitale utilizzando getDigitalTwin l'ID del gemello digitale.

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

Eseguire query sui gemelli digitali

Eseguire una query sull'istanza di Gemelli digitali di Azure per i gemelli digitali usando il linguaggio di query di Gemelli digitali di Azure. Di seguito è riportato un esempio di come eseguire query per i gemelli digitali e di come eseguire l'iterazione dei risultati.

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

Eliminare il gemello digitale

Possiamo eliminare un gemello digitale utilizzando deleteDigitalTwin l'ID del gemello digitale.

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

Ottenere e aggiornare i componenti del digital twin

Ottieni il componente del gemello digitale

Possiamo ottenere un componente di gemello digitale utilizzando getComponent l'ID del gemello digitale e il percorso del componente.

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

Aggiornare il componente del gemello digitale

Per aggiornare un componente del gemello digitale (ad esempio, sostituire, rimuovere o aggiungere una proprietà o una sottoproprietà del componente all'interno di un gemello digitale), è necessario fornire un ID del gemello digitale, il percorso del componente e un elenco di oggetti patch con le proprietà op e path. Il valore di op è "replace", "remove" o "add" e il valore di è il percorso del path componente del gemello digitale da aggiornare. Per le operazioni di "sostituzione" e "aggiunta", la proprietà deve essere inclusa con il value valore desiderato della proprietà del componente.

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

Creare ed elencare le relazioni dei gemelli digitali

Crea relazioni di digital twin

upsertRelationship crea una relazione su un gemello digitale fornito con l'ID di un gemello digitale, il nome della relazione (in questo caso, "ha"), l'ID di una relazione (in questo caso "BuildingHasFloor") e l'oggetto che rappresenta la relazione da creare. L'oggetto deve contenere la proprietà con la chiave "$targetId" per specificare la destinazione della relazione.

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

Elencare le relazioni dei gemelli digitali

Per un gemello digitale, listRelationships elencare listIncomingRelationships rispettivamente tutte le relazioni e tutte le relazioni in entrata.

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

Creare, ottenere, elencare ed eliminare i percorsi degli eventi

Crea percorso evento

Per creare una route di eventi, fornire un ID di una route di eventi (in questo caso, "myEventRouteId") e i dati di route di eventi contenenti l'endpoint e il filtro facoltativo come nell'esempio illustrato di seguito. Per ulteriori informazioni sul filtro degli eventi, consulta questa documentazione.

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

Ottieni il percorso dell'evento

Possiamo ottenere un percorso dell'evento utilizzando getEventRoute l'ID del percorso dell'evento.

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

Elencare i percorsi degli eventi

Possiamo elencare i percorsi degli eventi usando 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}`);
}

Elimina percorso evento

Possiamo eliminare un percorso dell'evento utilizzando deleteEventRoute l'ID del percorso dell'evento.

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

Pubblicare messaggi di telemetria per un gemello digitale

Per pubblicare un messaggio di telemetria per un gemello digitale, è necessario fornire l'ID del gemello digitale, il payload e un ID univoco per il messaggio.

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

È anche possibile pubblicare un messaggio di telemetria per un componente specifico in un gemello digitale. Oltre all'ID del gemello digitale, al payload e all'ID univoco del messaggio, è necessario specificare il percorso del componente di destinazione.

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

Altri esempi

Altri esempi sono disponibili nella directory degli esempi.

Risoluzione dei problemi

Registrazione

L'abilitazione della registrazione può aiutare a individuare informazioni utili sugli errori. Per visualizzare un log di richieste e risposte HTTP, impostare la AZURE_LOG_LEVEL variabile di ambiente su info. In alternativa, la registrazione può essere abilitata in fase di esecuzione chiamando setLogLevel in @azure/logger:

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

setLogLevel("info");

Per istruzioni più dettagliate su come abilitare i log, vedere la documentazione sul pacchetto @azure/logger.

Passaggi successivi

• Dai un'occhiata alla directory degli esempi per esempi dettagliati che illustrano come utilizzare le librerie client.
• Esplora la documentazione di Gemelli digitali di Azure

Contribuire

Per contribuire a questa libreria, leggere la guida per i contributi per altre informazioni su come compilare e testare il codice.

Progetti correlati

• Microsoft Azure SDK per Javascript