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

将 DICOMweb 标准 API 与 cURL 配合使用

项目
04/17/2024

本文介绍如何通过使用 cURL 和示例 .dcm DICOM® 文件来使用 DICOMweb 服务。

使用以下示例文件：

blue-circle.dcm
dicom-metadata.csv
green-square.dcm
red-triangle.dcm

示例 DICOM 文件的文件名、studyUID、seriesUID 和 instanceUID 为：

文件	StudyUID	SeriesUID	InstanceUID
green-square.dcm	1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420	1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652	1.2.826.0.1.3680043.8.498.12714725698140337137334606354172323212
red-triangle.dcm	1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420	1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652	1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395
blue-circle.dcm	1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420	1.2.826.0.1.3680043.8.498.77033797676425927098669402985243398207	1.2.826.0.1.3680043.8.498.13273713909719068980354078852867170114

注意

这些文件中的每一个都代表一个实例，并且是同一研究的一部分。此外，绿色正方形和红色三角形属于同一系列，而蓝色圆形属于单独的系列。

先决条件

若要使用 DICOM 标准 API，必须部署 DICOM 服务实例。有关详细信息，请参阅使用 Azure 门户部署 DICOM 服务。

部署 DICOM 服务实例后，检索应用服务的 URL。

登录到 Azure 门户。
搜索“最近的资源”并选择你的 DICOM 服务实例。
复制 DICOM 服务的服务 URL。
如果需要访问令牌，请参阅获取 DICOM 服务的访问令牌。

对于此代码，我们访问公共预览版 Azure 服务。请务必不要上传任何私人健康信息 (PHI)。

使用 DICOM 服务

DICOMweb 标准大量使用 multipart/related HTTP 请求（结合特定于 DICOM 的接受标头）。熟悉其他基于 REST 的 API 的开发人员在使用 DICOMweb 标准时往往会感到不便。但是，在启动并运行后，它易于使用。只需稍加熟悉就能开始使用。

每个 cURL 命令至少包含一个（有时是两个）必须替换的变量。为了简化命令的运行，请搜索并替换以下变量，将其替换为你的特定值。

{Service URL} 服务 URL 是用于访问在 Azure 门户中预配的 DICOM 服务的 URL，例如 https://<workspacename-dicomservicename>.dicom.azurehealthcareapis.com。在发出请求时，请确保将版本指定为 URL 的一部分。有关详细信息，请参阅 DICOM 服务的 API 版本控制文档。
{path-to-dicoms} - 包含 red-triangle.dcm 文件的目录路径，例如 C:/dicom-server/docs/dcms
- 请确保使用正斜杠作为分隔符，并且不在目录的末尾使用尾随正斜杠。

上传 DICOM 实例 (STOW)

使用 multipart/related 存储实例

此请求旨在演示如何使用 multipart/related 上传 DICOM 文件。

注意

DICOM 服务比 DICOM 标准更宽松。但是，本示例演示的 POST 请求完全符合该标准。

详细信息：

Path：../studies
方法：POST
标头：
- Accept：application/dicom+json
- Content-Type：multipart/related；type="application/dicom"
- Authorization：持有者令牌 {token value}
正文：
- Content-Type：上传的每个文件的 application/dicom，用边界值分隔

某些编程语言和工具的行为有所不同。例如，有些语言和工具要求定义自己的边界。对于这些工具，可能需要使用稍作修改的 Content-Type 标头。可以成功使用以下工具。

Content-Type：multipart/related；type="application/dicom"; boundary=ABCD1234
Content-Type：multipart/related；boundary=ABCD1234
Content-Type：multipart/related

curl --location --request POST "{Service URL}/v{version}/studies"
--header "Accept: application/dicom+json"
--header "Content-Type: multipart/related; type=\"application/dicom\""
--header "Authorization: Bearer {token value}"
--form "file1=@{path-to-dicoms}/red-triangle.dcm;type=application/dicom"
--trace-ascii "trace.txt"

存储特定研究的实例

此请求演示如何使用 multipart/related 将 DICOM 文件上传到指定研究。

详细信息：

