您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

Azure 数字孪生 Swagger 参考文档Azure Digital Twins Swagger reference documentation

每个预配的 Azure 数字孪生实例都包含自己生成的 Swagger 参考文档。Each provisioned Azure Digital Twins instance includes its own automatically generated Swagger reference documentation.

SwaggerOpenAPI 将复杂的 API 信息整合到一个交互式和语言无关的参考资源中。Swagger, or OpenAPI, unites complex API information into an interactive and language-agnostic reference resource. Swagger 提供有关要使用哪些 JSON 有效负载、HTTP 方法和特定终结点对 API 执行操作的关键参考资料。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.
  • REST API 终结点,用于指定必需的请求有效负载、标头、参数、上下文路径和 HTTP 方法。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 数字孪生管理 API 作出的开发和测试调用。Swagger is a convenient tool to assist with development and testing calls made to the Azure Digital Twins Management APIs.

提示

我们提供了 Swagger 非公开预览版来演示 API 功能集。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.

可以在以下位置访问你自己的已生成管理 API Swagger 文档:You can access your own generated Management API Swagger documentation at:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger
名称Name 替换为Replace with
YOUR_INSTANCE_NAMEYOUR_INSTANCE_NAME Azure 数字孪生实例的名称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

还列出了管理 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 数字孪生对象和 APIThe generated Swagger object models are convenient to see all available Azure Digital Twins objects and APIs. 开发人员在 Azure 数字孪生上生成解决方案时可以使用此资源。Developers can use this resource when they build solutions on Azure Digital Twins.

终结点摘要Endpoint summary

Swagger 还对编写管理 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 提供的一个强大功能是能够直接通过文档 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. 输入正确的值,并选择“执行” 。Enter the correct values, and select Execute.

已尝试使用 swaggerSwagger 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

若要详细了解如何以交互方式测试受 OAuth 2.0 保护的请求,请参阅官方文档To learn more about interactively testing requests protected by OAuth 2.0, see the official documentation.

备注

创建 Azure 数字孪生资源的用户主体将具有空间管理员角色分配,并将能够创建其他用户的其他角色分配。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.

  1. 按照中的步骤本快速入门创建 Azure AD 应用程序类型的Web 应用 / APIFollow the steps in this quickstart to create an Azure AD application of type Web app / API. 或者,可以重复使用现有的应用注册。Or 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
    
    NameName 替换为Replace with 示例Example
    YOUR_SWAGGER_URLYOUR_SWAGGER_URL 你在门户中找到的管理 REST API 文档 URLYour Management REST API documentation URL found in the portal https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swagger
  3. 授予应用访问 Azure 数字孪生的权限。Grant permissions for your app to access Azure Digital Twins. 在“所需权限”下,输入 Azure Digital Twins 并选择“委托的权限” 。Under Required permissions, enter Azure Digital Twins and select Delegated Permissions. 然后选择“授予权限”。 Then select Grant Permissions.

    Azure AD 应用注册添加 api

  4. 配置为允许 OAuth 2.0 隐式流的应用程序清单。Configure the application manifest to allow OAuth 2.0 implicit flow. 选择清单打开您的应用程序的应用程序清单。Select Manifest to open the application manifest for your app. 将“oauth2AllowImplicitFlow”设置为 trueSet oauth2AllowImplicitFlow to true.

    Azure AD 隐式流

  5. 复制 Azure AD 应用的 ID。Copy the ID of your Azure AD app.

后完成的 Azure Active Directory 注册:After completing the Azure Active Directory registration:

  1. 选择Authorize swagger 页上的按钮。Select the Authorize button on your swagger page.

    选择了在 Swagger 授权按钮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

后续步骤Next steps