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

扩展查询标记

项目
07/26/2023

概述

默认情况下，DICOM 服务支持查询在一致性语句中指定的 DICOM 标记。通过启用扩展查询标记，可以根据应用程序的需求轻松扩展标记列表。

使用下面列出的 API，用户可以在标准和专用 DICOM 标记上为其 DICOM 研究、系列和实例编制索引，以便在 QIDO-RS 查询中指定它们。

API

版本：v1

为了帮助管理给定 DICOM 服务实例中支持的标记，已添加以下 API 终结点。

API	说明
POST .../extendedquerytags	添加扩展查询标记
GET .../extendedquerytags	列出扩展查询标记
GET .../extendedquerytags/{tagPath}	获取扩展查询标记
DELETE .../extendedquerytags/{tagPath}	删除扩展查询标记
PATCH .../extendedquerytags/{tagPath}	更新扩展查询标记
GET .../extendedquerytags/{tagPath}/errors	列出扩展查询标记错误
GET .../operations/{operationId}	获取操作

添加扩展查询标记

添加一个或多个扩展查询标记，并启动一个长时间运行的操作，该操作使用指定的标记 () 重新编制当前 DICOM 实例的索引。

POST .../extendedquerytags

请求头

名称	必选	类型	说明
Content-Type	True	字符串	支持 `application/json`

请求正文

名称	必选	类型	说明
body		用于添加的扩展查询标记`[]`

限制

支持以下 VR 类型：

Vr	说明	单值匹配	范围匹配	模糊匹配
AE	应用程序实体	X
AS	Age 字符串	X
CS	代码字符串	X
DA	Date	X	X
DS	十进制字符串	X
DT	DateTime	X	X
FD	浮点双精度	X
FL	浮点单个	X
IS	整数字符串	X
LO	长字符串	X
PN	个人姓名	X		X
SH	短字符串	X
SL	有符号的 Long	X
SS	有符号的短	X
TM	时间	X	X
UI	唯一标识符	X
UL	无符号 Long	X
US	无符号短	X

注意

顺序标记是类型为“项序列 (SQ) ”的标记，目前不受支持。最多可以添加 128 个扩展查询标记。

响应

名称	类型	说明
202 (已接受)	操作参考	添加了扩展查询标记 () ，并且已启动长时间运行的操作来重新编制现有 DICOM 实例的索引
400（错误的请求）		请求正文包含无效数据
409（冲突）		已支持一个或多个请求的查询标记

列出扩展查询标记

() 的所有扩展查询标记的列表。

GET .../extendedquerytags

响应

名称	类型	说明
200 (正常)	扩展查询标记`[]`	返回扩展查询标记

获取扩展查询标记

获取扩展查询标记。

GET .../extendedquerytags/{tagPath}

URI 参数

名称	在	必需	类型	说明
tagPath	path	True	字符串	tagPath 是标记的路径，可以是标记或关键字 (keyword) 。例如，患者 ID 由 `00100020` 或表示 `PatientId`

响应

名称	类型	说明
200 (正常)	扩展查询标记	具有指定的扩展查询标记 `tagPath`
400（错误的请求）		请求的标记路径无效
404（未找到）		找不到具有所请求 tagPath 的扩展查询标记

删除扩展查询标记

删除扩展查询标记。

DELETE .../extendedquerytags/{tagPath}

URI 参数

名称	在	必需	类型	说明
tagPath	path	True	字符串	tagPath 是标记的路径，可以是标记或关键字 (keyword) 。例如，患者 ID 由 `00100020` 或表示 `PatientId`

响应

名称	类型	说明
204 (无内容)		已成功删除具有所请求 tagPath 的扩展查询标记。
400（错误的请求）		请求的标记路径无效。
404（未找到）		找不到具有所请求 tagPath 的扩展查询标记

更新扩展查询标记

更新扩展查询标记。

PATCH .../extendedquerytags/{tagPath}

URI 参数

名称	在	必需	类型	说明
tagPath	path	True	字符串	tagPath 是标记的路径，可以是标记或关键字 (keyword) 。例如，患者 ID 由 `00100020` 或表示 `PatientId`

请求头

名称	必选	类型	说明
Content-Type	True	字符串	支持 `application/json`。

请求正文

名称	必选	类型	说明
body		用于更新的扩展查询标记

响应

名称	类型	说明
20 (正常)	扩展查询标记	更新的扩展查询标记
400（错误的请求）		请求的标记路径或正文无效
404（未找到）		找不到具有所请求 tagPath 的扩展查询标记

列出扩展查询标记错误

列出扩展查询标记上的错误。

GET .../extendedquerytags/{tagPath}/errors

URI 参数

名称	在	必需	类型	说明
tagPath	path	True	字符串	tagPath 是标记的路径，可以是标记或关键字 (keyword) 。例如，患者 ID 由 `00100020` 或表示 `PatientId`

