Azure 数字孪生 Swagger 参考文档
每个预配的 Azure 数字孪生实例都包含自己生成的 Swagger 参考文档。
Swagger 或 OpenAPI 将复杂的 API 信息整合到一个交互式和语言无关的参考资源中。 Swagger 提供有关要使用哪些 JSON 有效负载、HTTP 方法和特定终结点对 API 执行操作的关键参考资料。
Swagger 摘要
Swagger 提供 API 的交互式摘要，这包括：
- API 和对象模型信息。
- REST API 终结点，用于指定必需的请求有效负载、标头、参数、上下文路径和 HTTP 方法。
- API 功能测试。
- 示例响应信息，用于验证和确认 HTTP 响应。
- 错误代码信息。
Swagger 是一种非常便利的工具，可用于帮助执行对 Azure 数字孪生管理 API 作出的开发和测试调用。
提示
我们提供了 Swagger 非公开预览版来演示 API 功能集。 它托管在 docs.westcentralus.azuresmartspaces.net/management/swagger 中。
可以在以下位置访问你自己的已生成管理 API Swagger 文档：
https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger
| 名称 | 替换为 |
|---|---|
| YOUR_INSTANCE_NAME | Azure 数字孪生实例的名称 |
| YOUR_LOCATION | 托管实例的服务器区域 |
参考资料
自动生成的 Swagger 参考资料提供了重要概念的快速概述、可用的管理 API 终结点和每个对象模型的描述，用于帮助开发和测试。
精简摘要对 API 进行了描述。
还列出了管理 API 对象模型。
可以选择每个列出的对象模型来获取关键属性的更详细摘要：
生成的 Swagger 对象模型便于读取所有可用的 Azure 数字孪生 对象和 API。 开发人员在 Azure 数字孪生上生成解决方案时可以使用此资源。
终结点摘要
Swagger 还对编写管理 API 的所有终结点提供了全面概述。
每个列出的终结点还包括所需的请求信息，例如：
- 必需的参数。
- 必需的参数数据类型。
- 用于访问资源的 HTTP 方法。
选择每个资源以显示其附加内容，以获取更详细的概述。
使用 Swagger 测试终结点
Swagger 提供的一个强大功能是能够直接通过文档 UI 测试 API 终结点。
选择特定终结点后，将显示 “试用” 按钮。
展开该部分会显示每个必需字段和可选参数的输入字段。 输入正确的值，并选择“执行”。
执行测试后，可以验证响应数据。
Swagger 响应数据
每个列出的终结点还包括用以验证开发和测试的响应正文数据。 这些示例包括成功 HTTP 请求的状态代码和 JSON。
这些示例还包括用以帮助调试或改进失败测试的错误代码。
Swagger OAuth 2.0 授权
注意
- 创建 Azure 数字孪生资源的用户主体将具有空间管理员角色分配，并且可以为其他用户创建其他角色分配。 这些用户及其角色可以授权调用 API。
按照 快速入门 中的步骤创建和配置 Azure Active Directory 应用程序。 或者，可以重复使用现有的应用注册。
将以下 重定向 URI 添加到 Azure Active Directory 应用注册：
https://YOUR_SWAGGER_URL/ui/oauth2-redirect-html名称 替换为 示例 YOUR_SWAGGER_URL 在门户中找到的管理 REST API 文档 URL https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swagger选中 “隐式授予>访问令牌 ”复选框，允许使用 OAuth 2.0 隐式授权流。 选择“ 配置”，然后选择 “保存”。
复制 Azure Active Directory 应用的 客户端 ID 。
完成 Azure Active Directory 注册后：
选择 Swagger 页面上的 “授权 ”按钮。
将应用程序 ID 粘贴到 client_id 字段中。
然后，你将重定向到以下成功模式。
若要详细了解如何以交互方式测试受 OAuth 2.0 保护的请求，请阅读 官方文档。
后续步骤
若要阅读有关 Azure 数字孪生对象模型和空间智能图的详细信息，请阅读了解 Azure 数字孪生对象模型。
若要了解如何使用管理 API 进行身份验证，请阅读使用 API 进行身份验证。