Path：../studies/{study}
方法：POST
标头：
- Accept：application/dicom+json
- Content-Type：multipart/related；type="application/dicom"
- Authorization：持有者令牌 {token value}
正文：
- Content-Type：上传的每个文件的 application/dicom，用边界值分隔

某些编程语言和工具的行为有所不同。例如，有些语言和工具要求定义自己的边界。对于这些语言和工具，可能需要使用稍作修改的 Content-Type 标头。可以成功使用以下工具。

Content-Type：multipart/related；type="application/dicom"; boundary=ABCD1234
Content-Type：multipart/related；boundary=ABCD1234
Content-Type：multipart/related

curl --request POST "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420"
--header "Accept: application/dicom+json"
--header "Content-Type: multipart/related; type=\"application/dicom\""
--header "Authorization: Bearer {token value}"
--form "file1=@{path-to-dicoms}/blue-circle.dcm;type=application/dicom"

Store-single-instance

注意

这是一个非标准 API，允许上传单个 DICOM 文件，而无需为 multipart/related 配置 POST。尽管 cURL 可以很好地处理 multipart/related，但此 API 允许 Postman 等工具将文件上传到 DICOM 服务。

上传单个 DICOM 文件需要以下方法。

详细信息：

Path：../studies
方法：POST
标头：
- Accept：application/dicom+json
- Content-Type：application/dicom
- Authorization：持有者令牌 {token value}
正文：
- 包含单个 DICOM 文件作为二进制字节。

curl --location --request POST "{Service URL}/v{version}/studies"
--header "Accept: application/dicom+json"
--header "Content-Type: application/dicom"
--header "Authorization: Bearer {token value}"
--data-binary "@{path-to-dicoms}/green-square.dcm"

使用 multipart/related 更新插入实例

注意

这是一个非标准 API，支持使用 multipart/related 更新插入 DICOM 文件。

详细信息：

Path：../studies
方法：PUT
标头：
- Accept：application/dicom+json
- Content-Type：multipart/related；type="application/dicom"
- Authorization：持有者令牌 {token value}
正文：
- Content-Type：上传的每个文件的 application/dicom，用边界值分隔

Content-Type：multipart/related；type="application/dicom"; boundary=ABCD1234
Content-Type：multipart/related；boundary=ABCD1234
Content-Type：multipart/related

curl --location --request PUT "{Service URL}/v{version}/studies"
--header "Accept: application/dicom+json"
--header "Content-Type: multipart/related; type=\"application/dicom\""
--header "Authorization: Bearer {token value}"
--form "file1=@{path-to-dicoms}/red-triangle.dcm;type=application/dicom"
--trace-ascii "trace.txt"

更新插入特定研究的实例

注意

这是一个非标准 API，支持使用 multipart/related 将 DICOM 文件更新插入到指定研究。

详细信息：

Path：../studies/{study}
方法：PUT
标头：
- Accept：application/dicom+json
- Content-Type：multipart/related；type="application/dicom"
- Authorization：持有者令牌 {token value}
正文：
- Content-Type：上传的每个文件的 application/dicom，用边界值分隔

Content-Type：multipart/related；type="application/dicom"; boundary=ABCD1234
Content-Type：multipart/related；boundary=ABCD1234
Content-Type：multipart/related

curl --request PUT "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420"
--header "Accept: application/dicom+json"
--header "Content-Type: multipart/related; type=\"application/dicom\""
--header "Authorization: Bearer {token value}"
--form "file1=@{path-to-dicoms}/blue-circle.dcm;type=application/dicom"

更新插入单个实例

注意

这是一个非标准 API，支持更新插入单个 DICOM 文件。

使用此方法可上传单个 DICOM 文件。

详细信息：

Path：../studies
方法：PUT
标头：
- Accept：application/dicom+json
- Content-Type：application/dicom
- Authorization：持有者令牌 {token value}
正文：
- 包含单个 DICOM 文件作为二进制字节。

curl --location --request PUT "{Service URL}/v{version}/studies"
--header "Accept: application/dicom+json"
--header "Content-Type: application/dicom"
--header "Authorization: Bearer {token value}"
--data-binary "@{path-to-dicoms}/green-square.dcm"

