Condividi tramite

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

  • Articolo

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

Introduzione

Ambienti attualmente supportati

Per altre informazioni, vedere i criteri di supporto.

Prerequisiti

Installare il pacchetto @azure/digital-twins-core

Installare la libreria client di Digital Twins Core per JavaScript con npm:

npm install @azure/digital-twins-core

Supporto browser

JavaScript Bundle

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.

CORS

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

Concetti chiave

Gemelli digitali di Azure

Gemelli digitali di Azure è un servizio Azure IoT che consente di creare modelli completi dell'ambiente fisico. Consente di 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.

Esempio

Creare DigitalTwinsClient

Per creare un nuovo DigitalTwinsClient, è necessario l'endpoint di un'istanza e delle credenziali di Gemelli digitali di Azure. In questo caso si usa DefaultAzureCredential per le credenziali del pacchetto @azure/identity. Supporta meccanismi di autenticazione diversi e determina il tipo di credenziale appropriato in base all'ambiente in cui è in esecuzione. readme for @azure/identity Per altre informazioni sulle diverse opzioni di autenticazione che è possibile usare, vedere .

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

Creare, elencare, ottenere, rimuovere le autorizzazioni ed eliminare modelli

Creare modelli

Per creare modelli, viene passato un elenco di modelli a createModels. In questo caso viene creato un solo modello.

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

Elencare i modelli

Viene usato listModels per elencare tutti i modelli.

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

Ottenere il modello

È possibile ottenere un modello specifico usando getModel con l'ID modello.

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

Modello di rimozione delle autorizzazioni

È possibile rimuovere le autorizzazioni di un modello usando decomissionModel con l'ID modello.

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

Eliminare il modello

È possibile eliminare un modello usando deleteModel con l'ID modello.

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

Creare, ottenere, eseguire query ed eliminare gemelli digitali

Creare un gemello digitale

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

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

Ottenere il gemello digitale

È possibile ottenere un gemello digitale usando getDigitalTwin con l'ID del gemello digitale.

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

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. Ecco un esempio di come eseguire una query per gemelli digitali e come scorrere i risultati.

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

Eliminare gemelli digitali

È possibile eliminare un gemello digitale usando deleteDigitalTwin con l'ID del gemello digitale.

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

Ottenere e aggiornare i componenti di Gemelli digitali

Ottenere il componente gemello digitale

È possibile ottenere un componente del gemello digitale usando getComponent con l'ID del gemello digitale e il percorso del componente.

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

Aggiornare il componente gemello digitale

Per aggiornare un componente di gemelli digitali , ad esempio sostituire, rimuovere o aggiungere una proprietà del componente o una sottoproprietà all'interno di un gemello digitale, è necessario fornire un ID gemello digitale, un 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 path è il percorso del componente gemello digitale da aggiornare. Per le operazioni "replace" e "add", la value proprietà deve essere inclusa con il valore desiderato della proprietà del componente.

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 relazioni con gemelli digitali

Creare relazioni con gemelli digitali

upsertRelationship crea una relazione su un gemello digitale fornito con ID di un gemello digitale, il nome della relazione (in questo caso "ha"), l'ID di una relazione (in questo caso "BuildingHasItem") 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.

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

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

Elencare le relazioni con gemelli digitali

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

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

Creare, ottenere, elencare ed eliminare route di eventi

Creare una route di eventi

Per creare una route di eventi, specificare un ID di una route di eventi (in questo caso "myEventRouteId") e i dati della route degli eventi contenenti l'endpoint e il filtro facoltativo, come illustrato di seguito. Per altre informazioni sui filtri degli eventi, vedere questa documentazione.

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

Ottenere la route degli eventi

È possibile ottenere una route di eventi usando getEventRoute con l'ID route dell'evento.

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

Elencare le route degli eventi

È possibile elencare le route di eventi usando listEventRoutes.

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

Eliminare la route degli eventi

È possibile eliminare una route di eventi usando deleteEventRoute con l'ID route dell'evento.

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 specificare l'ID del gemello digitale, il payload e un ID univoco per il messaggio.

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 messaggio univoco, è necessario specificare il percorso del componente di destinazione.

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

Esempi aggiuntivi

Altri esempi sono disponibili nella directory degli esempi.

Risoluzione dei problemi

Registrazione

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

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

setLogLevel("info");

Per istruzioni più dettagliate su come abilitare i log, è possibile esaminare la documentazione del pacchetto di @azure/logger.

Passaggi successivi

  • Esaminare la directory degli esempi per esempi dettagliati che illustrano come usare le librerie client.
  • Esplorare la documentazione di Gemelli digitali di Azure

Contributo

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