擴充查詢標籤

發行項
05/14/2024

根據預設，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

要求標頭

名稱	必要	類型	描述
內容-類型	True	string	支援`application/json`

要求本文

名稱	必要	類型	描述
本文		用於新增的擴充查詢標籤`[]`

限制

目前支援下列 VR 類型：

VR	描述	單一值比對	範圍比對	模糊比對
阿拉伯聯合大公國	應用程式實體	X
AS	年齡字串	X
CS	代碼字串	X
DA	Date	X	X
DS	十進位字串	X
DT	日期時間	X	X
FD	雙精度浮點數	X
FL	單精度浮點數	X
IS	整數字串	X
LO	長字串	X
PN	人員名稱	X		X
SH	短字串	X
SL	帶正負號的長整數	X
SS	帶正負號的短整數	X
TM	Time	X	X
UI	唯一識別碼	X
UL	未帶正負號的長整數	X
美國	未帶正負號的短整數	X

注意

目前不支援循序標籤，即項目序列 (SQ) 類型標籤下方的標籤。您最多可以新增 128 個擴充查詢標籤。如果值為 Null 或空白，我們就不會為擴充查詢標籤編製索引。

回覆

名稱	類型	描述
202 (已接受)	作業參考	擴充查詢標籤已新增，而且已啟動長時間執行的作業來為現有的 DICOM 執行個體重新編製索引
400 (錯誤的要求)		要求本文的資料無效
409 (衝突)		已支援一或多個要求的查詢標籤

列出擴充查詢標籤

所有擴充查詢標籤的清單。

GET .../extendedquerytags

回覆

名稱	類型	描述
200 (確定)	擴充查詢標籤`[]`	傳回擴充查詢標籤

取得擴充查詢標籤

取得擴充查詢標籤。

GET .../extendedquerytags/{tagPath}

URI 參數

名稱	位於	必要	類型	描述
tagPath	path	True	string	tagPath 是標籤的路徑，可以是標籤或關鍵字。例如，病患識別碼是由 `00100020` 或 `PatientId` 來表示

回覆

名稱	類型	描述
200 (確定)	擴充查詢標籤	具有指定 `tagPath` 的擴充查詢標籤
400 (錯誤的要求)		要求的標籤路徑無效
404 (找不到)		找不到具有所要求 tagPath 的擴充查詢標籤

刪除擴充查詢標籤

刪除擴充查詢標籤。

DELETE .../extendedquerytags/{tagPath}

URI 參數

名稱	位於	必要	類型	描述
tagPath	path	True	string	tagPath 是標籤的路徑，可以是標籤或關鍵字。例如，病患識別碼是由 `00100020` 或 `PatientId` 來表示

回覆

名稱	類型	描述
204 (沒有內容)		已成功刪除具有所要求 tagPath 的擴充查詢標籤。
400 (錯誤的要求)		要求的標籤路徑無效。
404 (找不到)		找不到具有所要求 tagPath 的擴充查詢標籤

更新擴充查詢標籤

更新擴充查詢標籤。

PATCH .../extendedquerytags/{tagPath}

URI 參數

名稱	位於	必要	類型	描述
tagPath	path	True	string	tagPath 是標籤的路徑，可以是標籤或關鍵字。例如，病患識別碼是由 `00100020` 或 `PatientId` 來表示

要求標頭

名稱	必要	類型	描述
內容-類型	True	string	支援 `application/json`。

要求本文

名稱	必要	類型	描述
本文		用於更新的擴充查詢標籤

回覆

名稱	類型	描述
20 (確定)	擴充查詢標籤	已更新的擴充查詢標籤
400 (錯誤的要求)		要求的標籤路徑或本文無效
404 (找不到)		找不到具有所要求 tagPath 的擴充查詢標籤

列出擴充查詢標籤錯誤

列出擴充查詢標籤上的錯誤。

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

URI 參數

名稱	位於	必要	類型	描述
tagPath	path	True	string	tagPath 是標籤的路徑，可以是標籤或關鍵字。例如，病患識別碼是由 `00100020` 或 `PatientId` 來表示

回覆

名稱	類型	描述
200 (確定)	擴充查詢標籤錯誤`[]`	與標籤相關聯的擴充查詢標籤錯誤清單
400 (錯誤的要求)		要求的標籤路徑無效
404 (找不到)		找不到具有所要求 tagPath 的擴充查詢標籤

取得作業

取得長時間執行的作業。

GET .../operations/{operationId}

URI 參數

名稱	位於	必要	類型	描述
operationId	path	True	string	作業識別碼

回覆

名稱	類型	描述
200 (確定)	運算	已針對指定識別碼完成的作業
202 (已接受)	運算	針對指定識別碼執行的作業
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，將 QueryStatus 設定為 Enabled，從而選擇忽略編製索引錯誤並允許查詢使用此標籤。所有至少參考一個手動啟用標籤的 QIDO 要求，都將在回應標頭 erroneous-dicom-attributes 中包含一組具有編製索引錯誤的標籤。

例如，假設擴充查詢標籤 PatientAge 在重新編製索引期間發生錯誤，但已手動啟用。針對下列查詢，您可能會在 erroneous-dicom-attributes 標頭中看到 PatientAge。

../instances?PatientAge=035Y

定義

擴充查詢標籤

QIDO-RS 將支援的 DICOM 標籤。

名稱	類型	描述
路徑	string	標籤的路徑，通常由群組識別碼和元素識別碼所組成。例如，`PatientId` (0010,0020) 具有路徑 00100020
VR	string	此標籤的值表示法
PrivateCreator	string	此私人標籤實作者的識別碼
層級	擴充查詢標籤層級	擴充查詢標籤層級
狀態	擴充查詢標籤狀態	擴充查詢標籤的狀態
QueryStatus	擴充查詢標籤查詢狀態	擴充查詢標籤的查詢狀態
錯誤	擴充查詢標籤錯誤參考	參考擴充查詢標籤錯誤
作業	作業參考	參考長時間執行的作業

