次の方法で共有


Azure Digital Twins API および SDK

この記事では、使用可能な Azure Digital Twins API の概要と、API を操作するためのメソッドについて説明します。 REST API は、関連付けられている Swagger を使って直接使用することも (Postman などのツールを使用)、SDK を通して使用することもできます。

Azure Digital Twins には、インスタンスとその要素を管理するためのコントロール プレーン API、データ プレーン API、SDK が用意されています。

  • コントロール プレーン API は、Azure Resource Manager (ARM) API であり、インスタンスの作成や削除などのリソース管理操作に対応しています。
  • データ プレーン API は、Azure Digital Twins API であり、モデル、ツイン、グラフの管理などのデータ管理操作に使用されます。
  • この SDK は、既存の API を利用して、カスタム アプリケーションの開発が Azure Digital Twins を役立てることで容易になるようにします。

コントロール プレーン API

コントロール プレーン API は、ARM API であり、Azure Digital Twins インスタンス全体を管理するために使用されます。そのため、インスタンス全体の作成や削除などの操作に対応しています。 また、エンドポイントの作成と削除にもこれらの API を使用します。

API を直接呼び出すには、コントロール プレーン Swagger リポジトリの最新の Swagger フォルダーを参照してください。 このフォルダーには、使用法を示す例が保存されているフォルダーも含まれています。

Azure Digital Twins コントロール プレーン API で現在使用できる SDK を次に示します。