响应

名称	类型	说明
200 (正常)	扩展查询标记错误`[]`	与标记关联的扩展查询标记错误列表
400（错误的请求）		请求的标记路径无效
404（未找到）		找不到具有所请求 tagPath 的扩展查询标记

获取操作

获取长时间运行的操作。

GET .../operations/{operationId}

URI 参数

名称	在	必需	类型	说明
operationId	path	True	字符串	操作 ID

响应

名称	类型	说明
200 (正常)	操作	指定 ID 的已完成操作
202 (已接受)	操作	指定 ID 的运行操作
404（未找到）		找不到操作

具有扩展查询标记的 QIDO

标记状态

扩展查询标记的状态指示当前状态。首次添加扩展查询标记时，其状态设置为 Adding，并启动长时间运行的操作以重新索引现有 DICOM 实例。操作完成后，标记状态将更新为 Ready。扩展查询标记现在可以在 QIDO 中使用。

例如，如果添加了标记“制造商型号名称” (0008，1090) ，并且处于 Ready 状态，则以后可以使用以下查询按“制造商型号名称”筛选存储的实例。

../instances?ManufacturerModelName=Microsoft

它们还可以与现有标记一起使用。例如：

../instances?00081090=Microsoft&PatientName=Jo&fuzzyMatching=true

标记查询状态

QueryStatus 指示是否允许 QIDO 用于标记。当重新编制索引操作无法处理标记的一个或多个 DICOM 实例时，该标记的 QueryStatus 会自动设置为 Disabled 。可以通过更新扩展查询标记 API 将设置为 QueryStatusEnabled 来选择忽略索引错误并允许查询使用此标记。引用至少一个手动启用的标记的任何 QIDO 请求都将在响应标头 erroneous-dicom-attributes中包含具有索引错误的标记集。

例如，假设扩展查询标记 PatientAge 在重新编制索引期间出错，但它是手动启用的。对于以下查询，你将能够在标头中看到PatientAgeerroneous-dicom-attributes。

../instances?PatientAge=035Y

定义

扩展查询标记

QIDO-RS 将支持的 DICOM 标记。

名称	类型	说明
路径	字符串	标记的路径，通常由组 ID 和元素 ID 组成。例如， `PatientId` (0010，0020) 具有路径00100020
Vr	字符串	此标记的值表示形式
PrivateCreator	字符串	此专用标记的实现者的标识代码
Level	扩展查询标记级别	扩展查询标记的级别
状态	扩展查询标记状态	扩展查询标记的状态
QueryStatus	扩展查询标记查询状态	扩展查询标记的查询状态
错误	扩展查询标记错误参考	对扩展查询标记错误的引用
操作	操作参考	对长时间运行的操作的引用

代码示例 1 是状态 (0008，0070) Ready的标准标记。

{
    "status": "Ready",
    "level": "Instance",
    "queryStatus": "Enabled",
    "path": "00080070",
    "vr": "LO"
}

代码示例 2 是状态 (0010，1010) Adding的标准标记。具有 ID 1a5d0306d9624f699929ee1a59ed57a0 的操作正在其上运行，到目前为止已发生 21 个错误。

{
    "status": "Adding",
    "level": "Study",
    "errors": {
        "count": 21,
        "href": "https://localhost:63838/extendedquerytags/00101010/errors"
    },
    "operation": {
        "id": "1a5d0306d9624f699929ee1a59ed57a0",
        "href": "https://localhost:63838/operations/1a5d0306d9624f699929ee1a59ed57a0"
    },
    "queryStatus": "Disabled",
    "path": "00101010",
    "vr": "AS"
}

操作参考

对长时间运行的操作的引用。

名称	类型	说明
ID	字符串	操作 ID
Href	字符串	操作的 URI

操作

表示长时间运行的操作。

名称	类型	说明
OperationId	string	操作 ID
OperationType	操作类型	长时间运行的操作的类型
CreatedTime	字符串	创建操作的时间
LastUpdatedTime	字符串	上次更新操作的时间
状态	操作状态	表示操作的运行时状态
PercentComplete	Integer	操作已完成的工时百分比
资源	string`[]`	操作正在创建或操作的资源位置的集合

下面的 代码示例 是一个正在运行的重新编制索引操作。

{
    "resources": [
        "https://localhost:63838/extendedquerytags/00101010"
    ],
    "operationId": "a99a8b51-78d4-4fd9-b004-b6c0bcaccf1d",
    "type": "Reindex",
    "createdTime": "2021-10-06T16:40:02.5247083Z",
    "lastUpdatedTime": "2021-10-06T16:40:04.5152934Z",
    "status": "Running",
    "percentComplete": 10
}

操作状态

表示长时间运行的操作的运行时状态。