程式碼範例 1 是處於 Ready 狀態的標準標籤 (0008,0070)。

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

程式碼範例 2 是處於 Adding 狀態的標準標籤 (0010,1010)。識別碼為 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"
}

作業參考

參考長時間執行的作業。

名稱	類型	描述
識別碼	string	作業識別碼
Href	string	作業的 URI

作業

表示長時間執行的作業。

名稱	類型	描述
OperationId	string	作業識別碼
OperationType	作業類型	長時間執行作業的類型
CreatedTime	string	建立作業的時間
LastUpdatedTime	string	上次更新作業的時間
狀態	作業狀態	表示作業的執行階段狀態
PercentComplete	整數	作業已完成的工作百分比
資源	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
}

作業狀態

表示長時間執行作業的執行階段狀態。

名稱	類型	描述
未開始	string	作業未啟動
執行中	string	作業正在執行，但尚未完成
已完成	string	作業已順利完成
失敗	string	作業在發生一或多個錯誤之後提早停止

擴充查詢標籤錯誤

在擴充查詢標籤編製索引作業期間發生的錯誤。

名稱	類型	描述
StudyInstanceUid	string	發生編製索引錯誤的研究執行個體 UID
SeriesInstanceUid	string	發生編製索引錯誤的序列執行個體 UID
SopInstanceUid	string	發生編製索引錯誤的 Sop 執行個體 UID
CreatedTime	string	錯誤發生時間 (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."
}

擴充查詢標籤錯誤參考

參考擴充查詢標籤錯誤。

名稱	類型	描述
計數	整數	擴充查詢標籤上的錯誤總數
Href	string	擴充查詢標籤錯誤的 URI

作業類型

長時間執行作業的類型。

名稱	類型	描述
重新編製索引	string	重新編製索引作業，會根據新標籤更新先前所新增資料的索引

擴充查詢標籤狀態

擴充查詢標籤的狀態。

名稱	類型	描述
新增中	string	擴充查詢標籤已新增，而且長時間執行的作業正在為現有的 DICOM 執行個體重新編製索引
就緒	string	擴充查詢標籤已可供 QIDO-RS 使用
刪除中	string	正在刪除擴充查詢標籤

擴充查詢標籤層級

套用此標籤之 DICOM 資訊階層的層級。

名稱	類型	描述
執行個體	string	擴充查詢標籤會與執行個體層級相關
數列	string	擴充查詢標籤會與序列層級相關
研究	string	擴充查詢標籤會與研究層級相關

擴充查詢標籤查詢狀態

擴充查詢標籤的查詢狀態。

名稱	類型	描述
停用	string	不允許查詢擴充查詢標籤
已啟用	string	允許查詢擴充查詢標籤

注意

重新編製索引作業期間的錯誤會停用擴充查詢標籤上的 QIDO。您可以呼叫更新擴充查詢標籤 API 來啟用它。

用於更新的擴充查詢標籤

表示用於更新的擴充查詢標籤。

名稱	類型	描述
QueryStatus	擴充查詢標籤查詢狀態	擴充查詢標籤的查詢狀態

用於新增的擴充查詢標籤

表示用於新增的擴充查詢標籤。

名稱	必要	類型	描述
路徑	True	string	標籤的路徑，通常由群組識別碼和元素識別碼所組成，其中 `PatientId` (0010,0020) 具有路徑 00100020
VR		string	此標籤的值表示法。這是標準標籤的選擇性項目，但為私人標籤的必要項目
PrivateCreator		string	此私人標籤實作者的識別碼。只有在標籤是私人標籤時才會設定
層級	True	擴充查詢標籤層級	表示與此標籤相關的階層。應該是研究、序列或執行個體之一

程式碼範例 1MicrosoftPC 正在執行個體層級上，定義具有 SS 值表示法的私人標籤 (0401,1001)。

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

程式碼範例 2 會使用標準標籤搭配關鍵字 ManufacturerModelName，以及序列層級上定義的 LO 值表示法。

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

程式碼範例 3 會使用標準標籤 (0010,0040)，並定義於研究上。值表示法已經由 DICOM 標準所定義。

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

摘要

此概念性文章可為您提供 DICOM 服務內擴充查詢標籤功能的概觀。

下一步

將 DICOM 服務部署到 Azure

搭配 DICOM 服務使用 DICOMweb API

注意

DICOM® \(英文\) 是美國電氣製造商協會對於其與醫療資訊數位通訊相關的標準出版物的註冊商標。

共用方式為

擴充查詢標籤

API

版本：v1

新增擴充查詢標籤

要求標頭

要求本文

限制

回覆

列出擴充查詢標籤

回覆

取得擴充查詢標籤

URI 參數

回覆

刪除擴充查詢標籤

URI 參數

回覆

更新擴充查詢標籤

URI 參數

要求標頭

要求本文

回覆

列出擴充查詢標籤錯誤

URI 參數

回覆

取得作業

URI 參數

回覆

具有擴充查詢標籤的 QIDO

標籤狀態

標籤查詢狀態

定義

擴充查詢標籤

作業參考

作業

作業狀態

擴充查詢標籤錯誤

擴充查詢標籤錯誤參考

作業類型

擴充查詢標籤狀態

擴充查詢標籤層級

擴充查詢標籤查詢狀態

用於更新的擴充查詢標籤

用於新增的擴充查詢標籤

摘要

下一步

意見反應

其他資源