共用方式為

DICOM 一致性語句 v1

  • 發行項

注意

API 第 2 版是最新的 API 版本，應該用來取代 v1。 如需詳細資訊， 請參閱 DICOM 一致性語句 v2 。

適用於 DICOM® 的醫學映射伺服器支援 DICOMweb Standard 的子集。 支援包括：

此外，支援下列非標準 API：

服務會使用 REST API 版本控制。 REST API 的版本必須明確指定為基底 URL 的一部分，如下列範例所示：

https://<service_url>/v<version>/studies

這個版本的一致性語句會對應至 v1 REST API 的版本。

如需如何在提出要求時指定版本的資訊，請參閱 API 版本控制檔。

您可以在 Postman 集合中找到支援交易的範例要求。

Preamble Sanitization

服務會忽略 128 位元組的檔案前置詞，並以 Null 字元取代其內容。 此行為可確保沒有透過服務傳遞的 檔案容易受到惡意前置弱點的攻擊。 不過，這個前置詞清理也表示 用來編碼雙重格式內容的 前置詞，例如 TIFF 無法與服務搭配使用。

研究服務

研究服務可讓用戶儲存、擷取和搜尋 DICOM 研究、系列和實例。 我們新增了非標準 Delete 交易，以啟用完整的資源生命週期。

商店 （STOW-RS）

此交易會使用 POST 或 PUT 方法來儲存要求承載中包含的研究、數列和實例表示法。

方法 路徑 描述
POST ../研究 儲存實例。
POST ../studys/{study} 儲存特定研究的實例。
PUT ../研究 Upsert 實例。
PUT ../studys/{study} 特定研究的Upsert實例。

參數 study 會對應至 DICOM 屬性 StudyInstanceUID。 如果指定，任何不屬於所提供研究的實例，就會使用 43265 警告碼來拒絕。

支援回應的下列 Accept 標頭：

  • application/dicom+json

支援下列 Content-Type 標頭：

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

注意

伺服器不會強制或取代與 POST 要求現有資料衝突的屬性。 所有數據都會儲存為提供。 對於 upsert （PUT） 要求，現有數據會由收到的新數據取代。

儲存必要的屬性

試著儲存的每個 DICOM 檔案中都必須有下列 DICOM 元素：

  • StudyInstanceUID
  • SeriesInstanceUID
  • SOPInstanceUID
  • SOPClassUID
  • PatientID

注意

所有 UID 長度必須介於 1 到 64 個字元之間，且只包含英數位元或下列特殊字元： .、 -。 PatientID會根據其LOVR類型進行驗證。

每個儲存的檔案都必須有、 SeriesInstanceUID和 SopInstanceUID的唯一組合StudyInstanceUID。 如果具有相同標識碼的檔案已經存在，則會傳回警告碼 45070 。

只接受具有明確值表示法的傳輸語法。

儲存回應狀態代碼

代碼 描述
200 (OK) 要求中的所有 SOP 實例都會儲存。
202 (Accepted) 要求中的某些實例會儲存，但其他實例失敗。
204 (No Content) 存放區交易要求中未提供任何內容。
400 (Bad Request) 要求的格式不正確。 例如，提供的學習實例標識碼不符合預期的 UID 格式。
401 (Unauthorized) 用戶端未通過驗證。
403 (Forbidden) 使用者未獲授權。
406 (Not Acceptable) 不支援指定的 Accept 標頭。
409 (Conflict) 存放區交易要求中的實例都未儲存。
415 (Unsupported Media Type) 不支援提供的 Content-Type 。
503 (Service Unavailable) 服務無法使用或忙碌中。 請稍後再試一次。

儲存響應承載

響應承載會以下列元素填入 DICOM 數據集。

標籤 名稱 描述
(0008, 1190) RetrieveURL 研究的擷取 URL，如果在 StudyInstanceUID 存放區要求中提供 ，且至少成功儲存一個實例
(0008, 1198) FailedSOPSequence 無法儲存的實例序列
(0008, 1199) ReferencedSOPSequence 預存實例的順序

中的每個 FailedSOPSequence 數據集都有下列元素（如果可以讀取嘗試儲存的 DICOM 檔案）。

標籤 名稱 描述
(0008, 1150) ReferencedSOPClassUID 無法儲存之實例的SOP類別唯一標識碼
(0008, 1155) ReferencedSOPInstanceUID 無法儲存之實例的 SOP 實例唯一標識碼
(0008, 1197) FailureReason 此實例無法儲存的原因代碼
(0074, 1048) FailedAttributesSequence 的序列 ErrorComment ，其中包含每個失敗屬性的原因

中的每個 ReferencedSOPSequence 數據集都有下列元素。

標籤 名稱 描述
(0008, 1150) ReferencedSOPClassUID 無法儲存之實例的SOP類別唯一標識碼
(0008, 1155) ReferencedSOPInstanceUID 無法儲存之實例的 SOP 實例唯一標識碼
(0008, 1190) RetrieveURL DICOM 伺服器上這個實例的擷取 URL

