JavaScript 用 Azure Digital Twins Core クライアントライブラリ - バージョン 2.0.0

2025-05-28

このパッケージには、ツイン、モデル、リレーションシップなどを管理するための Azure Digital Twins サービスへのアクセスを提供する Azure Digital Twins API のアイソモーフィック SDK が含まれています。

作業の開始

現在サポートされている環境

Node.js の LTS バージョン
Safari、Chrome、Edge、Firefox の最新バージョン。

詳細については、サポートポリシーのを参照してください。

[前提条件]

Azure Digital Twins インスタンス。

`@azure/digital-twins-core` パッケージをインストールする

JavaScript 用の Digital Twins Core クライアントライブラリを npm でインストールします。

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 インスタンスへのエンドポイントと資格情報が必要です。ここでは、パッケージ@azure/identityからの資格情報にDefaultAzureCredentialを使用します。さまざまな認証メカニズムをサポートし、実行している環境に基づいて適切な資格情報の種類を決定します。使用できるさまざまな認証オプションの詳細については、 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);

モデルの作成、一覧表示、取得、廃止、削除

モデルを作成する

モデルを作成するために、モデルのリストを createModelsに渡します。ここでは、1つのモデルのみを作成します。

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

モデルを一覧表示する

listModelsを使用してすべてのモデルをリストします。

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

モデルを取得

モデルIDを持つ getModel を使用して、特定のモデルを取得できます。

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

廃止モデル

モデルIDの decomissionModel を使用して、モデルを廃止できます。

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

モデルを削除する

モデルIDの deleteModel を使用してモデルを削除できます。

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

デジタルツインの作成、取得、クエリ、削除

デジタルツインを作成

ツインを作成するには、デジタルツインの ID と、デジタルツインオブジェクトを含む JSON 文字列を指定する必要があります。

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

デジタルツインを入手する

デジタルツインIDを持つ getDigitalTwin を使用して、デジタルツインを取得できます。

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

デジタルツインのクエリ

Azure Digital Twins クエリ言語を使用して、Azure Digital Twins インスタンスに対してデジタルツインのクエリを実行します。デジタルツインのクエリ方法と、結果を反復処理する方法の例を次に示します。

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

デジタルツインの削除

デジタルツインIDを持つ deleteDigitalTwin を使用して、デジタルツインを削除できます。

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

デジタルツインコンポーネントの取得と更新

デジタルツインコンポーネントを入手する

デジタルツインコンポーネントは、デジタルツインIDとコンポーネントのパスを持つ getComponent を使用して取得できます。

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

デジタルツインコンポーネントの更新

デジタルツインコンポーネントを更新する(つまり、デジタルツイン内のコンポーネントプロパティまたはサブプロパティを置き換え、削除、または追加する)には、デジタルツインID、コンポーネントパス、およびプロパティ op と pathを持つパッチオブジェクトのリストを提供する必要があります。 opの値は「replace」、「remove」、または「add」で、pathの値は更新されるデジタルツインコンポーネントへのパスです。 "replace" 操作と "add" 操作の場合、 value プロパティをコンポーネントプロパティの目的の値に含める必要があります。

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

デジタルツインの関係を作成してリストアップ

デジタルツインの関係性を構築

upsertRelationship デジタルツインの ID、リレーションシップの名前 (この場合は "has")、リレーションシップの ID (この場合は "BuildingHasFloor")、および作成するリレーションシップを表すオブジェクトで指定されたデジタルツインにリレーションシップを作成します。オブジェクトには、リレーションシップのターゲットを指定するためのキー "$targetId" を持つプロパティが含まれている必要があります。

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

デジタルツインの関係を一覧表示する

デジタルツインの場合、 listRelationships と listIncomingRelationships には、それぞれすべてのリレーションシップとすべての受信リレーションシップが一覧表示されます。

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

イベントルートの作成、取得、一覧表示、削除

イベントルートの作成

イベントルートを作成するには、イベントルートの ID (この場合は "myEventRouteId") と、エンドポイントと次の例のような省略可能なフィルターを含むイベントルートデータを指定します。イベントのフィルタリングの詳細については、このドキュメントを参照してください。

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

イベントルートを取得する

イベントルートIDを持つ getEventRoute を使用して、イベントルートを取得できます。

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

イベントルートの一覧表示

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

イベントルートの削除

イベントルートを削除するには、 deleteEventRoute とイベントルート ID を指定します。

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

デジタルツインのテレメトリメッセージを発行する

デジタルツインのテレメトリメッセージを発行するには、デジタルツイン ID、ペイロード、およびメッセージの一意の ID を指定する必要があります。

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

また、デジタルツイン内の特定のコンポーネントのテレメトリメッセージを発行することもできます。デジタルツイン ID、ペイロード、一意のメッセージ ID に加えて、ターゲットコンポーネントのパスを指定する必要があります。

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

その他の例

その他の例については、 samples ディレクトリを参照してください。

トラブルシューティング

ロギング（記録）

ログの記録を有効にすると、エラーに関する有用な情報を明らかにするのに役立つ場合があります。 HTTP 要求と応答のログを表示するには、環境変数 AZURE_LOG_LEVEL を info に設定します。または、setLogLevel で @azure/logger を呼び出して、実行時にログ記録を有効にすることもできます。

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

setLogLevel("info");

ログを有効にする方法の詳細については、@azure/logger パッケージに関するドキュメントを参照してください。

次のステップ

サンプルディレクトリには、クライアントライブラリの使用方法を示す詳細な例があります。
Azure Digital Twins のドキュメントを確認する

投稿

このライブラリに投稿する場合は、コードをビルドしてテストする方法の詳細については、投稿ガイドをお読みください。

JavaScript 用の Microsoft Azure SDK