DICOM 一致性声明

Cloud Healthcare API 中的 DICOM 存储区支持 DICOM PS3.18 - Web 服务标准（通常称为 DICOMweb）中指定的一部分 RESTful Web 服务。具体来说，它们支持研究服务和资源（以前称为 WADA-RS、STOW-RS 和 QDO-RS 服务）。

此外，Cloud Healthcare API 还支持用于删除 DICOM 实例的专有 Web 服务。

Cloud Healthcare API 不支持 URI 服务、Worklist 服务、非患者实例服务或任何功能事务。

检索事务

检索事务是用于检索 DICOM 影像数据的 RESTful Web 服务。

“检索事务”功能支持检索以下资源：

  • DICOM 资源：
    • 研究
    • 系列
    • 实例
    • 框架
    • 批量数据
  • 元数据资源
    • 研究
    • 系列
    • 实例
  • 呈现的资源
    • 实例
    • 框架

它不支持缩略图资源。

如需详细了解这些方法的配额和限制，请参阅配额和限制。

DICOM 研究/系列/实例

支持以下 Accept 标头：

  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.1（默认）
  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.4.50
  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.4.90
  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.4.91
  • multipart/related; type="application/dicom"; transfer-syntax=*

DICOM 实例

为方便起见，除了上述 Accept 标头之外，RetrieveInstance 还支持单个部件的内容类型：

  • application/dicom; transfer-syntax=1.2.840.10008.1.2.1
  • application/dicom; transfer-syntax=1.2.840.10008.1.2.4.50
  • application/dicom; transfer-syntax=1.2.840.10008.1.2.4.90
  • application/dicom; transfer-syntax=1.2.840.10008.1.2.4.91
  • application/dicom; transfer-syntax=*

它不是官方 DICOMweb 标准的一部分。

DICOM 框架

支持以下 Accept 标头：

  • multipart/related; type="application/octet-stream"; transfer-syntax=1.2.840.10008.1.2.1（默认）
  • multipart/related; type="application/octet-stream"; transfer-syntax=*
  • multipart/related; type="image/jpeg"; transfer-syntax=1.2.840.10008.1.2.4.50
  • multipart/related; type="image/png"

* 的传输语法允许用户请求不进行转码，因此将会使用已上传文件的传输语法。对于 application/octet-stream，批量数据将采用其在上传的 DICOM 文件中所显示的格式返回。

呈现的资源

支持以下 Accept 标头：

  • image/jpeg（默认）
  • image/png

仅支持检索实例或框架资源。

除了视口之外，不支持任何其他网址参数。

元数据资源

支持以下 Accept 标头：

  • application/dicom+json（默认）
  • multipart/related; type=application/dicom+xml

编码为 InlineBinary 元素的标记将使用小端字节顺序进行编码，因为请求元数据资源的端点不支持传输语法参数。

默认情况下，RetrieveMetadata 不会返回使用 DICOM 值表示形式来表示 OB、OW 或 UN 的任何属性。如需针对与预览版 Bulkdata 定义匹配的标记返回 BulkDataURI，请使用 Preview version。

元数据资源不会返回包含超过约 1 MiB 数据的 DICOM 序列标记。此限制仅适用于元数据资源。DICOM 资源仍将包含这些标记。

批量数据资源（预览版）

支持以下 Accept 标头：

  • multipart/related; type="application/octet-stream"; transfer-syntax=*（默认）
  • application/octet-stream; transfer-syntax=*

转码支持的传输语法

上面的 Accept 标头介绍了您可以从 API 请求的媒体类型和传输语法，但根据上传的原始文件的传输语法，您不一定能请求。具体而言，只能通过以下传输语法进行转码：

  • 1.2.840.10008.1.2（隐式小端字节序）
  • 1.2.840.10008.1.2.1（显式小端字节序）
  • 1.2.840.10008.1.2.2（显式 VR 大端字节序）
  • 1.2.840.10008.1.2.4.50（JPEG 基准进程 1）
  • 1.2.840.10008.1.2.4.57（JPEG 无损格式）
  • 1.2.840.10008.1.2.4.70（JPEG 无损格式选择值 1）
  • 1.2.840.10008.1.2.4.90（仅限 JPEG 2000 无损格式）
  • 1.2.840.10008.1.2.4.91 (JPEG 2000)
  • 1.2.840.10008.1.2.5（RLE 无损格式）