標頭為 的Acceptapplication/dicom+json範例回應：

{
  "00081190":
  {
    "vr":"UR",
    "Value":["http://localhost/studies/d09e8215-e1e1-4c7a-8496-b4f6641ed232"]
  },
  "00081198":
  {
    "vr":"SQ",
    "Value":
    [{
      "00081150":
      {
        "vr":"UI","Value":["cd70f89a-05bc-4dab-b6b8-1f3d2fcafeec"]
      },
      "00081155":
      {
        "vr":"UI",
        "Value":["22c35d16-11ce-43fa-8f86-90ceed6cf4e7"]
      },
      "00081197":
      {
        "vr":"US",
        "Value":[43265]
      }
    }]
  },
  "00081199":
  {
    "vr":"SQ",
    "Value":
    [{
      "00081150":
      {
        "vr":"UI",
        "Value":["d246deb5-18c8-4336-a591-aeb6f8596664"]
      },
      "00081155":
      {
        "vr":"UI",
        "Value":["4a858cbb-a71f-4c01-b9b5-85f88b031365"]
      },
      "00081190":
      {
        "vr":"UR",
        "Value":["http://localhost/studies/d09e8215-e1e1-4c7a-8496-b4f6641ed232/series/8c4915f5-cc54-4e50-aa1f-9b06f6e58485/instances/4a858cbb-a71f-4c01-b9b5-85f88b031365"]
      }
    }]
  }
}

存放區失敗原因碼

代碼 描述
272 由於處理作業時發生一般失敗，存放區交易並未儲存 實例。
43264 DICOM 實例驗證失敗。
43265 提供的實體 StudyInstanceUID 不符合 StudyInstanceUID 存放區要求中指定的 。
45070 具有相同、 SeriesInstanceUID和 SopInstanceUID 的 StudyInstanceUIDDICOM 實例已經儲存。 如果您想要更新內容，請先刪除此實例。
45071 DICOM 實例是由另一個進程所建立，或先前嘗試建立失敗且清除程式未完成。 先刪除實例，然後再嘗試再次建立。

儲存警告原因碼

代碼 描述
45063 DICOM 實例數據集不符合 SOP 類別。 研究存放區交易（第 10.5 節）觀察到數據集在實例儲存期間不符合 SOP 類別的條件約束。

儲存錯誤碼

代碼 描述
100 提供的實例屬性不符合驗證準則。

擷取 （WADO-RS）

此擷取交易提供依參考方式擷取預存研究、數列、實例和框架的支援。

方法 路徑 描述
GET ../studys/{study} 擷取研究中的所有實例
GET ../studys/{study}/metadata 擷取研究內所有實例的元數據
GET ../studys/{study}/series/{series} 擷取數列中的所有實例
GET ../studys/{study}/series/{series}/metadata 擷取數列中所有實例的元數據
GET ../studys/{study}/series/{series}/instances/{instance} 擷取單一實例
GET ../studys/{study}/series/{series}/instances/{instance}/metadata 擷取單一實例的元數據
GET ../studys/{study}/series/{series}/instances/{instance}/rendered 擷取轉譯成影像格式的實例
GET ../studys/{study}/series/{series}/instances/{instance}/frames/{frames} 從單一實例擷取一或多個畫面格;若要指定多個框架，請使用逗號分隔每個框架來傳回。 例如： /studies/1/series/2/instance/3/frames/4,5,6 。
GET ../studys/{study}/series/{series}/instances/{instance}/frames/{frame}/rendered 擷取轉譯成影像格式的單一畫面

擷取研究或數列內的實例

支援下列 Accept 標頭來擷取研究或數列內的實例。

  • multipart/related; type="application/dicom"; transfer-syntax=*
  • 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.1
  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.4.90
  • */* （未指定 transfer-syntax 時， * 會當做預設值使用，且 mediaType 預設為 application/dicom）

擷取實例

擷取特定實例支援下列 Accept 標頭：

  • application/dicom; transfer-syntax=*
  • multipart/related; type="application/dicom"; transfer-syntax=*
  • application/dicom; （未指定傳輸語法時， 1.2.840.10008.1.2.1 會當做預設值使用）
  • multipart/related; type="application/dicom" （未指定傳輸語法時， 1.2.840.10008.1.2.1 會當做預設值使用）
  • application/dicom; transfer-syntax=1.2.840.10008.1.2.1
  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.1
  • 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.90
  • */* （未指定 transfer-syntax 時， * 會當做預設值使用，且 mediaType 預設為 application/dicom）

擷取

