DICOM 一致性語句 v2

發行項
09/01/2024

注意

API 第 2 版是最新的 API 版本。如需 v2 與 v1 相比的變更清單，請參閱 DICOM 服務 API v2 變更

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

研究服務
Worklist Service （UPS 推送和提取 SOP）

此外，支持這些非標準 API：

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

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

這個版本的一致性語句會對應至 v2 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 會繼續為必要的標籤，而且在輸入中可以有 null 值。 PatientID會根據其LOVR類型進行驗證。

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

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

注意

要求限制為 4GB。沒有單一 DICOM 檔案或檔案組合可能超過此限制。

儲存 v1 的變更

在舊版中，如果任何必要或可搜尋的屬性驗證失敗，Store 要求將會失敗。從 V2 開始，只有在必要的屬性驗證失敗時，要求才會失敗。

API 不需要的屬性驗證失敗，導致檔案儲存時出現警告。每個實例的每個失敗屬性都有警告。當序列包含驗證失敗的屬性，或單一屬性有多個問題時，只會指出第一個失敗的屬性原因。

如果屬性以 Null 填補，當可搜尋且儲存為 dicom+json 元數據時，屬性會編製索引。未提供驗證警告。

儲存回應狀態代碼

代碼	描述
`200 (OK)`	要求中的所有 SOP 實例都已儲存。
`202 (Accepted)`	源伺服器儲存了部分實例，而其他實例則失敗或傳回警告。有關此錯誤的其他資訊可能會在回應消息本文中找到。
`204 (No Content)`	存放區交易要求中未提供任何內容。
`400 (Bad Request)`	要求的格式不正確。例如，提供的學習實例標識碼不符合預期的 UID 格式。
`401 (Unauthorized)`	用戶端未通過驗證。
`406 (Not Acceptable)`	不支援指定的 `Accept` 標頭。
`409 (Conflict)`	存放區交易要求中的實例都未儲存。
`415 (Unsupported Media Type)`	不支援提供的 `Content-Type` 。
`424 (Failed Dependency)`	DICOM 服務無法存取它相依的資源，無法完成此要求。例如，無法存取連線的 Data Lake Store 或密鑰保存庫，以支援客戶管理的密鑰加密。
`500 (Internal Server Error)`	伺服器發生未知的內部錯誤。請稍後再試一次。
`503 (Service Unavailable)`	服務無法使用或忙碌中。請稍後再試一次。

儲存響應承載

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

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

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

標籤	名稱	描述
(0008, 1150)	`ReferencedSOPClassUID`	無法儲存之實例的SOP類別唯一標識碼。
(0008, 1155)	`ReferencedSOPInstanceUID`	無法儲存之實例的 SOP 實例唯一標識碼。
(0008, 1197)	`FailureReason`	此實例無法儲存的原因碼。
(0008, 1196)	`WarningReason`	`WarningReason`表示偵測到但不夠嚴重但無法讓存放區作業失敗的驗證問題。
(0074, 1048)	`FailedAttributesSequence`	的序列 `ErrorComment` ，其中包含每個失敗屬性的原因。

中的每個 ReferencedSOPSequence 資料集都有下列元素：

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

在 ReferencedSOPSequence 中，標頭Acceptapplication/dicom+json沒有 FailedAttributesSequence 的範例回應：

{
  "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"]
      }
    }]
  }
}

具有 ReferencedSOPSequence 中 FailedAttributesSequence 之標頭application/dicom+json的範例回應Accept：

{
  "00081190":
  {
    "vr":"UR",
    "Value":["http://localhost/studies/d09e8215-e1e1-4c7a-8496-b4f6641ed232"]
  },
  "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"]
      },
      "00081196": {
        "vr": "US",
        "Value": [
            1
        ]
      },
      "00741048": {
        "vr": "SQ",
        "Value": [
          {
            "00000902": {
              "vr": "LO",
              "Value": [
                "DICOM100: (0008,0020) - Content \"NotAValidDate\" does not validate VR DA: one of the date values does not match the pattern YYYYMMDD"
              ]
            }
          },
          {
            "00000902": {
              "vr": "LO",
              "Value": [
                "DICOM100: (0008,002a) - Content \"NotAValidDate\" does not validate VR DT: value does not mach pattern YYYY[MM[DD[HH[MM[SS[.F{1-6}]]]]]]"
              ]
            }
          }
        ]
      }
    }]
  }
}

