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

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

はじめに

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

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

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

前提条件

• Azure Digital Twins インスタンス。

@azure/digital-twins-core パッケージのインストール

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

npm install @azure/digital-twins-core

ブラウザーのサポート

JavaScript バンドル

ブラウザーでこのクライアント ライブラリを使用するには、まず bundler を使用する必要があります。 これを行う方法の詳細については、 バンドルに関するドキュメントを参照してください。

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使用できるさまざまな認証オプションの詳細については、 を参照してください。

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渡します。 ここでは、1 つのモデルのみを作成します。

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

モデルを取得する

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

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

使用停止モデル

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

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

モデルを削除する

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

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

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

デジタル ツインを作成する

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

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

デジタル ツインを取得する

を使用して、デジタル ツイン ID を使用 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}`);
}

デジタル ツインを削除する

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

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

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

デジタル ツイン コンポーネントを取得する

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

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 コンポーネント プロパティの目的の値に含める必要があります。

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 (この場合は "BuildingHas Floor") と、作成するリレーションシップを表すオブジェクトを使用して、デジタル ツインにリレーションシップを作成します。 リレーションシップのターゲットを指定するには、オブジェクトにキー "$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}`);
}

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

イベント ルートを作成する

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

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

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

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

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

イベント ルートを削除する

を使用してイベント ルート ID を使用して deleteEventRoute イベント ルートを削除できます。

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

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

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

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

デジタル ツイン内の特定のコンポーネントのテレメトリ メッセージを発行することもできます。 デジタル ツイン ID、ペイロード、および一意のメッセージ 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 パッケージに関するドキュメントを参照してください。

次のステップ

• クライアント ライブラリの使用方法を示す詳細な例については、 samples ディレクトリを参照してください。
• Azure Digital Twins の ドキュメントを確認する

共同作成

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

関連プロジェクト

• Microsoft Azure SDK for Javascript