擷取畫面格支援下列 Accept 標頭。

  • multipart/related; type="application/octet-stream"; transfer-syntax=*
  • multipart/related; type="application/octet-stream"; （未指定傳輸語法時， 1.2.840.10008.1.2.1 會當做預設值使用）
  • multipart/related; type="application/octet-stream"; transfer-syntax=1.2.840.10008.1.2.1
  • multipart/related; type="image/jp2"; （未指定傳輸語法時， 1.2.840.10008.1.2.4.90 會當做預設值使用）
  • multipart/related; type="image/jp2";transfer-syntax=1.2.840.10008.1.2.4.90
  • */* （未指定 transfer-syntax 時， * 會當做預設值使用，且 mediaType 預設為 application/octet-stream）

擷取傳輸語法

當要求的傳輸語法與源檔不同時，源檔會轉碼為要求的傳輸語法。 源文件必須是下列其中一種格式，轉碼才能成功，否則轉碼可能會失敗。

  • 1.2.840.10008.1.2 （小尾隱含）
  • 1.2.840.10008.1.2.1 （小尾明確）
  • 1.2.840.10008.1.2.2 （明確 VR Big Endian）
  • 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 無損失）

不支援 transfer-syntax 的結果為 406 Not Acceptable。

擷取元數據（適用於研究、數列或實例）

支援下列 Accept 標頭來擷取研究、數列或實例的元數據。

  • application/dicom+json

擷取元數據不會傳回具有下列值表示的屬性。

VR 名稱 描述
OB 其他位元組
OD 其他雙精度浮點數
OF 其他浮點數
OL 其他 Long
O 其他64位非常長
OW 其他 Word
UN Unknown

擷取元數據快取驗證（適用於研究、數列或實例）

使用 ETag 機制支援快取驗證。 在元數據要求的回應中，ETag 會以其中一個標頭傳回。 此 ETag 可以快取並新增為 If-None-Match 相同元數據的後續要求中的標頭。 如果數據存在，可能會有兩種類型的回應：

  • 自上一個要求之後的數據不會變更： HTTP 304 (Not Modified) 回應會傳送，且沒有回應本文。
  • 自從上次要求之後，數據已變更： HTTP 200 (OK) 回應會以更新的 ETag 傳送。 必要數據也會傳回為本文的一部分。

擷取轉譯的影像（例如或框架）

支援下列 Accept 標頭來擷取實例或框架的轉譯影像。

  • image/jpeg
  • image/png

如果沒有 Accept 指定標頭，服務預設會 image/jpeg 轉譯 。

服務僅支持轉譯單一框架。 如果針對具有多個畫面格的實例要求轉譯，則預設只會將第一個畫面轉譯為影像。

指定要傳回的特定畫面格時，畫面索引會從 1 開始。

quality也支援查詢參數。 從 1 到 100 內含的整數值（1 是最差的品質，而 100 是最佳品質）可能會傳遞為查詢參數的值。 此參數用於轉譯為 jpeg的影像，而且會忽略轉 png 譯要求。 如果未指定，參數會預設為 100。

擷取回應狀態代碼

代碼 描述
200 (OK) 已擷取所有要求的數據。
304 (Not Modified) 自上次要求之後，要求的數據尚未修改。 在此情況下，內容不會新增至回應本文。 如需詳細資訊，請參閱上一節擷取元數據快取驗證（適用於研究、數列或實例）。
400 (Bad Request) 要求的格式不正確。 例如，所提供的研究實例標識碼不符合預期的 UID 格式，或不支援要求的傳輸語法編碼。
401 (Unauthorized) 用戶端未通過驗證。
403 (Forbidden) 使用者未獲授權。
404 (Not Found) 找不到指定的 DICOM 資源，或針對轉譯的要求，實例未包含像素數據。
406 (Not Acceptable) 不支援指定的 Accept 標頭，或針對轉譯和轉碼要求所要求的檔案太大。
503 (Service Unavailable) 服務無法使用或忙碌中。 請稍後再試一次。

搜尋 （QIDO-RS）

根據 DICOM 對象的識別碼進行查詢（QIDO）可讓您依屬性搜尋研究、系列和實例。

方法 路徑 描述
搜尋研究
GET ../研究?。。。 搜尋研究
搜尋數列
GET ../系列?。。。 搜尋系列
GET ../studys/{study}/series?... 在研究中搜尋數列
搜尋實例
GET ../實例?。。。 搜尋執行個體
GET ../studys/{study}/instances?... 在研究中搜尋實例
GET ../studys/{study}/series/{series}/instances?... 搜尋數列中的實例

支援下列 Accept 標頭進行搜尋：

  • application/dicom+json

支援的搜尋參數

支援每個查詢的下列參數。

機碼 支援值 允許的計數 描述
{attributeID}= {value} 0...N 在查詢中搜尋屬性/值比對
includefield= {attributeID}
all		 0...N 回應中要傳回的其他屬性;同時支援公用和私人標籤。
提供 時 all 。 如需每個查詢類型傳回哪些屬性的詳細資訊，請參閱搜尋回應。
如果與混合{attributeID}all提供伺服器預設會使用 all。
limit= {value} 0..1 整數值，以限制回應中傳回的值數目;
值的範圍可以是介於 1 >= x <= 200 之間，預設值為 100。
offset= {value} 0..1 略過 {value} 結果;
如果提供的位移大於搜尋查詢結果的數目， 204 (no content) 則會傳回回應。
fuzzymatching= true / false 0..1 如果將 true 模糊比對套用至 PatientName 屬性;它會在 PatientName 值內執行任何名稱部分的前置詞比對。 例如，如果 PatientName 是 “John^Doe”，則 “joh”、“do”、“jo do”、“Doe” 和 “John Doe” 全都相符。 然而，“ohn”不相符。

可搜尋的屬性

我們支援搜尋下列屬性和搜尋類型。

Attribute 關鍵詞 所有研究 所有數列 所有實例 研究系列 研究的實例 研究系列實例
StudyInstanceUID X X X
PatientName X X X
PatientID X X X
PatientBirthDate X X X
AccessionNumber X X X
ReferringPhysicianName X X X
StudyDate X X X
StudyDescription X X X
ModalitiesInStudy X X X
SeriesInstanceUID X X X X
Modality X X X X
PerformedProcedureStepStartDate X X X X
ManufacturerModelName X X X X
SOPInstanceUID X X X

搜尋比對

我們支援下列比對類型。

搜尋類型 支援的屬性 範例
範圍查詢 StudyDate/PatientBirthDate {attributeID}={value1}-{value2}. 對於日期/時間值，我們支援標籤上的內含範圍，其對應至 attributeID >= {value1} AND attributeID <= {value2}。 如果未 {value1} 指定，則會比對之前和包含 {value2} 的所有日期/時間。 同樣地，如果未 {value2} 指定，則會比對所有出現的 {value1} 和後續日期/時間。 不過，其中一個值必須存在。 {attributeID}={value1}- 但是，和 {attributeID}=-{value2} 是有效的， {attributeID}=- 是無效的。
完全相符 所有支持的屬性 {attributeID}={value1}
模糊比對 PatientName, ReferringPhysicianName 比對以 值開頭之名稱的任何元件。

屬性標識碼

標記可以透過數種方式編碼查詢參數。 我們已部分實作 PS3.18 6.7.1.1.1 中所定義的標準。 支援標記的下列編碼方式。

值 範例
{group}{element} 0020000D
{dicomKeyword} StudyInstanceUID

以下是搜尋實例的範例查詢：

../instances?Modality=CT&00280011=512&includefield=00280010&limit=5&offset=0

搜尋回應

回應是 DICOM 數據集的陣列。 根據資源而定， 預設 會傳回下列屬性。

默認研究標籤

標籤 屬性名稱
(0008, 0005) SpecificCharacterSet
(0008, 0020) StudyDate
(0008, 0030) StudyTime
(0008, 0050) AccessionNumber
(0008, 0056) InstanceAvailability
(0008, 0090) ReferringPhysicianName
(0008, 0201) TimezoneOffsetFromUTC
(0010, 0010) PatientName
(0010, 0020) PatientID
(0010, 0030) PatientBirthDate
(0010, 0040) PatientSex
(0020, 0010) StudyID
（0020,000D） StudyInstanceUID

默認數列標籤

標籤 屬性名稱
(0008, 0005) SpecificCharacterSet
(0008, 0060) Modality
(0008, 0201) TimezoneOffsetFromUTC
（0008,103E） SeriesDescription
（0020,000E） SeriesInstanceUID
(0040, 0244) PerformedProcedureStepStartDate
(0040, 0245) PerformedProcedureStepStartTime
(0040, 0275) RequestAttributesSequence

默認實例標籤

標籤 屬性名稱
(0008, 0005) SpecificCharacterSet
(0008, 0016) SOPClassUID
(0008, 0018) SOPInstanceUID
(0008, 0056) InstanceAvailability
(0008, 0201) TimezoneOffsetFromUTC
(0020, 0013) InstanceNumber
(0028, 0010) Rows
(0028, 0011) Columns
(0028, 0100) BitsAllocated
(0028, 0008) NumberOfFrames

如果 includefield=all為 ，則包含下列屬性以及預設屬性。 除了預設屬性，這是每個資源層級支援的屬性完整清單。

額外的研究標籤

標籤 屬性名稱
(0008, 1030) Study Description
(0008, 0063) AnatomicRegionsInStudyCodeSequence
(0008, 1032) ProcedureCodeSequence
(0008, 1060) NameOfPhysiciansReadingStudy
(0008, 1080) AdmittingDiagnosesDescription
(0008, 1110) ReferencedStudySequence
(0010, 1010) PatientAge
(0010, 1020) PatientSize
(0010, 1030) PatientWeight
(0010, 2180) Occupation
（0010,21B0） AdditionalPatientHistory

其他數列標籤

標籤 屬性名稱
(0020, 0011) SeriesNumber
(0020, 0060) Laterality
(0008, 0021) SeriesDate
(0008, 0031) SeriesTime

會傳回下列屬性：

  • 資源 URL 中的所有相符查詢參數和 UID。
  • IncludeField 該資源層級支持的屬性。
  • 如果目標資源為 All Series，則 Study 也會傳回層級屬性。
  • 如果目標資源為 All Instances，則會 Study 傳回層級 Series 屬性。
  • 如果目標資源為 Study's Instances，則 Series 也會傳回層級屬性。
  • NumberOfStudyRelatedInstances層級 includeField支持Study匯總屬性。
  • NumberOfSeriesRelatedInstances層級 includeField支持Series匯總屬性。

搜尋回應碼

查詢 API 會在回應中傳回下列其中一個狀態代碼。

代碼 描述
200 (OK) 響應承載包含所有相符的資源。
204 (No Content) 搜尋已順利完成，但未傳回任何結果。
400 (Bad Request) 伺服器無法執行查詢，因為查詢元件無效。 回應本文包含失敗的詳細數據。
401 (Unauthorized) 用戶端未通過驗證。
403 (Forbidden) 使用者未獲授權。
503 (Service Unavailable) 服務無法使用或忙碌中。 請稍後再試一次。

訂單備註

  • 不支援使用 TimezoneOffsetFromUTC (00080201) 進行查詢。
  • 查詢 API 不會傳回 413 (request entity too large)。 如果要求的查詢回應限制超出可接受的範圍，則會傳回不正確的要求。 可接受範圍內要求的任何專案都已解決。
  • 當目標資源是研究/數列時，可能會跨多個實例產生不一致的研究/數列層級元數據。 例如，兩個實例可能有不同的 patientName。 在此情況下，最新的勝利，而且您只能搜尋最新的數據。
  • 已優化分頁結果以先傳回相符 的最新 實例，如果已新增符合查詢的較新數據，這可能會導致後續頁面中的記錄重複。
  • 比對 不 區分大小寫， 對 PN VR 類型不 區分腔調字。
  • 比對不區分大小寫，而且對其他字串 VR 類型區分腔調字。
  • 如果單一值數據元素的多個值不正確，則只會編製第一個值的索引。

刪除

此交易不屬於官方 DICOMwe 標準。 它會使用 DELETE 方法，從存放區中移除研究、數列和實例的表示法。

方法 路徑 描述
DELETE ../studys/{study} 刪除特定研究的所有實例
DELETE ../studys/{study}/series/{series} 刪除研究內特定數列的所有實例
DELETE ../studys/{study}/series/{series}/instances/{instance} 刪除數列內的特定實例

、 與參數study分別對應至、 和 SopInstanceUID 的 DICOM 屬性StudyInstanceUIDSeriesInstanceUID。 seriesinstance

要求 Accept 標頭、 Content-Type 標頭或本文內容沒有任何限制。

注意

刪除交易之後，已刪除的實例將無法復原。

回應狀態代碼

代碼 描述
204 (No Content) 刪除所有 SOP 實例時
400 (Bad Request) 要求的格式不正確
401 (Unauthorized) 用戶端未通過驗證
403 (Forbidden) 使用者未獲授權
404 (Not Found) 在研究中找不到指定的數列，或在數列中找不到指定的實例時
503 (Service Unavailable) 服務無法使用或忙碌中。 請稍後再試一次。

刪除響應承載

回應本文是空的。 狀態代碼是唯一傳回的實用資訊。

Worklist Service （UPS-RS）

DICOM 服務支援 Worklist Service (UPS-RS) 的推送和提取 SOP。 Worklist 服務提供一個 Worklist 的存取權，其中包含 Workitems，每個工作清單都代表統一程式步驟（UPS）。

在整個過程中，URI 範本中的變數 {workitem} 代表 Workitem UID。

可用的 UPS-RS 端點包括：

動詞命令 路徑 描述
POST {s}/workitems{？AffectedSOPInstanceUID} 建立工作項目
POST {s}/workitems/{instance}{？transaction} 更新工作項目
GET {s}/workitems{？query*} 搜尋工作項目
GET {s}/workitems/{instance} 擷取工作專案
PUT {s}/workitems/{instance}/state 變更工作項目狀態
POST {s}/workitems/{instance}/cancelrequest 取消工作專案
POST {s}/workitems/{instance}/subscribers/{AETitle}{？deletionlock} 建立訂用帳戶
POST {s}/workitems/1.2.840.10008.5.1.4.34.5/ 暫停訂閱
DELETE {s}/workitems/{instance}/subscribers/{AETitle} 刪除訂閱
GET {s}/subscribers/{AETitle} 開啟訂用帳戶通道

建立 Workitem

此交易會使用 POST 方法來建立新的 Workitem。

方法 路徑 描述
POST ../workitems 建立 Workitem
POST ../workitems？{workitem} 使用指定的 UID 建立 Workitem。

如果未在 URI 中指定，承載資料集必須包含 屬性中的 SOPInstanceUID Workitem。

要求 Accept 中需要和 Content-Type 標頭，而且兩者都必須有 值 application/dicom+json。

特定交易的內容中有數個與 DICOM 數據屬性相關的需求。 屬性可能需要存在、必須不存在、必須是空白，或非空白。 您可以在此表格中找到這些需求。

注意

雖然參考數據表指出不應該存在 SOP 實例 UID，但本指南專屬於 DIMSE 通訊協定，而且會在 DICOMWeb 中以不同的方式處理。 如果不在 URI 中，SOP 實例 UID 應該會出現在數據集中。

注意

包括 1C 和 2C 的所有條件式需求代碼都會被視為選擇性。

建立回應狀態代碼

代碼 描述
201 (Created) 已成功建立目標 Workitem。
400 (Bad Request) 要求發生問題。 例如，要求承載不符合需求。
401 (Unauthorized) 用戶端未通過驗證。
403 (Forbidden) 使用者未獲授權。
409 (Conflict) Workitem 已經存在。
415 (Unsupported Media Type) 不支援提供的 Content-Type 。
503 (Service Unavailable) 服務無法使用或忙碌中。 請稍後再試一次。

建立響應承載

成功回應沒有承載。 Location和 Content-Location 回應標頭包含所建立 Workitem 的 URI 參考。

失敗回應承載包含描述失敗的訊息。

要求取消

此交易可讓使用者要求取消非擁有的 Workitem。

有四個 有效的 Workitem 狀態。

  • SCHEDULED
  • IN PROGRESS
  • CANCELED
  • COMPLETED

此交易只會針對處於 狀態的 SCHEDULED Workitems 成功。 任何使用者都可以藉由將 Workitem 的交易 UID 設定為 ，並將其狀態變更為 IN PROGRESS來宣告 Workitem 的擁有權。 從此為止，使用者只能藉由提供正確的交易 UID 來修改 Workitem。 雖然 UPS 會定義 Watch 和 Event SOP 類別，以允許轉送取消要求和其他事件，但此 DICOM 服務不會實作這些類別，因此在傳回失敗的工作專案 IN PROGRESS 上，取消要求。 您可以透過 變更 Workitem 狀態 交易來取消擁有的 Workitem。

方法 路徑 描述
POST ../workitems/{workitem}/cancelrequest 要求取消排程的 Workitem

標頭 Content-Type 是必要的，而且必須有 值 application/dicom+json。

要求承載可能包含 DICOM 標準中所定義的動作資訊。

要求取消響應狀態代碼

代碼 描述
202 (Accepted) 伺服器已接受要求，但 Target Workitem 狀態不變。
400 (Bad Request) 要求語法發生問題。
401 (Unauthorized) 用戶端未通過驗證。
403 (Forbidden) 使用者未獲授權。
404 (Not Found) 找不到 Target Workitem。
409 (Conflict) 要求與 Target Workitem 的目前狀態不一致。 例如，Target Workitem 處於 SCHEDULED 或 COMPLETED 狀態。
415 (Unsupported Media Type) 不支援提供的 Content-Type 。

要求取消響應承載

成功回應沒有承載，而失敗響應承載則包含描述失敗的訊息。 如果 Workitem 實體已經處於已取消狀態，回應會包含下列 HTTP 警告標頭： 299: The UPS is already in the requested state of CANCELED.

擷取 Workitem

此交易會擷取 Workitem。 它會對應至 UPS DIMSE N-GET 作業。

指： https://dicom.nema.org/medical/dicom/current/output/html/part18.html#sect_11.5

如果源伺服器上存在 Workitem，Workitem 會以可接受的媒體類型傳回。 傳回的 Workitem 不會包含交易 UID （0008,1195） 屬性。 這是保留屬性角色作為存取鎖定的必要專案。

方法 路徑 描述
GET ../workitems/{workitem} 擷取 Workitem 的要求

標頭 Accept 是必要的，而且必須有 值 application/dicom+json。

擷取 Workitem 回應狀態代碼

代碼 描述
200 (確定) 已成功擷取 Workitem 實例。
400 (錯誤的要求) 要求發生問題。
401 (未經授權) 用戶端未通過驗證。
403 (禁止) 使用者未獲授權。
404 (找不到) 找不到 Target Workitem。

擷取 Workitem 回應承載

  • 成功回應具有單一部分承載，其中包含所選媒體類型中所要求的 Workitem。
  • 傳回的 Workitem 不會包含 Workitem 的交易 UID （0008， 1195） 屬性，因為該屬性應該只對擁有者知道。

Update Workitem

此交易會修改現有 Workitem 的屬性。 它對應於 UPS DIMSE N-SET 作業。

指： https://dicom.nema.org/medical/dicom/current/output/html/part18.html#sect_11.6

若要更新目前處於狀態的 SCHEDULED Workitem， Transaction UID 屬性不應該存在。 針對處於 狀態的 IN PROGRESS Workitem，要求必須包含目前的交易 UID 做為查詢參數。 如果 Workitem 已經在 或 狀態中COMPLETED，則回應為 400 (Bad Request)。CANCELED

方法 路徑 描述
POST ../workitems/{workitem}？{transaction-uid} 更新 Workitem 交易

標頭 Content-Type 是必要的，而且必須有 值 application/dicom+json。

要求承載包含數據集，其中包含要套用至目標 Workitem 的變更。 修改序列時，要求必須包含序列中的所有Items，而不只是要修改的專案。 當多個屬性需要更新為群組時，請在單一要求中將更新為多個屬性，而不是多個要求。

特定交易的內容中有許多與 DICOM 資料屬性相關的需求。 屬性可能需要存在、必須不存在、必須是空白，或非空白。 您可以在此表格中找到這些需求。

注意

包括 1C 和 2C 的所有條件式需求代碼都會被視為選擇性。

注意

要求無法設定程式步驟狀態 （0074,1000） 屬性的值。 程式步驟狀態是使用變更狀態交易或要求取消交易來管理。

更新 Workitem 交易回應狀態代碼

代碼 描述
200 (OK) Target Workitem 已更新。
400 (Bad Request) 要求發生問題。 例如：（1） Target Workitem 處於 COMPLETED 或 CANCELED 狀態。 （2） 遺失交易 UID。 （3） 交易 UID 不正確。 （4） 數據集不符合要求。
401 (Unauthorized) 用戶端未通過驗證。
403 (Forbidden) 使用者未獲授權。
404 (Not Found) 找不到 Target Workitem。
409 (Conflict) 要求與 Target Workitem 的目前狀態不一致。
415 (Unsupported Media Type) 不支援提供的 Content-Type 。

更新 Workitem 交易響應承載

源伺服器支援表格 11.6.3-2 中所需的標頭字段。

成功回應沒有承載，或包含狀態報告文件的承載。

失敗響應承載可能包含狀態報告，描述任何失敗、警告或其他實用資訊。

變更 Workitem 狀態

此交易用來變更 Workitem 的狀態。 它對應至 UPS DIMSE N-ACTION 作業「變更 UPS 狀態」。 狀態變更可用來宣告擁有權、完成或取消 Workitem。

指： https://dicom.nema.org/medical/dicom/current/output/html/part18.html#sect_11.7

如果源伺服器上存在 Workitem，Workitem 會以可接受的媒體類型傳回。 傳回的 Workitem 不會包含交易 UID （0008,1195） 屬性。 這是保留此屬性的角色作為存取鎖定的必要條件，如這裡所述 。

方法 路徑 描述
PUT ../workitems/{workitem}/state 變更 Workitem 狀態

標頭 Accept 是必要的，而且必須有 值 application/dicom+json。

要求承載包含變更 UPS 狀態數據元素。 這些資料元素包括：

  • 交易 UID （0008， 1195） 。 要求承載包含交易 UID。 使用者代理程式會在要求轉換至 IN PROGRESS 指定 Workitem 的狀態時，建立交易 UID。 使用者代理程式會在後續交易中提供該 Workitem 的交易 UID。
  • 程式步驟狀態 （0074， 1000） 。 法律值會對應至要求的狀態轉換。 它們是： IN PROGRESS、 COMPLETED、 或 CANCELED。

變更 Workitem 狀態回應狀態代碼

代碼 描述
200 (OK) 已成功擷取 Workitem 實例。
400 (Bad Request) 由於下列其中一個原因，無法執行要求。 （1） 根據 Target Workitem 的目前狀態，要求無效。 （2） 遺失交易 UID。 （3） 交易 UID 不正確
401 (Unauthorized) 用戶端未通過驗證。
403 (Forbidden) 使用者未獲授權。
404 (Not Found) 找不到 Target Workitem。
409 (Conflict) 要求與 Target Workitem 的目前狀態不一致。

變更 Workitem 狀態響應承載

  • 回應包括區段 11.7.3.2 中指定的標頭字段。
  • 成功回應沒有承載。
  • 失敗響應承載可能包含狀態報告，描述任何失敗、警告或其他實用資訊。

Search Workitems

此交易可讓您依屬性搜尋 Workitems。

方法 路徑 描述
GET ../workitems？ 搜尋 Workitems

支援下列 Accept 標頭進行搜尋。

  • application/dicom+json

支援的搜尋參數

支援每個查詢的下列參數。

機碼 支援值 允許的計數 描述
{attributeID}= {value} 0...N 在查詢中搜尋屬性/值比對
includefield= {attributeID}
all		 0...N 回應中要傳回的其他屬性;只有最上層屬性可以包含 - 不是屬於序列一部分的屬性。 同時支援公用和私人標籤。 提供時 all ，請參閱 搜尋回應 ，以取得每個查詢類型傳回哪些屬性的詳細資訊。 如果 和 all 的{attributeID}混合提供，伺服器預設為使用 『all』。
limit= {value} 0...1 整數值，以限制回應中傳回的值數目;Value 可以在範圍 1 >= x <= 200之間，預設為 100。
offset= {value} 0...1 略過 {value} 結果;如果提供的位移大於搜尋查詢結果的數目， 204 (no content) 則會傳回回應。
fuzzymatching= true | false 0...1 如果將 true 模糊比對套用至任何具有人員名稱 （PN） 值表示法的屬性 （VR）：會執行這些屬性內任何名稱部分的前置詞比對。 例如，如果 PatientName 是 ，則joh為 、、do、 Doe jo do和 John Doe John^Doe所有相符專案。 不過ohn，不相符。
可搜尋的屬性

我們支援搜尋這些屬性。

Attribute 關鍵詞
PatientName
PatientID
ReferencedRequestSequence.AccessionNumber
ReferencedRequestSequence.RequestedProcedureID
ScheduledProcedureStepStartDateTime
ScheduledStationNameCodeSequence.CodeValue
ScheduledStationClassCodeSequence.CodeValue
ScheduledStationGeographicLocationCodeSequence.CodeValue
ProcedureStepState
StudyInstanceUID
搜尋比對

我們支持這些比對類型。

搜尋類型 支援的屬性 範例
範圍查詢 Scheduled​Procedure​Step​Start​Date​Time {attributeID}={value1}-{value2}. 對於日期/時間值，我們支援標籤上的內含範圍。 這會對應至 attributeID >= {value1} AND attributeID <= {value2}。 如果未 {value1} 指定，則會比對之前和包含 {value2} 的所有日期/時間。 同樣地，如果未 {value2} 指定，則會比對所有出現的 {value1} 和後續日期/時間。 不過，其中一個值必須存在。 {attributeID}={value1}- 但是，和 {attributeID}=-{value2} 是有效的， {attributeID}=- 是無效的。
完全相符 所有支持的屬性 {attributeID}={value1}
模糊比對 PatientName 比對名稱以 值開頭的任何元件

注意

雖然我們不支援完整序列比對，但我們確實支援序列中包含的屬性完全相符。

屬性標識碼

標記可以透過許多方式編碼查詢參數。 我們已部分實作 PS3.18 6.7.1.1.1 中所定義的標準。 支援標記的下列編碼方式。

值 範例
{group}{element} 00100010
{dicomKeyword} PatientName

範例查詢：

../workitems?PatientID=K123&0040A370.00080050=1423JS&includefield=00404005&limit=5&offset=0

搜尋回應

回應是已傳回下列屬性的 0...N DICOM 資料集數位：

  • DICOM PowerShell 3.4 資料表 CC.2.5-3 中傳回索引鍵類型為 1 或 2 的所有屬性。
  • DICOM PowerShell 3.4 數據表 CC.2.5-3 中的所有屬性，其傳回密鑰類型為 1C，符合條件式需求。
  • 所有其他以比對參數傳遞的 Workitem 屬性。
  • 所有其他以參數值傳遞 includefield 的 Workitem 屬性。

搜尋回應碼

查詢 API 會在回應中傳回下列其中一個狀態代碼。

代碼 描述
200 (OK) 響應承載包含所有相符的資源。
206 (Partial Content) 響應承載只包含一些搜尋結果，其餘部分可以透過適當的要求來要求。
204 (No Content) 搜尋已順利完成，但未傳回任何結果。
400 (Bad Request) 要求發生問題。 例如，無效的查詢參數語法。 回應本文包含失敗的詳細數據。
401 (Unauthorized) 用戶端未通過驗證。
403 (Forbidden) 使用者未獲授權。
503 (Service Unavailable) 服務無法使用或忙碌中。 請稍後再試一次。

其他注意事項

查詢 API 不會傳回 413 (request entity too large)。 如果要求的查詢回應限制超出可接受的範圍，則會傳回不正確的要求。 可接受範圍內要求的任何專案都已解決。

  • 已優化分頁結果以先傳回相符的最新實例，如果新增符合查詢的新數據，可能會導致後續頁面中的記錄重複。
  • 比對 不 區分大小寫， 對 PN VR 類型不 區分腔調字。
  • 比對不區分大小寫，而且對其他字串 VR 類型區分腔調字。
  • 如果有一個案例會同時取消 Workitem 並查詢相同的 Workitem，則查詢可能會排除正在更新的 Workitem，而回應碼為 206 (Partial Content)。

注意

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