存放區失敗原因碼

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

儲存警告原因碼

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

儲存錯誤碼

代碼	描述
`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
application/octet-stream; transfer-syntax=* 用於單一畫面擷取

*/* （未指定 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

擷取的元數據會在屬性以 Null 填補並儲存為原狀時包含 Null 字元。

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

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

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

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

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

image/jpeg
image/png

在未 Accept 指定標頭的情況下，服務預設會 image/jpeg 轉譯。

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

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

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

擷取原始版本

使用大量更新作業可讓您擷取研究、系列或實例的原始或最新版本。預設一律會傳回最新版的研究、系列或執行個體。您可以將標頭設定 msdicom-request-original 為 true，以傳回原始版本。範例要求如下：

GET ../studies/{study}/series/{series}/instances/{instance}
Accept: multipart/related; type="application/dicom"; transfer-syntax=*
msdicom-request-original: true
Content-Type: application/dicom

擷取回應狀態代碼

代碼	描述
`200 (OK)`	已擷取所有要求的數據。
`304 (Not Modified)`	自上一個要求之後，要求的數據不會變更。在這種情況下，內容不會新增至回應本文。如需詳細資訊，請參閱上一節擷取元數據快取驗證（適用於研究、數列或實例）。
`400 (Bad Request)`	要求的格式不正確。例如，所提供的研究實例標識碼不符合預期的 UID 格式，或不支援要求的傳輸語法編碼。
`401 (Unauthorized)`	用戶端未通過驗證。
`403 (Forbidden)`	使用者未獲授權。
`404 (Not Found)`	找不到指定的 DICOM 資源，或針對轉譯的要求，實例未包含像素數據。
`406 (Not Acceptable)`	不支援指定的 `Accept` 標頭，或針對轉譯和轉碼要求所要求的檔案太大。
`424 (Failed Dependency)`	DICOM 服務無法存取它相依的資源，無法完成此要求。例如，無法存取連線的 Data Lake Store 或密鑰保存庫，以支援客戶管理的密鑰加密。
`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

從 v1 搜尋變更

在 v1 API 中，如果擴充查詢標籤有任何錯誤，因為一或多個現有的實例有無法編製索引的標記值，則包含擴充查詢卷標的後續搜尋查詢會傳回erroneous-dicom-attributes檔中的詳細數據。不過，此標頭中不包含具有 STOW-RS 驗證警告的標籤（也稱為屬性）。如果存放區要求在儲存實例時產生可搜尋屬性的驗證警告，這些屬性可能無法用來搜尋已儲存的實例。不過，如果失敗的同一個研究或數列中的實例覆寫值，或如果先前的實例已經正確儲存值，則驗證失敗的任何可搜尋屬性都可以傳回結果。如果未覆寫屬性值，則不會產生任何搜尋結果。

您可以透過下列方式更正屬性。

刪除已儲存的實例，並上傳具有更正數據的新實例
使用更正的數據，在相同的研究/系列中上傳新的實例

支援的搜尋參數

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

機碼	支援值	允許的計數	描述
`{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（沒有內容）回應。
`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`	比對名稱以值開頭的任何元件
UID 清單比對	`StudyInstanceUID`	比對清單中提供的值所識別的研究。支援逗號（，，）或反斜杠（\）作為有效的分隔符。 `{attributeID}=1.2.3,5.6.7,8.9.0` 會傳回與所有研究相關聯的詳細數據，因為它們存在。

屬性標識碼

標記可以透過數種方式編碼查詢參數。我們已部分實作 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, 0020)	`StudyDate`
(0008, 0050)	`AccessionNumber`
(0008, 1030)	`StudyDescription`
(0009, 0090)	`ReferringPhysicianName`
(0010, 0010)	`PatientName`
(0010, 0020)	`PatientID`
(0010, 0030)	`PatientBirthDate`
（0020,000D）	`StudyInstanceUID`

默認數列標籤

標籤	屬性名稱
(0008, 0060)	`Modality`
(0008, 1090)	`ManufacturerModelName`
（0020,000E）	`SeriesInstanceUID`
(0040, 0244)	`PerformedProcedureStepStartDate`

默認實例標籤

標籤	屬性名稱
(0008, 0018)	`SOPInstanceUID`

如果 includefield=all為，這些屬性會連同預設屬性一起包含。除了預設屬性，此清單也包含每個資源層級支援的屬性完整清單。

其他研究標籤

標籤	屬性名稱
(0008, 0005)	`SpecificCharacterSet`
(0008, 0030)	`StudyTime`
(0008, 0056)	`InstanceAvailability`
(0008, 0201)	`TimezoneOffsetFromUTC`
(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`
(0010, 0040)	`PatientSex`
(0020, 0010)	`StudyID`

