適用于 JavaScript 的 Azure Azure Digital Twins Core 用戶端程式庫 - 1.1.0 版

發行項
04/05/2023

此套件包含適用于 Azure Digital Twins API 的同型 SDK，可讓您存取 Azure Digital Twins 服務來管理對應項、模型、關聯性等。

開始使用

目前支援的環境

LTS 版本的 Node.js
Safari、Chrome、Edge 和 Firefox 的最新版本。

如需詳細資訊，請參閱我們的支援原則。

必要條件

Azure Digital Twins 實例。

安裝 `@azure/digital-twins-core` 套件

使用 npm 安裝適用于 JavaScript 的 Digital Twins Core 用戶端程式庫：

npm install @azure/digital-twins-core

瀏覽器支援

JavaScript 套件組合

若要在瀏覽器中使用此用戶端程式庫，您必須先使用套件組合器。如需如何執行這項操作的詳細資訊，請參閱我們的統合檔。

CORS

Azure Digital Twins 目前不支援跨原始來源資源共用 (CORS)。因此，此程式庫無法用來從瀏覽器直接呼叫範本服務。如需指引，請參閱本檔。

重要概念

Azure Digital Twins

Azure Digital Twins 是一項 Azure IoT 服務，其可建立完整的實體環境模型。此服務可建立空間智慧圖形，用模型來呈現人員、空間和裝置之間的關聯性與互動情形。您可以流覽 Azure Digital Twins 檔，以深入瞭解 Azure Digital Twins。

`DigitalTwinsClient`

DigitalTwinsClient 是此程式庫使用者用來管理其 Azure Digital Twins 實例的用戶端物件。

範例

建立 DigitalTwinsClient

若要建立新的 DigitalTwinsClient ，您需要 Azure Digital Twins 實例和認證的端點。在這裡，我們將用於 DefaultAzureCredential 套件 @azure/identity 中的認證。它支援不同的驗證機制，並根據其執行所在的環境來判斷適當的認證類型。 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);

建立、列出、取得、解除委任和刪除模型

建立模型

為了建立模型，我們會將模型清單傳遞至 createModels 。在這裡，我們只會建立一個模型。

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

列出模型：

我們會使用 listModels 來列出所有模型。

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

取得模型

我們可以使用搭配模型識別碼來取得特定模型 getModel 。

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

解除委任模型

我們可以使用搭配模型識別碼來解除委任模型 decomissionModel 。

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

刪除模型

我們可以使用 deleteModel 搭配模型識別碼來刪除模型。

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

建立、取得、查詢和刪除數位對應項

建立數位對應項

若要建立對應項，您必須提供數位對應項的識別碼，以及包含數位對應項物件的 JSON 字串。

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

取得數位分身

我們可以使用數位對應項識別碼來取得數位對應 getDigitalTwin 項。

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

查詢數位分身

使用 Azure Digital Twins 查詢語言來查詢數位對應項的 Azure Digital Twins 實例。以下是如何查詢數位對應項以及如何逐一查看結果的範例。

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

刪除數位對應項

我們可以使用數位對應項識別碼來刪除數位對應 deleteDigitalTwin 項。

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

取得和更新數位對應項元件

取得數位對應項元件

我們可以使用數位對應項識別碼和元件的路徑來取得數位對應項元件 getComponent 。

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

更新數位對應項元件

若要更新數位對應項元件 (，也就是在數位對應項) 內取代、移除或新增元件屬性或子屬性，您需要提供數位對應項識別碼、元件路徑，以及具有屬性 oppath 和的修補程式物件清單。的值 op 是「replace」、「remove」或「add」，而的值 path 是要更新之數位對應項元件的路徑。針對「replace」和「add」作業， value 屬性應該包含在您所需的元件屬性值中。

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

建立和列出數位對應項關聯性

建立數位對應項關聯性

upsertRelationship 會在數位對應項的識別碼、關聯性名稱 (的數位對應項上建立關聯性，在此案例中為「has」) 、關聯性識別碼 (在此案例中為「BuildingHasFloor」) ，以及代表要建立之關聯性的物件。物件必須包含具有索引鍵「$targetId」的屬性，才能指定關聯性的目標。

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

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

列出數位對應項關聯性

針對數位對應項， listRelationships 分別 listIncomingRelationships 列出所有關聯性和所有連入關聯性。

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

建立、取得、列出和刪除事件路由

建立事件路由

若要建立事件路由，請提供事件路由的識別碼 (在此案例中為「myEventRouteId」) ，以及包含端點和選擇性篩選的事件路由資料，如以下範例所示。如需篩選事件的詳細資訊，請參閱此檔。

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

取得事件路由

我們可以使用搭配事件路由識別碼來取得事件路由 getEventRoute 。

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

列出事件路由

我們可以使用列出事件路由 listEventRoutes 。

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

刪除事件路由

我們可以使用 deleteEventRoute 搭配事件路由識別碼來刪除事件路由。

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

發佈數位對應項的遙測訊息

若要發佈數位對應項的遙測訊息，您必須提供數位對應項識別碼、承載，以及訊息的唯一識別碼。

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

您也可以在數位對應項中發佈特定元件的遙測訊息。除了數位對應項識別碼、承載和唯一訊息識別碼之外，您還需要指定目標群組件路徑。

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

其他範例

您可以在 samples 目錄中找到其他範例。

疑難排解

記錄

啟用記錄有助於找出失敗的相關實用資訊。若要查看 HTTP 的要求和回應記錄，請將 AZURE_LOG_LEVEL 環境變數設定為 info。或者，您可以在 @azure/logger 中呼叫 setLogLevel，以在執行階段啟用記錄：

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

setLogLevel("info");

如需如何啟用記錄的詳細指示，可參閱 @azure/logger 套件文件。

下一步

請查看範例目錄，以取得示範如何使用用戶端程式庫的詳細範例。
探索 Azure Digital Twins 檔

參與

如果您希望向此程式庫投稿，請參閱投稿指南，深入瞭解如何組建與測試程式碼。

Microsoft Azure SDK for JAVAscript

共用方式為