SDK 言語 パッケージ リンク リファレンス ドキュメント ソース コード
.NET (C#) NuGet の Azure.ResourceManager.DigitalTwins Azure DigitalTwins SDK for .NET のリファレンス GitHub の.NET 用 Microsoft Azure Digital Twins 管理クライアント ライブラリ
Java Maven の azure-resourcemanager-digitaltwins リソース管理のリファレンス - Digital Twins GitHub の Java 用 Azure Resource Manager AzureDigitalTwins クライアント ライブラリ
JavaScript npm の JavaScript 用 AzureDigitalTwinsManagement クライアント ライブラリ GitHub の JavaScript 用 AzureDigitalTwinsManagement クライアント ライブラリ
Python PyPI の azure-mgmt-digitaltwins GitHub の Microsoft Azure SDK for Python
Go azure-sdk-for-go/services/digitaltwins/mgmt GitHub の Azure SDK for Go

また、Azure portalCLI を使用して Azure Digital Twins と対話することで、コントロール プレーン API を実行することもできます。

データ プレーン API

データ プレーン API は、Azure Digital Twins API であり、Azure Digital Twins インスタンス内の要素を管理するために使用されます。 たとえば、ルートの作成、モデルのアップロード、リレーションシップの作成、ツインの管理などの操作が含まれ、大まかに次のカテゴリーに分類できます。

API を直接呼び出すには、データ プレーン Swagger リポジトリの最新の Swagger フォルダーを参照してください。 このフォルダーには、使用法を示す例が保存されているフォルダーも含まれています。 データ プレーン API リファレンス ドキュメントを表示することもできます。

Azure Digital Twins データ プレーン API で現在使用できる SDK を次に示します。

SDK 言語 パッケージ リンク リファレンス ドキュメント ソース コード
.NET (C#) NuGet の Azure.DigitalTwins.Core .NET 用 Azure IoT Digital Twins クライアント ライブラリのリファレンス GitHub の .NET 用 Azure IoT Digital Twins クライアント ライブラリ
Java Maven の com.azure:azure-digitaltwins-core Java の Azure Digital Twins SDK のリファレンス GitHub の Java 用 Azure IoT Digital Twins クライアント ライブラリ
JavaScript npm の JavaScript 用 Azure Digital Twins コア クライアント ライブラリ Reference for @azure/digital-twins-core GitHub の JavaScript 用 Azure Digital Twins コア クライアント ライブラリ
Python PyPI の Python 用 Azure Digital Twins コア クライアント ライブラリ azure-digitaltwins-core のリファレンス GitHub の Python 用 Azure Digital Twins コア クライアント ライブラリ

CLI を使用して Azure Digital Twins と対話することで、データ プレーン API を実行することもできます。

使用状況と認証に関する注意事項

このセクションには、API と SDK の使用に関する詳細な情報が含まれています。

API に関する注意事項

Azure Digital Twins API を直接呼び出すための一般的な情報を次に示します。

API 要求の認証に関する詳細情報を次に示します。

  • Azure Digital Twins API 要求のベアラー トークンを生成する方法の 1 つは、az account get-access-token CLI コマンドを使用することです。 詳細な手順については、ベアラー トークンの取得に関する記事を参照してください
  • Azure Digital Twins API への要求には、Azure Digital Twins インスタンスが存在する同じ Microsoft Entra ID テナントの一部であるユーザーまたはサービス プリンシパルが必要です。 Azure Digital Twins エンドポイントの悪意のあるスキャンを防ぐために、発信元のテナントの外部からのアクセス トークンを含む要求には、"404 サブドメインが見つかりませんでした" というエラー メッセージが返されます。 このエラーは、ユーザーまたはサービス プリンシパルに Microsoft Entra B2B コラボレーションを通じて Azure Digital Twins データ所有者または Azure Digital Twins データ閲覧者ロールが付与された場合でも返されます。 複数のテナントにわたるアクセスを実現する方法については、アプリ認証コードを作成するを参照してください。

SDK の注意事項

Azure Digital Twins の基になる SDK は Azure.Core. SDK のインフラストラクチャと種類については、Azure 名前空間のドキュメントを参照してください。

SDK での認証に関する詳細な情報を次に示します。

  • まず、クラスをインスタンス化します DigitalTwinsClient 。 コンストラクターには、Azure.Identity パッケージ内の各種認証情報を使用して取得できる資格情報が必要です。 Azure.Identity の詳細については、名前空間に関するドキュメントを参照してください。
  • 作業を開始するときには InteractiveBrowserCredential が役立ちますが、マネージド ID の資格情報など、他にもいくつかのオプションがあります。これを使用して、Azure Digital Twins に対して MSI を使用してセットアップされた Azure Functions を認証できます。 InteractiveBrowserCredential の詳細については、クラスのドキュメントを参照してください。

関数と返されるデータに関する詳細な情報を次に示します。

  • すべてのサービス API 呼び出しは、DigitalTwinsClient クラスのメンバー関数として公開されます。
  • すべてのサービス関数には、同期バージョンと非同期バージョンが存在します。
  • すべてのサービス関数は、400 以上のリターン状態に対して例外をスローします。 try セクションに呼び出しをラップし、少なくとも RequestFailedExceptions をキャッチします。 この種類の例外の詳細については、リファレンス ドキュメントを参照してください。
  • ほとんどのサービス メソッドは Response<T> (または非同期呼び出しの場合は Task<Response<T>>) を返します。 T は、サービス呼び出しで返されるオブジェクトのクラスです。 応答クラスは、サービスの戻り値をカプセル化し、その Value フィールドに戻り値を表示します。
  • ページングされた結果を含むサービス メソッドは、結果として Pageable<T> または AsyncPageable<T> を返します。 Pageable<T> クラスの詳細についてはそのリファレンス ドキュメントを、AsyncPageable<T> の詳細についてはそのリファレンス ドキュメントを参照してください。
  • await foreach ループを使用して、ページングした結果を反復処理できます。 このプロセスの詳細については、「C# 8 の非同期列挙型を使った反復処理」を参照してください。
  • サービス メソッドは、可能な限り、厳密に型指定されたオブジェクトを返します。 ただし、Azure Digital Twins は、実行時にユーザーによって構成されたカスタム モデル (サービスにアップロードされた DTDL モデルを使用) に基づいているため、多くのサービス API はツイン データを JSON 形式で取得して返します。

.NET (C#) SDK のシリアル化のヘルパー

シリアル化のヘルパーは、基本情報にアクセスするためのツイン データを、迅速に作成または逆シリアル化するために .NET (C#) SDK 内で使用できるヘルパー関数です。 コア SDK メソッドでは、既定でツイン データが JSON として返されるため、それらのヘルパー クラスを使用して、ツイン データをさらに分割できます。

使用できるヘルパー クラスは次のとおりです。

  • BasicDigitalTwin: 一般的にデジタル ツインのコア データを表します
  • BasicDigitalTwinComponent: 一般的に BasicDigitalTwinContents プロパティ内のコンポーネントを表します
  • BasicRelationship: 一般的にリレーションシップのコア データを表します
  • DigitalTwinsJsonPropertyName: カスタムのデジタル ツイン型での JSON のシリアル化と逆シリアル化で使用される文字列定数が格納されています

Import Jobs API を使用した一括インポート

Import Jobs API は、1 つの API 呼び出しで一連のモデル、ツイン、リレーションシップをインポートできるデータ プレーン API です。 インポート ジョブ API 操作は、CLI コマンドとデータ プレーン SDK にも含まれています Import Jobs API を使用するには、Azure Blob Storage使用する必要があります。

アクセス許可を確認する

Import Jobs API を使用するには、このセクションで説明するアクセス許可設定を有効にする必要があります。

まず、Azure Digital Twins インスタンスのシステム割り当てマネージド ID が必要です。 インスタンスのシステム マネージド ID を設定する手順については、「インスタンスのマネージド ID を有効または無効にする」を参照してください

次のデータ アクション カテゴリに対する書き込みアクセス許可Azure Digital Twins インスタンスに必要です。

  • Microsoft.DigitalTwins/jobs/*
  • ジョブ呼び出しに含めるグラフ要素。 Microsoft.DigitalTwins/models/*これには、、、 Microsoft.DigitalTwins/digitaltwins/*Microsoft.DigitalTwins/digitaltwins/relationships/*

これらのすべてのアクセス許可を提供する組み込みロールは、Azure Digital Twins データ所有者です。 カスタム ロールを使用して、必要なデータ型にのみきめ細かいアクセス権を付与することもできます。 Azure Digital Twins のロールの詳細については、「Azure Digital Twins ソリューションのセキュリティ」を参照してください

Note

Import Jobs API 呼び出しを試みたが、インポートしようとしているいずれかのグラフ要素の種類に対する書き込みアクセス許可がない場合、ジョブはその型をスキップし、他の型をインポートします。 たとえば、モデルとツインへの書き込みアクセス権があり、リレーションシップにはアクセスできない場合、3 種類の要素すべてを一括インポートしようとすると、モデルとツインのインポートのみが成功します。 ジョブの状態にはエラーが反映され、どのアクセス許可が不足しているかがメッセージに示されます。

また、Azure Blob Storage コンテナー内の入力ファイルと出力ファイルにアクセスできるように、Azure Digital Twins インスタンスのシステム割り当てマネージド ID に次 の RBAC アクセス許可 を付与する必要もあります。

最後に、Jobs API への要求で使用できるベアラー トークンを生成します。 手順については、ベアラー トークンの取得に関する記事を参照してください

データを書式設定する

API は、NDJSON ファイルからのグラフ情報の入力を受け入れます。これは、Azure BLOB ストレージ コンテナーにアップロードする必要があります。 ファイルはセクションで Header 始まり、その後に省略可能な Modelsセクション、 Twinsおよび Relationships. 3 種類のグラフ データをすべてファイルに含める必要はありませんが、存在するセクションはその順序に従う必要があります。 この API で作成されたツインとリレーションシップには、必要に応じてプロパティの初期化を含めることができます。

インポート API のサンプル入力データ ファイルを次に示します。

{"Section": "Header"}
{"fileVersion": "1.0.0", "author": "foobar", "organization": "contoso"}
{"Section": "Models"}
{"@id":"dtmi:com:microsoft:azure:iot:model0;1","@type":"Interface","contents":[{"@type":"Property","name":"property00","schema":"integer"},{"@type":"Property","name":"property01","schema":{"@type":"Map","mapKey":{"name":"subPropertyName","schema":"string"},"mapValue":{"name":"subPropertyValue","schema":"string"}}},{"@type":"Relationship","name":"has","target":"dtmi:com:microsoft:azure:iot:model1;1","properties":[{"@type":"Property","name":"relationshipproperty1","schema":"string"},{"@type":"Property","name":"relationshipproperty2","schema":"integer"}]}],"description":{"en":"This is the description of model"},"displayName":{"en":"This is the display name"},"@context":"dtmi:dtdl:context;2"}
{"@id":"dtmi:com:microsoft:azure:iot:model1;1","@type":"Interface","contents":[{"@type":"Property","name":"property10","schema":"string"},{"@type":"Property","name":"property11","schema":{"@type":"Map","mapKey":{"name":"subPropertyName","schema":"string"},"mapValue":{"name":"subPropertyValue","schema":"string"}}}],"description":{"en":"This is the description of model"},"displayName":{"en":"This is the display name"},"@context":"dtmi:dtdl:context;2"}
{"Section": "Twins"}
{"$dtId":"twin0","$metadata":{"$model":"dtmi:com:microsoft:azure:iot:model0;1"},"property00":10,"property01":{"subProperty1":"subProperty1Value","subProperty2":"subProperty2Value"}}
{"$dtId":"twin1","$metadata":{"$model":"dtmi:com:microsoft:azure:iot:model1;1"},"property10":"propertyValue1","property11":{"subProperty1":"subProperty1Value","subProperty2":"subProperty2Value"}}
{"Section": "Relationships"}
{"$dtId":"twin0","$relationshipId":"relationship","$targetId":"twin1","$relationshipName":"has","relationshipProperty1":"propertyValue1","relationshipProperty2":10}

ヒント

モデル、ツイン、リレーションシップをインポート API でサポートされている NDJSON に変換するサンプル プロジェクトについては、「Azure Digital Twins Bulk Import NDJSON Generator」を参照してください。 サンプル プロジェクトは .NET 用に記述されており、独自のインポート ファイルの作成に役立つダウンロードまたは調整が可能です。

ファイルが作成されたら、任意のアップロード方法 (AzCopy コマンド、Azure CLI、または Azure portal) を使用して、Azure Blob Storage 内のブロック BLOB にアップロードします。 インポート ジョブ API 呼び出しの本文で、NDJSON ファイルの BLOB ストレージ URL を使用します。

インポート ジョブを実行する

これで、Import Jobs API の呼び出しに進むことができます。 1 つの API 呼び出しで完全なグラフをインポートする方法の詳細については、「Import Jobs API を使用してモデル、ツイン、リレーションシップを一括でアップロードする」を参照してください。 Import Jobs API を使用して、各リソースの種類を個別にインポートすることもできます。 個々のリソースの種類でジョブのインポート API を使用する方法の詳細については、「モデル、ツインおよびリレーションシップのジョブ API のインポート手順」を参照してください。

API 呼び出しの本文で、NDJSON 入力ファイルの BLOB ストレージ URL を指定します。 また、サービスによって作成された出力ログを格納する場所を示す新しい BLOB ストレージ URL も提供します。

重要

Azure Digital Twins インスタンスのシステム割り当てマネージド ID に、「アクセス許可の確認」セクションで説明されているストレージ BLOB RBAC アクセス許可があることを確認します。

インポート ジョブが実行されると、サービスによって構造化された出力ログが生成され、BLOB コンテナーの新しい追加 BLOB として、要求の出力 BLOB に指定した URL の場所に格納されます。 モデル、ツイン、リレーションシップを正常にインポートするジョブの出力ログの例を次に示します。

{"timestamp":"2022-12-30T19:50:34.5540455Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"status":"Started"}}
{"timestamp":"2022-12-30T19:50:37.2406748Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Models","status":"Started"}}
{"timestamp":"2022-12-30T19:50:38.1445612Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Models","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:38.5475921Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Twins","status":"Started"}}
{"timestamp":"2022-12-30T19:50:39.2744802Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Twins","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:39.7494663Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Relationships","status":"Started"}}
{"timestamp":"2022-12-30T19:50:40.4480645Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Relationships","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:41.3043264Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"status":"Succeeded"}}

ジョブが完了すると、BulkOperationEntityCount メトリックを使用して、取り込まれたエンティティの合計数を確認できます。

Import Jobs API からの Cancel 操作を使用して、実行中のインポート ジョブを取り消すこともできます。 ジョブが取り消され、実行されなくなったら、ジョブを削除できます。

制限と考慮事項

Import Jobs API を使用する際は、次の考慮事項に留意してください。

  • インポート ジョブはアトミック操作ではありません。 失敗、部分的なジョブの完了、またはキャンセル操作使用の場合、ロールバックはありません。
  • Azure Digital Twins インスタンス内で一度にサポートされる一括ジョブは 1 つだけです。 この情報と、Azure Digital Twins のジョブ API の その他の数値制限を表示できます。

Delete Jobs API を使用した一括削除

Delete Jobs API は、1 回の API 呼び出しでインスタンス内のすべてのモデル、ツイン、リレーションシップを削除できるデータ プレーン API です。 ジョブの削除 API 操作は、CLI コマンドとしても使用できます。 削除ジョブを作成し、その状態をチェックするための要求の詳細については、API ドキュメントを参照してください。

すべての要素が確実に削除されるようにするには、Delete Jobs API の使用中に次の推奨事項に従います。

  • API 要求を認証するためのベアラー トークンを生成する方法については、ベアラー トークンの取得に関する記事を参照してください
  • 最近多数のエンティティをグラフにインポートした場合は、しばらく待ってから、削除ジョブを開始する前にすべての要素がグラフ内で同期されていることを確認します。
  • 削除ジョブが完了するまで、インスタンスに対するすべての操作 (特にアップロード操作) を停止します。

削除するグラフのサイズによっては、削除ジョブに数分から数時間かかる場合があります。

削除ジョブの既定のタイムアウト期間は 12 時間であり、API のクエリ パラメーターを使用して 15 分から 24 時間の任意の値に調整できます。 これは、削除ジョブがタイムアウトするまでに実行される時間です。この時点で、サービスはジョブがまだ完了していない場合にジョブの停止を試みます。

制限とその他の考慮事項

ジョブの削除 API を使用する際は、次の点に注意してください。

  • 削除ジョブはアトミック操作ではありません。 ジョブの失敗、部分的なジョブの完了、またはタイムアウトの場合、ロールバックはありません。
  • Azure Digital Twins インスタンス内で一度にサポートされる一括ジョブは 1 つだけです。 この情報と、Azure Digital Twins のジョブ API の その他の数値制限を表示できます。

API メトリックの監視

要求、待機時間、失敗率などの API メトリックは、Azure portal で見ることができます。

Azure Digital Twins メトリックの表示と管理の詳細については、「インスタンスの監視」を参照してください。 Azure Digital Twins で使用できる API メトリックの完全な一覧については、Azure Digital Twins の API 要求メトリックに関する記事を参照してください。

次のステップ

Postman を使用して Azure Digital Twins API に直接要求を行う方法を確認します。

または、このチュートリアルを使用してクライアント アプリを作成し、.NET SDK を使用する練習を行います。