其他數列標籤

標籤	屬性名稱
(0008, 0005)	SpecificCharacterSet
(0008, 0201)	TimezoneOffsetFromUTC
(0020, 0011)	SeriesNumber
(0020, 0060)	橫向
(0008, 0021)	SeriesDate
(0008, 0031)	SeriesTime
（0008,103E）	SeriesDescription
(0040, 0245)	PerformedProcedureStepStartTime
(0040, 0275)	RequestAttributesSequence

其他實例標籤

標籤	屬性名稱
(0008, 0005)	SpecificCharacterSet
(0008, 0016)	SOPClassUID
(0008, 0056)	InstanceAvailability
(0008, 0201)	TimezoneOffsetFromUTC
(0020, 0013)	InstanceNumber
(0028, 0010)	資料列
(0028, 0011)	資料行
(0028, 0100)	BitsAllocated
(0028, 0008)	NumberOfFrames

會傳回下列屬性。

資源 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)`	使用者未獲授權。
`414 (URI Too Long)`	URI 超過支援的長度上限 8192 個字元。
`424 (Failed Dependency)`	DICOM 服務無法存取它相依的資源，無法完成此要求。例如，無法存取連線的 Data Lake Store 或密鑰保存庫，以支援客戶管理的密鑰加密。
`503 (Service Unavailable)`	服務無法使用或忙碌中。請稍後再試一次。

備註

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

刪除

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

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

參數 study、 series與 instance 分別對應至 DICOM 屬性 StudyInstanceUID、 SeriesInstanceUID與 SopInstanceUID 。

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

注意

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

回應狀態代碼

代碼	描述
`204 (No Content)`	刪除所有 SOP 實例時。
`400 (Bad Request)`	要求的格式不正確。
`401 (Unauthorized)`	用戶端未通過驗證。
`403 (Forbidden)`	使用者未獲授權。
`404 (Not Found)`	在研究中找不到指定的數列，或在數列中找不到指定的實例時。
`424 (Failed Dependency)`	DICOM 服務無法存取它相依的資源，無法完成此要求。例如，無法存取連線的 Data Lake Store 或密鑰保存庫，以支援客戶管理的密鑰加密。
`503 (Service Unavailable)`	服務無法使用或忙碌中。請稍後再試一次。

刪除響應承載

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

Worklist Service （UPS-RS）

DICOM 服務支援 Worklist Service (UPS-RS) 的推送和提取 SOP。此服務提供一個 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` 。
`424 (Failed Dependency)`	DICOM 服務無法存取它相依的資源，無法完成此要求。例如，無法存取連線的 Data Lake Store 或密鑰保存庫，以支援客戶管理的密鑰加密。
`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` 。
`424 (Failed Dependency)`	DICOM 服務無法存取它相依的資源，無法完成此要求。例如，無法存取連線的 Data Lake Store 或密鑰保存庫，以支援客戶管理的密鑰加密。
`503 (Service Unavailable)`	服務無法使用或忙碌中。請稍後再試一次。

要求取消響應承載

成功回應沒有承載，而失敗響應承載則包含描述失敗的訊息。如果 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。
424 （失敗的相依性）	DICOM 服務無法存取它相依的資源，無法完成此要求。例如，無法存取連線的 Data Lake Store 或密鑰保存庫，以支援客戶管理的密鑰加密。
503 （服務無法使用）	服務無法使用或忙碌中。請稍後再試一次。