如果原始文件的传输语法不是上述列表中的语法，而您请求转码为其他格式，则系统会返回错误。

Cloud Healthcare API 无法将位深大于 8 的非单色图像转码为 JPEG。此外，如果图片的“分配的位数”(0028, 0100) 值为 1，或者存储在“浮点像素数据”(7FE0,0008)、“双浮点像素数据”(7FE0,0009) 标记中，则只能在原生格式之间进行转码。

要停用转码功能并从 API 中检索任何文件，您可以在 Accept 标头中设置 transfer-syntax=*。

状态代码

代码 含义
200 (OK) 响应载荷包含所有目标资源的表示形式。
400 (Bad Request) 对指定目标资源（例如缺少像素数据）的请求无效（例如查询参数或标头错误）。
401 (Unauthorized) 请求缺少身份验证凭据。
403 (Permission Denied) 已通过身份验证的用户无权访问此资源（或该资源不存在）。
406 (Not Acceptable) 服务器不支持任何可接受的媒体类型。
429 (Too Many Requests) 客户端超出了其配额。
503 (Service Unavailable) 服务器当前不可用或请求已超出其截止日期。

存储事务

存储事务是用于存储 DICOM 影像数据的 RESTful Web 服务。

存储事务可以直接接受第 10 部分 DICOM 二进制文件，也可以接受将 DICOM 文件拆分为元数据（以 JSON 表示）和批量数据。这两个版本具有不同的语义，以下各部分进行了介绍。

如需详细了解此方法的配额和限制，请参阅配额和限制。

DICOM 第 10 部分二进制文件

支持的 Content-Type 如下：

  • multipart/related; type=application/dicom
  • application/dicom

服务器不会强制转换或替换属性。

此版本接受所有传输语法类和 SOP 类。提取某些关键元数据属性时，仅对 DICOM 文件进行最小程度的验证。

请注意，为方便起见，“存储事务”还接受内容类型为 application/dicom 的单个 DICOM 实例的单部分 HTTP 请求。它不是官方 DICOMweb 标准的一部分。

如需查看关联的方法指南，请参阅存储 DICOM 实例。

JSON 元数据和批量数据请求

使用 JSON 元数据和批量数据存储实例时，第一个多部分部分必须包含 DICOM 实例的 JSON 数组。

第一部分的 Content-Type 必须为 application/dicom+json; transfer-syntax=TransferSyntaxUID，其中 TransferSyntaxUID 是对 InlineBinary 对象中的二进制数据进行编码时所用的传输语法。如果元数据中没有 InlineBinary 对象，则可以省略 transfer-syntax 参数。

JSON 元数据中的每个实例中都必须存在以下 DICOM 元素：

  • SpecificCharacterSet
  • TransferSyntaxUID
  • SOPClassUID
  • StudyInstanceUID
  • SeriesInstanceUID
  • SOPInstanceUID

SpecificCharacterSet 元素必须设置为 ISO_IR 192，而 JSON 元数据必须采用 Unicode UTF-8 编码。TransferSyntaxUID 可以设置为任何有效的传输语法，但以下不支持的传输语法除外：

  • 1.2.840.10008.1.2.2（显式 VR 大端字节序）
  • 1.2.840.10008.1.2.1.99（使用 Deflate 压缩过的显式 VR 小端字节序）

在 JSON 元数据中，用户可以为 OB、OW 或 UN 的 DICOM 标记（具有 VR）指定多个 BulkDataURI。这些 BulkDataURI 表示包含 URI 的代码的二进制数据将在接下来的部分中发送，该部分将 Content-Location 标头设置为 BulkDataURI。