名称	类型	说明
NotStarted	字符串	操作未启动
正在运行	字符串	操作正在执行，但尚未完成
已完成	字符串	操作已成功完成
失败	字符串	操作在遇到一个或多个错误后过早停止

扩展查询标记错误

扩展查询标记索引操作期间发生的错误。

名称	类型	说明
StudyInstanceUid	string	发生索引错误的研究实例 UID
SeriesInstanceUid	string	发生索引错误的系列实例 UID
SopInstanceUid	string	发生索引错误的 Sop 实例 UID
CreatedTime	字符串	发生错误的时间 (UTC)
ErrorMessage	string	错误消息

下面的 代码示例 包含 DICOM 实例上的意外值长度错误。发生于 2021-10-06T16：41：44.4783136。

{
    "studyInstanceUid": "2.25.253658084841524753870559471415339023884",
    "seriesInstanceUid": "2.25.309809095970466602239093351963447277833",
    "sopInstanceUid": "2.25.225286918605419873651833906117051809629",
    "createdTime": "2021-10-06T16:41:44.4783136",
    "errorMessage": "Value length is not expected."
}

扩展查询标记错误参考

对扩展查询标记错误的引用。

名称	类型	说明
计数	Integer	扩展查询标记上的错误总数
Href	字符串	扩展查询标记错误的 URI

操作类型

长时间运行的操作的类型。

名称	类型	说明
重新编制索引	字符串	基于新标记更新以前添加的数据的索引的重新索引操作

扩展查询标记状态

扩展查询标记的状态。

名称	类型	说明
正在添加	字符串	已添加扩展查询标记，并且长时间运行的操作正在为现有 DICOM 实例重新编制索引
就绪	字符串	扩展查询标记已准备好用于 QIDO-RS
正在删除	字符串	正在删除扩展查询标记

扩展查询标记级别

应用此标记的 DICOM 信息层次结构的级别。

名称	类型	说明
实例	string	扩展查询标记在实例级别相关
系列	字符串	扩展查询标记在序列级别相关
检查	字符串	扩展查询标记在研究级别相关

扩展查询标记查询状态

扩展查询标记的查询状态。

名称	类型	说明
已禁用	字符串	不允许查询扩展查询标记
已启用	字符串	允许查询扩展查询标记

注意

重新编制索引操作期间的错误会禁用扩展查询标记上的 QIDO。可以调用更新扩展查询标记 API 来启用它。

用于更新的扩展查询标记

表示用于更新的扩展查询标记。

名称	类型	说明
QueryStatus	扩展查询标记查询状态	扩展查询标记的查询状态

用于添加的扩展查询标记

表示要添加的扩展查询标记。

名称	必选	类型	说明
路径	True	字符串	标记的路径，通常由组 ID 和元素 ID 组成， `PatientId` (0010，0020) 具有路径00100020
Vr		字符串	此标记的值表示形式。它对于标准标记是可选的，对于专用标记是必需的
PrivateCreator		字符串	此专用标记的实现者的标识代码。仅在标记为专用标记时设置
Level	True	扩展查询标记级别	表示此标记相关的层次结构。应为研究、系列或实例之一

代码示例 1MicrosoftPC 使用实例级别的值表示形式定义私有标记 (0401，1001) SS。

{
    "Path": "04011001",
    "VR": "SS",
    "PrivateCreator": "MicrosoftPC",
    "Level": "Instance"
}

代码示例 2 将标准标记与关键字 (keyword) ManufacturerModelName 与序列级别上定义的值表示形式一起使用LO。

{
    "Path": "ManufacturerModelName",
    "VR": "LO",
    "Level": "Series"
}

代码示例 3 使用标准标记 (0010，0040) ，并在研究中定义。值表示形式已由 DICOM 标准定义。

{
    "Path": "00100040",
    "Level": "Study"
}

总结

此概念性文章概述了 DICOM 服务中的扩展查询标记功能。

后续步骤

有关部署 DICOM 服务的详细信息，请参阅

将 DICOM 服务部署到 Azure

将 DICOMweb™标准 API 与 DICOM 服务配合使用

通过

扩展查询标记

概述

API

版本：v1

添加扩展查询标记

请求头

请求正文

限制

响应

列出扩展查询标记

响应

获取扩展查询标记

URI 参数

响应

删除扩展查询标记

URI 参数

响应

更新扩展查询标记

URI 参数

请求头

请求正文

响应

列出扩展查询标记错误

URI 参数

响应

获取操作

URI 参数

响应

具有扩展查询标记的 QIDO

标记状态

标记查询状态

定义

扩展查询标记

操作参考

操作

操作状态

扩展查询标记错误

扩展查询标记错误参考

操作类型

扩展查询标记状态

扩展查询标记级别

扩展查询标记查询状态

用于更新的扩展查询标记

用于添加的扩展查询标记

总结

后续步骤

反馈

其他资源