擷取 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` 。
`424 (Failed Dependency)`	DICOM 服務無法存取它相依的資源，無法完成此要求。例如，無法存取連線的 Data Lake Store 或密鑰保存庫，以支援客戶管理的密鑰加密。
`503 (Service Unavailable)`	服務無法使用或忙碌中。請稍後再試一次。

更新 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 的目前狀態不一致。
`424 (Failed Dependency)`	DICOM 服務無法存取它相依的資源，無法完成此要求。例如，無法存取連線的 Data Lake Store 或密鑰保存庫，以支援客戶管理的密鑰加密。
`503 (Service Unavailable)`	服務無法使用或忙碌中。請稍後再試一次。

變更 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	整數值，以限制回應中傳回的值數目。值可以在範圍 `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`

注意

我們不支援使用空字串搜尋任何屬性。

搜尋比對

我們支援下列比對類型。

搜尋類型	支援的屬性	範例
範圍查詢	`ScheduledProcedureStepStartDateTime`	`{attributeID}={value1}-{value2}`. 對於日期/時間值，我們支援標籤上的內含範圍。這個範圍會對應至 `attributeID >= {value1} AND attributeID <= {value2}`。如果未 `{value1}` 指定，則會比對之前所有出現的日期/時間，包括 `{value2}` 。同樣地，如果未 `{value2}` 指定，則會比對所有出現的 `{value1}` 和後續日期/時間。不過，其中一個值必須存在。 `{attributeID}={value1}-`但是`{attributeID}=-`，和 `{attributeID}=-{value2}` 無效。
完全相符	所有支持的屬性	`{attributeID}={value1}`
模糊比對	`PatientName`	比對以值開頭之名稱的任何元件。
通配符比對	`PatientID`, `ReferencedRequestSequence.AccessionNumber`, `ReferencedRequestSequence.RequestedProcedureID`, `ProcedureStepState`, `ScheduledStationNameCodeSequence.CodeValue`, `ScheduledStationClassCodeSequence.CodeValue`, `ScheduledStationGeographicLocationCodeSequence.CodeValue`	支援下列通配符： `` - 比對零個或多個字元。例如 - `{attributeID}={val}` 符合 “val”、“valid”、“value” 而非 “evaluate”。 `?` - 比對單一字元。例如 - `{attributeID}={valu?}` 符合 “value”、“valu1” 而非 “valued” 或 “valu”

注意

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

屬性標識碼

標記可以透過許多方式編碼查詢參數。我們已部分實作 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)`	使用者未獲授權。
`424 (Failed Dependency)`	DICOM 服務無法存取它相依的資源，無法完成此要求。例如，無法存取連線的 Data Lake Store 或密鑰保存庫，以支援客戶管理的密鑰加密。
`503 (Service Unavailable)`	服務無法使用或忙碌中。請稍後再試一次。

其他注意事項

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

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

注意

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

共用方式為

DICOM 一致性語句 v2

Preamble Sanitization

研究服務

商店 （STOW-RS）

儲存必要的屬性

儲存 v1 的變更

儲存回應狀態代碼

儲存響應承載

存放區失敗原因碼

儲存警告原因碼

儲存錯誤碼

擷取 （WADO-RS）

擷取研究或數列內的實例

擷取實例

擷取

擷取傳輸語法

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

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

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

擷取原始版本

擷取回應狀態代碼

搜尋 （QIDO-RS）

從 v1 搜尋變更

支援的搜尋參數

可搜尋的屬性

搜尋比對

屬性標識碼

搜尋回應

默認研究標籤

默認數列標籤

默認實例標籤

其他研究標籤

其他數列標籤

其他實例標籤

搜尋回應碼

備註

刪除

回應狀態代碼

刪除響應承載

Worklist Service （UPS-RS）

建立 Workitem

建立回應狀態代碼

建立響應承載

要求取消

要求取消響應狀態代碼

要求取消響應承載

擷取 Workitem

擷取 Workitem 回應狀態代碼

擷取 Workitem 回應承載

Update Workitem

更新 Workitem 交易回應狀態代碼

更新 Workitem 交易響應承載

變更 Workitem 狀態

變更 Workitem 狀態回應狀態代碼

變更 Workitem 狀態響應承載

Search Workitems

支援的搜尋參數

可搜尋的屬性

搜尋比對

屬性標識碼

搜尋回應

搜尋回應碼

其他注意事項

意見反應

其他資源

商店（STOW-RS）

擷取（WADO-RS）

搜尋（QIDO-RS）