JSON 元数据中的每个实例最多只能有一个 BulkDataURI。JSON 元数据中不得有任何重复的 BulkDataURI。压缩映像批量数据只能针对 PixelData 标记发送，发送时，批量数据部分中指定的传输语法必须与实例的 TransferSyntaxUID 元素值匹配。

批量数据部分支持以下 Content-Type：

  • application/octet-stream
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.4.70
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.4.50
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.​4.​51
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.​4.​57
  • image/x-dicom-rle; transfer-syntax=1.2.840.10008.1.2.5
  • image/x-jls; transfer-syntax=1.2.840.10008.1.2.​4.​80
  • image/x-jls; transfer-syntax=1.2.840.10008.1.2.4.81
  • image/jp2; transfer-syntax=1.2.840.10008.1.2.4.90
  • image/jp2; transfer-syntax=1.2.840.10008.1.2.4.91
  • image/jpx; transfer-syntax=1.2.840.10008.1.2.4.92
  • image/jpx; transfer-syntax=1.2.840.10008.1.2.4.93

另一种指定二进制数据的方法是将数据编码为 InlineBinary base64 编码字符串。除 PixelData 之外的所有标记都支持使用此方法，PixelData 必须作为批量数据的一部分发送。在 JSON 元数据中使用 InlineBinary 对象时，必须在 JSON 元数据部分的 Content-Type 中指定用于编码的传输语法。

服务器不会派生图片像素说明宏属性。

如需查看关联的方法指南，请参阅从 JSON 元数据和 JPEG 文件创建 DICOM 实例。

响应

发生错误时，将额外返回一个 FailureDetail (0009, 0097) 标记（用于 XML 响应）或 FailureDetailJSON (0009,1097) 标记（用于 JSON 响应）。FailureDetail 标记提供直观易懂的错误说明。

如果 DICOM 实例与 DICOM 存储区中已有的另一个实例具有相同的 <StudyInstanceUID, SeriesInstanceUID, SOPInstanceUID> 元组，则系统会返回正在处理故障错误，并附带一个“already exists”FailureDetail 标记。

响应采用 JSON 还是 XML 格式，可以通过以下 Accept 标头值进行控制：

  • application/dicom+xml（默认）
  • application/dicom+json

状态代码

代码 含义
200 (OK) 资源已成功存储。
400 (Bad Request) 请求无效（例如，媒体类型或传输语法不受支持）。
401 (Unauthorized) 请求缺少身份验证凭据。
403 (Permission Denied) 已通过身份验证的用户无权访问此资源（或该资源不存在）。
406 (Not Acceptable) 服务器不支持任何可接受的媒体类型。
409 (Conflict) 至少有一项资源未成功存储（例如，DICOM 文件无效）。如需了解详情，请查看响应正文中的 FailureDetail 标记。
429 (Too Many Requests) 客户端超出了其配额。
503 (Service Unavailable) 服务器当前不可用或请求已超出其截止日期。

搜索事务

检索事务是用于查询 DICOM 影像元数据的 RESTful Web 服务。

Cloud Healthcare API 支持搜索研究、系列和实例。

搜索参数

支持按以下标记进行搜索：

  • 研究：
    • StudyInstanceUID
    • PatientName
    • PatientID
    • AccessionNumber
    • ReferringPhysicianName
    • StudyDate
  • 系列：所有研究级别的搜索字词和
    • SeriesInstanceUID
    • 模态
  • 实例：所有研究/系列级别的搜索字词和
    • SOPInstanceUID

仅支持单值完全匹配，但 StudyDate 和 PatientName 除外，它们分别支持范围查询和模糊匹配。

