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

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

Swagger (または OpenAPI) では、複雑な API 情報を、言語に依存しない対話型のリファレンス リソースに統合します。Swagger, or OpenAPI, unites complex API information into an interactive and language-agnostic reference resource. Swagger は、API に対する操作を実行するために使用する JSON ペイロード、HTTP メソッド、および特定のエンドポイントに関する重要な参考資料を提供します。Swagger provides critical reference material about which JSON payloads, HTTP methods, and specific endpoints to use to perform operations against an API.

Swagger の概要Swagger summary

Swagger では、以下を含む API の対話型の概要が提供されます。Swagger provides an interactive summary of your API, which includes:

  • API とオブジェクト モデルの情報。API and object model information.
  • 必須の要求ペイロード、ヘッダー、パラメーター、コンテキストのパス、および HTTP メソッドを指定する REST API エンドポイント。REST API endpoints that specify the required request payloads, headers, parameters, context paths, and HTTP methods.
  • API の機能のテスト。Testing of API functionalities.
  • HTTP 応答の検証と確認に使用される応答情報の例。Example response information used to validate and confirm HTTP responses.
  • エラー コード情報。Error code information.

Swagger は、Azure Digital Twins Management API に対して行われる呼び出しの開発およびテストを支援する便利なツールです。Swagger is a convenient tool to assist with development and testing calls made to the Azure Digital Twins Management APIs.

ヒント

API の機能を見ることができる Swagger のプレビューが提供されています。A Swagger sneak preview is provided to demonstrate the API feature set. docs.westcentralus.azuresmartspaces.net/management/swagger でホストされています。It's hosted at docs.westcentralus.azuresmartspaces.net/management/swagger.

生成された独自の Management API Swagger ドキュメントには、次の場所からアクセスできます。You can access your own generated Management API Swagger documentation at:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger
NameName 置換後の文字列Replace with
YOUR_INSTANCE_NAMEYOUR_INSTANCE_NAME Azure Digital Twins インスタンスの名前The name of your Azure Digital Twins instance
YOUR_LOCATIONYOUR_LOCATION インスタンスをホストするサーバーのリージョンWhich server region your instance is hosted on

参考資料Reference material

自動的に生成される Swagger の参考資料では、重要な概念の簡単な概要、使用可能な管理 API エンドポイント、および開発とテストを支援する各オブジェクト モデルの説明を提供します。The automatically generated Swagger reference material supplies a quick overview of important concepts, available Management API endpoints, and a description of each object model to assist development and testing.

簡潔な概要では、API について説明されています。A concise summary describes the API.

Swagger の最上部Swagger top

Management API オブジェクト モデルも一覧表示されます。Management API object models are also listed.

Swagger モデルSwagger models

一覧表示されている各オブジェクト モデルを選択すると、キー属性の詳細な概要が表示されます。You can select each listed object model for a more detailed summary of key attributes.

Swagger モデルSwagger model

生成された Swagger オブジェクト モデルは、Azure Digital Twins の使用可能なすべてのオブジェクトおよび API を確認するのに便利です。The generated Swagger object models are convenient to see all available Azure Digital Twins objects and APIs. 開発者は、Azure Digital Twins でソリューションを作成するときに、このリソースの使用できます。Developers can use this resource when they build solutions on Azure Digital Twins.

エンドポイントの概要Endpoint summary

Swagger では、Management API を構成するすべてのエンドポイントの完全な概要も提供します。Swagger also provides a thorough overview of all endpoints that compose the Management APIs.

一覧表示されている各エンドポイントには、次のような要求の必須情報も含まれます。Each listed endpoint also includes the required request information, such as the:

  • 必須のパラメーター。Required parameters.
  • 必須のパラメーターのデータ型。Required parameter data types.
  • リソースにアクセスする HTTP メソッド。HTTP method to access the resource.

Swagger エンドポイントSwagger endpoints

さらに詳細な概要を見るには、各リソースをクリックします。To see a more detailed overview, select each resource.

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

Swagger が提供する強力な機能の 1 つは、ドキュメントの UI から直接、API エンドポイントをテストできることです。One of the powerful functionalities Swagger provides is the ability to test an API endpoint directly through the documentation UI.

特定のエンドポイントを選択すると、 [試してみる] と表示されます。After you select a specific endpoint, you see Try it out.

Swagger の試用Swagger try

そのセクションを展開すると、必須および省略可能な各パラメーターの入力フィールドが表示されます。Expand that section to bring up input fields for each required and optional parameter. 適切な値を入力し、 [Execute](実行) を選択します。Enter the correct values, and select Execute.

Swagger の試用後Swagger tried

テストを実行した後は、応答データを検証できます。After you execute the test, you can validate the response data.

Swagger の応答データSwagger response data

一覧表示されている各エンドポイントには、開発およびテストを検証するための応答本文データも含まれます。Each listed endpoint also includes response body data to validate your development and tests. これらの例には、HTTP 要求が成功したときに表示される状態コードと JSON が含まれます。These examples include the status codes and JSON you want to see for successful HTTP requests.

Swagger の応答Swagger response

これらの例には、失敗したテストのデバッグまたは改善に役立つエラー コードも含まれます。The examples also include error codes to help debug or improve failing tests.

Swagger OAuth 2.0 承認Swagger OAuth 2.0 authorization

注意

  • Azure Digital Twins リソースを作成したユーザー プリンシパルにはスペース管理者ロールが割り当てられ、他のユーザーに対して追加のロール割り当てを作成できます。The user principal that created the Azure Digital Twins resource will have a Space Administrator role assignment and will be able to create additional role assignments for other users. このようなユーザーとそのロールには、API の呼び出しを許可することができます。Such users and their roles can be authorized to call the APIs.
  1. こちらのクイック スタートの手順に従うか、Azure Digital Twins アプリを Azure Active Directory レガシに登録して、Azure AD アプリケーションを作成し、構成します。Follow the steps in this quickstart or Register your Azure Digital Twins app with Azure Active Directory legacy to create and configure an Azure AD application. または、既存のアプリの登録を再利用することもできます。Alternatively, you can reuse an existing app registration.

  2. 次の応答 URL をアプリの登録に追加します。Add the following reply url to the app registration:

    https://YOUR_SWAGGER_URL/ui/oauth2-redirect-html
    
    EnableAdfsAuthenticationName 置換後の文字列Replace with Example
    YOUR_SWAGGER_URLYOUR_SWAGGER_URL ポータルで見つかった Management REST API ドキュメントの URLYour Management REST API documentation URL found in the portal https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swagger
  3. Azure AD アプリの ID をコピーします。Copy the ID of your Azure AD app.

Azure Active Directory の登録を完了した後:After completing the Azure Active Directory registration:

  1. Swagger ページで [Authorize](承認) ボタンをクリックします。Select the Authorize button on your swagger page.

    Swagger の [Authorize](承認) ボタンをクリックするSelect the Swagger authorize button

  2. アプリケーション ID を [client_id] フィールドに貼り付けます。Paste the application ID into the client_id field.

    Swagger の [client_id] フィールドSwagger client_id field

  3. 次の成功のモーダルにリダイレクトされます。You will then be redirected to the following success modal.

    Swagger のリダイレクト モーダルSwagger redirect modal

OAuth 2.0 によって保護された要求の対話的なテストに関する詳細については、公式ドキュメントを参照してください。To learn more about interactively testing requests protected by OAuth 2.0, see the official documentation.

次の手順Next steps