Azure Digital Twins Swagger リファレンスドキュメント

[アーティクル]
02/03/2020

重要

Azure Digital Twins サービスの新しいバージョンがリリースされました。新しいサービスの拡張された機能に照らして、元の Azure Digital Twins サービス (このドキュメントセットで説明) は廃止されました。

新しいサービスのドキュメントを表示するには、アクティブな Azure Digital Twins のドキュメントを参照してください。

プロビジョニングされた各 Azure Digital Twins インスタンスには、自動生成された独自の Swagger リファレンスドキュメントが含まれています。

Swagger (または OpenAPI) では、複雑な API 情報を、言語に依存しない対話型のリファレンスリソースに統合します。 Swagger は、API に対する操作を実行するために使用する JSON ペイロード、HTTP メソッド、および特定のエンドポイントに関する重要な参考資料を提供します。

Swagger の概要

Swagger では、以下を含む API の対話型の概要が提供されます。

API とオブジェクトモデルの情報。
必須の要求ペイロード、ヘッダー、パラメーター、コンテキストのパス、および HTTP メソッドを指定する REST API エンドポイント。
API の機能のテスト。
HTTP 応答の検証と確認に使用される応答情報の例。
エラーコード情報。

Swagger は、Azure Digital Twins Management API に対して行われる呼び出しの開発およびテストを支援する便利なツールです。

ヒント

API の機能を見ることができる Swagger のプレビューが提供されています。 docs.westcentralus.azuresmartspaces.net/management/swagger でホストされています。

生成された独自の Management API Swagger ドキュメントには、次の場所からアクセスできます。

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger

名前	置換後の文字列
YOUR_INSTANCE_NAME	Azure Digital Twins インスタンスの名前
YOUR_LOCATION	インスタンスをホストするサーバーのリージョン

参考資料

自動的に生成される Swagger の参考資料では、重要な概念の簡単な概要、使用可能な管理 API エンドポイント、および開発とテストを支援する各オブジェクトモデルの説明を提供します。

簡潔な概要では、API について説明されています。

Management API オブジェクトモデルも一覧表示されます。

一覧表示されている各オブジェクトモデルを選択すると、キー属性の詳細な概要が表示されます。

生成された Swagger オブジェクトモデルは、Azure Digital Twins の使用可能なすべてのオブジェクトおよび API を確認するのに便利です。開発者は、Azure Digital Twins でソリューションを作成するときに、このリソースの使用できます。

エンドポイントの概要

Swagger では、Management API を構成するすべてのエンドポイントの完全な概要も提供します。

一覧表示されている各エンドポイントには、次のような要求の必須情報も含まれます。

必須のパラメーター。
必須のパラメーターのデータ型。
リソースにアクセスする HTTP メソッド。

各リソースを選択すると、追加の内容が表示され、さらに詳細な概要が得られます。

Swagger を使用してエンドポイントをテストする

Swagger が提供する強力な機能の 1 つは、ドキュメントの UI から直接、API エンドポイントをテストできることです。

特定のエンドポイントを選択すると、[試してみる] ボタンが表示されます。

$Swagger [Try it out]$試してみる$ ボタン$

そのセクションを展開すると、必須および省略可能な各パラメーターの入力フィールドが表示されます。適切な値を入力し、[Execute]$実行$ を選択します。

テストを実行した後は、応答データを検証できます。

Swagger の応答データ

一覧表示されている各エンドポイントには、開発およびテストを検証するための応答本文データも含まれます。これらの例には、成功した HTTP 要求の状態コードおよび JSON が含まれます。

これらの例には、失敗したテストのデバッグまたは改善に役立つエラーコードも含まれます。

Swagger OAuth 2.0 承認

Note

Azure Digital Twins リソースを作成したユーザープリンシパルにはスペース管理者ロールが割り当てられ、他のユーザーに対して追加のロール割り当てを作成できます。このようなユーザーとそのロールには、API の呼び出しを許可することができます。

こちらのクイックスタートの手順を実行して、Azure Active Directory アプリケーションを作成し、構成します。または、既存のアプリの登録を再利用することもできます。

次のリダイレクト URI を Azure Active Directory アプリ登録に追加します。

https://YOUR_SWAGGER_URL/ui/oauth2-redirect-html

名前	置換後の文字列	例
YOUR_SWAGGER_URL	ポータルで見つかった Management REST API ドキュメントの URL	`https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swagger`

OAuth 2.0 の暗黙的な許可>フローを使用できるようにするには、[暗黙的なアクセス許可トークン] チェックボックスをオンにします。 [構成]、[保存] の順に選択します。
Azure Active Directory アプリの [クライアント ID] をコピーします。

Azure Active Directory の登録を完了した後:

Swagger ページで [Authorize]$承認$ ボタンをクリックします。
アプリケーション ID を client_id フィールドに貼り付けます。
次の成功のモーダルにリダイレクトされます。

OAuth 2.0 によって保護された要求の対話的なテストに関する詳細については、公式ドキュメントをお読みください。

次のステップ

Azure Digital Twins のオブジェクトモデルおよび空間インテリジェンスグラフについて詳しくは、Azure Digital Twins オブジェクトモデルに関する記事をご覧ください。
Management API を使用して認証を行う方法については、API を使用した認証に関する記事をご覧ください。

Azure Digital Twins Swagger リファレンス ドキュメント