支持下列其他网址参数：

  • fuzzymatching：如果设置为 true，则模糊匹配将应用于 PatientName 标记。“模糊匹配”将对查询中的 PatientName 值和存储的值执行令牌化和标准化。匹配的前提是任何搜索令牌是任何存储的令牌的前缀。例如，如果 PatientName 是“John^Doe”，则“jo”、“Do”和“John Doe”全部匹配。但 “ohn”不匹配。
  • includefield：可以设置为以英文逗号分隔的属性 ID（如 DICOM 标记 ID 或关键字）的列表，也可以设置为 all 值以返回所有可用标记。如需查看可用标记的列表，请参阅返回的结果。

支持使用 limit 和 offset 查询参数进行分页。如果没有提供更多结果，则没有警告响应标头。您必须执行额外查询才能确定是否有更多结果。

  • limit：对于研究/系列和实例，应返回的结果数上限分别是 5000 个和 50000 个。研究/系列和实例的默认结果数分别为 100 个和 1000 个。

  • offset：开始时跳过的结果数最多为 1000000 个。

不支持 UTC 时区偏移量。

返回的结果

响应采用 JSON 还是 XML 格式，可以使用以下 Accept 标头值进行控制：

  • application/dicom+json（默认）
  • multipart/related; type=application/dicom+xml

默认情况下，将返回以下属性：

  • 研究：
    • SpecificCharacterSet
    • StudyDate
    • StudyTime
    • AccessionNumber
    • InstanceAvailability
    • ReferringPhysicianName
    • TimezoneOffsetFromUTC
    • PatientName
    • PatientID
    • PatientBirthDate
    • PatientSex
    • StudyInstanceUID
    • StudyID
  • 系列：
    • SpecificCharacterSet
    • 模态
    • TimezoneOffsetFromUTC
    • SeriesDescription
    • SeriesInstanceUID
    • PerformedProcedureStepStartDate
    • PerformedProcedureStepStartTime
    • RequestAttributesSequence
  • 实例：
    • SpecificCharacterSet
    • SOPClassUID
    • SOPInstanceUID
    • InstanceAvailability
    • TimezoneOffsetFromUTC
    • InstanceNumber
    • 行数
    • 列数
    • BitsAllocated
    • NumberOfFrames

对于 includefield=all，默认属性将与以下属性一起返回：

  • 研究：
    • PersonIdentificationCodeSequence
    • PersonAddress
    • PersonTelephoneNumbers
    • PersonTelecomInformation
    • InstitutionName
    • InstitutionAddress
    • InstitutionCodeSequence
    • ReferringPhysicianIdentificationSequence
    • ConsultingPhysicianName
    • ConsultingPhysicianIdentificationSequence
    • IssuerOfAccessionNumberSequence
    • LocalNamespaceEntityID
    • UniversalEntityID
    • UniversalEntityIDType
    • StudyDescription
    • PhysiciansOfRecord
    • PhysiciansOfRecordIdentificationSequence
    • NameOfPhysiciansReadingStudy
    • PhysiciansReadingStudyIdentificationSequence
    • RequestingServiceCodeSequence
    • ReferencedStudySequence
    • ProcedureCodeSequence
    • ReasonForPerformedProcedureCodeSequence
  • 系列：
    • SeriesNumber
    • 偏侧性
    • SeriesDate
    • SeriesTime
  • 实例：DICOM 实例中存在的所有属性，但不包括以下例外情况。

默认情况下，searchForInstances 不会返回使用 DICOM 值表示形式来表示 OB、OW 或 UN 的任何属性。如需针对与预览版Bulkdata 定义匹配的标记返回 BulkDataURI，请使用预览版 searchForInstances。

元数据响应中不会返回含有 1 MiB 左右的数据的 DICOM 序列标记。

元数据不一致/无效

对于 SearchForStudies/SearchForSeries，多个实例中可能存在不一致的研究/系列级别元数据。例如，可以上传两个 StudyInstanceUID 相同但 StudyDates 不同的实例。在这种情况下，搜索行为没有明确定义。在某些情况下，可以按照该值进行搜索，但在其他情况下，返回的值可能因各个调用不同而异。

状态代码

