Azure Digital Twins API および SDK
この記事では、使用可能な Azure Digital Twins API の概要と、API を操作するためのメソッドについて説明します。 REST API は、関連付けられている Swagger を使って直接使用することも、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 を次に示します。
また、コントロール プレーン API の演習を行うには、Azure portal および CLI を使用して Azure Digital Twins を操作します。
データ プレーン API
データ プレーン API は、Azure Digital Twins API であり、Azure Digital Twins インスタンス内の要素を管理するために使用されます。 たとえば、ルートの作成、モデルのアップロード、リレーションシップの作成、ツインの管理などの操作が含まれ、大まかに次のカテゴリーに分類できます。
DigitalTwinModels- DigitalTwinModels カテゴリには、Azure Digital Twins インスタンスのモデルを管理するための API が含まれています。 管理アクティビティには、DTDL で作成されたモデルのアップロード、検証、取得、および削除が含まれます。DigitalTwins- DigitalTwins カテゴリには、開発者が Azure Digital Twins インスタンスで Digital Twins とその関係を作成、変更、および削除するための API が含まれています。Query- Query カテゴリでは、開発者はリレーションシップにわたるツイン グラフで一連の Digital Twins を検索できます。Event Routes- Event Routes カテゴリには、システムを通してダウンストリーミング サービスにデータをルーティングする API が含まれています。Import Jobs- Import Jobs API を使うと、実行時間の長い非同期アクションを管理して、モデル、ツイン、リレーションシップを一括でインポートすることができます。Delete Jobs- Delete Jobs API を使うと、実行時間の長い非同期アクションを管理して、インスタンスのすべてのモデル、ツイン、リレーションシップを削除することができます。
API を直接呼び出すには、データ プレーン Swagger リポジトリの最新の Swagger フォルダーを参照してください。 このフォルダーには、使用法を示す例が保存されているフォルダーも含まれています。 データ プレーン API リファレンス ドキュメントを表示することもできます。
Azure Digital Twins データ プレーン API のために現在使用できる SDK を次に示します。
また、データ プレーン API の演習を行うには、CLI を使用して Azure Digital Twins を操作します。
使用状況と認証に関する注意事項
このセクションには、API と SDK の使用に関する詳細な情報が含まれています。
API に関する注意事項
Azure Digital Twins API を直接呼び出すための一般的な情報を次に示します。
- HTTP REST テスト ツールを使用して、Azure Digital Twins の API を直接呼び出すことができます。 このプロセスの詳細については、「Azure Digital Twins API を呼び出す」を参照してください。
- 現在、Azure Digital Twins ではクロスオリジン リソース共有 (CORS) がサポートされていません。 影響と解決方法の詳細については、「Azure Digital Twins のクロス オリジン リソース共有 (CORS)」を参照してください。
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: 一般的にBasicDigitalTwinのContentsプロパティ内のコンポーネントを表しますBasicRelationship: 一般的にリレーションシップのコア データを表しますDigitalTwinsJsonPropertyName: カスタムのデジタル ツイン型での JSON のシリアル化と逆シリアル化で使用される文字列定数が格納されています
インポート ジョブ API を使用して一括インポートする
インポート ジョブ API は、1 つの API 呼び出しで一連のモデル、ツイン、リレーションシップをインポートできるデータ プレーン API です。 インポート ジョブ API 操作は、CLI コマンドとデータ プレーン SDK にも含まれています。 インポート ジョブ API を使用するには、Azure Blob Storage を使用する必要があります。
アクセス許可を確認する
インポート ジョブ 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
インポート ジョブ API 呼び出しを試みたが、インポートしようとしているいずれかのグラフ要素型に対する書き込みアクセス許可がない場合、ジョブはその型をスキップし、他の型をインポートします。 たとえば、モデルとツインへの書き込みアクセス権限はあるが、リレーションシップへの書き込みアクセス権限はない場合、3 つの型の要素すべてを一括インポートしようとすると、モデルとツインのインポートのみが成功します。 ジョブの状態にはエラーが反映され、どのアクセス許可が不足しているかがメッセージに示されます。
また、Azure Blob Storage コンテナー内の入力ファイルと出力ファイルにアクセスできるように、Azure Digital Twins インスタンスのシステム割り当てマネージド ID に次の RBAC アクセス許可を付与する必要があります。
- Azure Storage 入力 BLOB コンテナーのストレージ BLOB データ閲覧者
- Azure Storage 出力 BLOB コンテナーのストレージ BLOB データ共同作成者
最後に、Jobs API へのリクエストで使用できるベアラー トークンを生成します。 手順については、「ベアラー トークンを追加する」を参照してください。
データを書式設定する
API は、NDJSON ファイルからのグラフ情報の入力を受け入れます。これは、Azure Blob Storage コンテナーにアップロードする必要があります。 ファイルは 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 Storage URL を使用します。
インポート ジョブを実行する
これで、インポート ジョブ API の呼び出しに進むことができます。 1 つの API 呼び出しで完全なグラフをインポートする方法の詳細については、「インポート ジョブ API を使用してモデル、ツイン、リレーションシップを一括でアップロードする」を参照してください。 インポート ジョブ API を使用して、各リソースの種類を個別にインポートすることもできます。 個々のリソースの種類でインポート ジョブ API を使用する方法の詳細については、「モデル、ツイン、リレーションシップに対するインポート ジョブ API の手順」を参照してください。
API 呼び出しの本文で、NDJSON 入力ファイルの Blob Storage URL を指定します。 また、サービスによって作成された出力ログを格納する場所を示す新しい Blob Storage 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 メトリックを使用して、取り込まれたエンティティの合計数を確認できます。
インポート ジョブ API から Cancel 操作を使用して、実行中のインポート ジョブを取り消すこともできます。 ジョブが取り消され、実行されなくなったら、ジョブを削除できます。
制限と考慮事項
インポート ジョブ API を使用する際は、次の考慮事項に留意してください。
- インポート ジョブはアトミック操作ではありません。 失敗、ジョブの部分的な完了、または Cancel 操作を使用する場合、ロールバックはありません。
- Azure Digital Twins インスタンス内で一度にサポートされる一括ジョブは 1 つだけです。 この情報とジョブ API のその他の数値制限は、「Azure Digital Twins の制限事項」で確認できます。
Delete Jobs API を使用して一括削除する
Delete Jobs API は、1 回の API 呼び出しでインスタンス内のすべてのモデル、ツイン、リレーションシップを削除できるデータ プレーン API です。 Delete Jobs API 操作は、CLI コマンドとしても使用できます。 削除ジョブを作成してその状態を確認するための要求の詳細については、API ドキュメントを参照してください。
すべての要素が確実に削除されるようにするには、Delete Jobs API の使用中に次のレコメンデーションにフォローします。
- API 要求を認証するためのベアラー トークンを生成する方法については、「ベアラー トークンを追加する」を参照してください。
- 最近大きい数値のエンティティをグラフにインポートした場合は、しばらく待ってから、削除ジョブを開始する前にすべての要素がグラフ内で同期されていることを確認します。
- 削除ジョブが完了するまで、インスタンスに対するすべての操作 (特にアップロード操作) を停止します。
削除するグラフのサイズによっては、削除ジョブに数分から数時間かかる場合があります。
削除ジョブの既定のタイムアウト期間は 12 時間であり、API のクエリ パラメーターを使用して 15 分から 24 時間の任意の値に調整できます。 これは、削除ジョブがタイムアウトするまでに実行される時間です。この時点で、サービスはジョブがまだ完了していない場合にジョブの停止を試みます。
制限とその他の考慮事項
Delete Jobs API を使用する際は、次の考慮事項に留意してください。
- 削除ジョブはアトミック操作ではありません。 ジョブの失敗、部分的な完了、またはタイムアウトの場合、ロールバックはありません。
- Azure Digital Twins インスタンス内で一度にサポートされる一括ジョブは 1 つだけです。 この情報とジョブ API のその他の数値制限は、「Azure Digital Twins の制限事項」で確認できます。
API メトリックの監視
要求、待機時間、失敗率などの API メトリックは、Azure portal で見ることができます。
Azure Digital Twins メトリックの表示と管理の詳細については、「インスタンスを監視する」を参照してください。 Azure Digital Twins で使用できる API メトリックの完全な一覧については、Azure Digital Twins の API 要求メトリックに関する記事を参照してください。
次のステップ
Azure Digital Twins API に直接要求を行う方法については、次を参照してください。
または、このチュートリアルを使用してクライアント アプリを作成し、.NET SDK を使用する練習を行います。