检索 DICOM (WADO)

检索研究中的所有实例

此请求检索单个研究中的所有实例，并将其作为 multipart/related 字节的集合返回。

详细信息：

Path：../studies/{study}
方法：GET
标头：
- Accept：multipart/related；type="application/dicom"; transfer-syntax=*
- Authorization：持有者令牌 {token value}

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420"
--header "Accept: multipart/related; type=\"application/dicom\"; transfer-syntax=*"
--header "Authorization: Bearer {token value}"
--output "suppressWarnings.txt"

此 cURL 命令显示输出文件 (suppressWarnings.txt) 中下载的字节，但它们不是直接 DICOM 文件，而只是 multipart/related 下载的文本表示形式。

检索研究中所有实例的元数据

此请求检索单个研究中所有实例的元数据。

详细信息：

Path：../studies/{study}/metadata
方法：GET
标头：
- Accept：application/dicom+json
- Authorization：持有者令牌 {token value}

此 cURL 命令显示输出文件 (suppressWarnings.txt) 中下载的字节，但它们不是直接 DICOM 文件，而只是 multipart/related 下载的文本表示形式。

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/metadata"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

检索系列中的所有实例

此请求检索单个系列中的所有实例，并将其作为 multipart/related 字节的集合返回。

详细信息：

Path：../studies/{study}/series/{series}
方法：GET
标头：
- Accept：multipart/related；type="application/dicom"; transfer-syntax=*
- Authorization：持有者令牌 {token value}

此 cURL 命令显示输出文件 (suppressWarnings.txt) 中下载的字节，但该文件不是直接 DICOM 文件，而只是 multipart/related 下载的文本表示形式。

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652"
--header "Accept: multipart/related; type=\"application/dicom\"; transfer-syntax=*"
--header "Authorization: Bearer {token value}"
--output "suppressWarnings.txt"

检索系列中所有实例的元数据

此请求检索单个研究中所有实例的元数据。

详细信息：

Path：../studies/{study}/series/{series}/metadata
方法：GET
标头：
- Accept：application/dicom+json
- Authorization：持有者令牌 {token value}

curl --request GET "{Service URL}/v{version}/studies1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/metadata"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

检索一系列研究中的单个实例

此请求检索单个实例，并将其作为 DICOM 格式的字节流返回。

详细信息：

Path：../studies/{study}/series{series}/instances/{instance}
方法：GET
标头：
- Accept：application/dicom；transfer-syntax=*
- Authorization：持有者令牌 {token value}

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/instances/1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395"
--header "Accept: application/dicom; transfer-syntax=*"
--header "Authorization: Bearer {token value}"
--output "suppressWarnings.txt"

检索一系列研究中的单个实例的元数据

此请求检索单个研究和系列中单个实例的元数据。

详细信息：

Path：../studies/{study}/series/{series}/instances/{instance}/metadata
方法：GET
标头：
- Accept：application/dicom+json
- Authorization：持有者令牌 {token value}

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/instances/1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395/metadata"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

从单个实例中检索一个或多个帧

此请求检索单个实例中的一个或多个帧，并将其作为 multipart/related 字节的集合返回。可以通过传递以逗号分隔的帧编号列表来检索多个帧。具有图像的所有 DICOM 实例至少具有一个帧，通常只是与实例本身关联的图像。

详细信息：

Path：../studies/{study}/series{series}/instances/{instance}/frames/1,2,3
方法：GET
标头：
- Accept：multipart/related；type="application/octet-stream"；transfer-syntax=1.2.840.10008.1.2.1 (Default) or
- Accept：multipart/related；type="application/octet-stream"；transfer-syntax=* 或
- Accept：multipart/related；type="application/octet-stream"；
- Authorization：持有者令牌 {token value}

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/instances/1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395/frames/1"
--header "Accept: multipart/related; type=\"application/octet-stream\"; transfer-syntax=1.2.840.10008.1.2.1"
--header "Authorization: Bearer {token value}"
--output "suppressWarnings.txt"