代码 含义
200 (OK) 响应载荷包含所有目标资源的表示形式。
400 (Bad Request) 请求无效（例如查询参数无效）。
401 (Unauthorized) 请求缺少身份验证凭据。
403 (Permission Denied) 已通过身份验证的用户无权访问此资源（或该资源不存在）。
406 (Not Acceptable) 服务器不支持任何可接受的媒体类型。
429 (Too Many Requests) 客户端超出了其配额。
503 (Service Unavailable) 服务器当前不可用或请求已超出其截止日期。

删除

Cloud Healthcare API 支持以下专有操作类型：

  • DeleteStudy
  • DeleteSeries
  • DeleteInstance

它们使用的请求路径与其 WADA-RS 副本的请求路径相同（副本分别为 RetrieveStudy、RetrieveSeries 和 RetrieveInstance）。系统会使用 DELETE 请求，而不是 HTTP GET 请求。其结果是指定的研究、系列或实例以及其中包含的所有 DICOM 资源都会被删除。

DeleteStudy 和 DeleteSeries 方法将返回一个长时间运行的操作，该操作会删除研究或系列中的所有实例。请注意，在操作完成之前，实例无法插入到正在被操作删除的研究或系列中。

有关操作的方法指南，请参阅管理长时间运行的操作。

成功的 DeleteInstance 请求将返回空响应。

状态代码

代码 含义
200 (OK) 请求资源已被删除。
400 (Bad Request) 请求无效。
401 (Unauthorized) 请求缺少身份验证凭据。
403 (Permission Denied) 已通过身份验证的用户无权访问此资源（或该资源不存在）。
429 (Too Many Requests) 客户端超出了其配额。
503 (Service Unavailable) 服务器当前不可用或请求已超出其截止日期。

Accept 标头

上述某些方法可让您使用 HTTP Accept 标头控制响应格式。顶级级别（如 */*）和子类型（如 image/*）均支持通配符匹配。还支持通过指定 q 值来指示相关偏好设置。如果未针对 Accept 标头指定 q 值，则它会设置为默认值 1.0。

如果指定了多个 Accept 标头，并且最爱的 Accept 标头之间存在关联，则服务器将选择 Accept 标头。在这种情况下，客户端不应依赖服务器是否选择 Accept 标头。

支持的 SOP 类

Cloud Healthcare API 可以提取所有 DICOM SOP 类并对其执行基本检索。对于需要在图片格式之间进行转码的任何检索，请参阅转码支持的传输语法以查看受支持的传输语法列表。

DICOM 字典版本

Cloud Healthcare API 使用 DICOM 2025b 字典来解析提取的实例的标记，并在导出到 BigQuery 时生成列名称。

Bulkdata 代码定义（预览版）

使用预览方法检索元数据时，Cloud Healthcare API 会排除定义为“bulkdata”的某些标记。相反，这些代码将与包含 BulkDataURI 的元数据一起返回，以便用户检索这些代码的内容（请参阅 RetrieveBulkdata）。以下是 Cloud Healthcare API 使用的定义：

  • 任何像素数据标记：(7FE0,0008)、(7FE0,0009)、(7FE0,0010)。
  • 任何 VR 为 OB、OW 或 UN 的标记。
  • 标记的 VR 为 OD、OF、OL 或 OV，且大于 2 KiB。
    • 出于旧版原因，如果已提取到 Cloud Healthcare API 的实例的标记大于 256 B (OF 和 OL) 或 512 B (OD)，则可能会被视为批量数据。
  • 代码为 AT、FD、FL、UL、US、SV 或 UV 且值多重性 (VM) 大于 512 的代码。
    • 出于旧版原因，如果虚拟机大于 64 个，已提取到 Cloud Healthcare API 的实例的标记可能会被视为批量数据。

此外，以下标记被视为批量数据，但从元数据方法返回时没有 BulkDataURI，并且无法使用 RetrieveBulkdata 检索内容：

  • VR 为 SQ 且大小超过大约 1 MiB 的标记。