你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

DICOM 服务的 API 版本控制

  • 项目

本参考指南概述了 DICOM 服务的 API 版本策略。

在请求中指定 REST API 版本

必须在请求 URL 中显式指定 REST API 的版本，如以下示例所示：

<service_url>/v<version>/studies

注意

不支持没有版本的路由。

支持的版本

当前支持的版本为：

  • v1.0-prerelease
  • v1
  • v2

可在以下 URL 中找到支持版本的 OpenAPI 文档：

<service_url>/v<version>/api.yaml

DICOM 一致性声明

所有版本的 DICOM API 将始终符合 DICOMweb™ 标准规范，但不同的版本可能会公开不同的 API。 有关详细信息，请参阅符合性语句的特定版本：

预发行版本

标签为“prerelease”的 API 版本表示该版本尚未准备好用于生产，并且仅应在测试环境中使用。 这些终结点可能会遇到中断性变更，恕不另行通知。

如何递增版本

目前，我们只在发生中断性变更时递增主版本，这被认为不向后兼容。

下面是一些中断性变更示例（主版本递增）：

  • 重命名或删除终结点。
  • 删除参数或添加必需参数。
  • 更改状态代码。
  • 删除响应中的属性或完全更改响应类型，但可以向响应添加属性。
  • 更改属性的类型。
  • API 更改时的行为，比如业务逻辑变更，过去执行 foo，而现在执行 bar。

版本 (非中断性变更不会) 递增：

  • 添加可为空或具有默认值的属性。
  • 向响应模型添加属性。
  • 更改属性顺序。

响应中的标头

ReportApiVersions 已打开，这意味着我们会在适当时返回标头 api-supported-versions 和 api-deprecated-versions。

  • api-supported-versions 将列出请求的 API 支持的版本。 它仅在调用带有 ApiVersion("<someVersion>") 批注的终结点时返回。

  • api-deprecated-versions 将列出请求的 API 已弃用的版本。 它仅在调用带有 ApiVersion("<someVersion>", Deprecated = true) 批注的终结点时返回。

示例：

[ApiVersion("1")]
[ApiVersion("1.0-prerelease", Deprecated = true)]

API 支持和已弃用版本的屏幕截图。

后续步骤

本文介绍了 DICOM 服务的 API 版本策略。 有关 DICOM 服务的详细信息，请参阅

DICOM 服务概述