通过

你当前正在访问 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。 有关详细信息，请参阅符合性语句的特定版本：

预发布版本

标签为“预发行版”的 API 版本指示版本尚未准备好用于生产，并且它只应在测试环境中使用。 这些终结点可能会遇到中断性变更，但未注意到。

如何递增版本

我们目前仅在出现中断性变更时递增主版本，这被视为不向后兼容。

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

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

非中断性变更（版本未递增）：

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

响应中的标头

ReportApiVersions 处于打开状态，这意味着系统在适当时返回标头 api 支持的版本和 api-deprecated-versions。

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

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

示例：

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

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

注意

DICOM® 是美国电气制造商协会的注册商标，适用于其有关医疗信息数字通信的标准出版物。