DICOM 符合聲明

Cloud Healthcare API 中的 DICOM 存放區支援 DICOM PS3.18 - Web Services 標準 (通常稱為 DICOMweb) 中指定的 RESTful 網路服務子集。具體來說，這些服務支援「研究服務和資源」 (先前稱為 WADO-RS、STOW-RS 和 QIDO-RS 服務)。

此外，Cloud Healthcare API 也支援專屬的網頁服務，可刪除 DICOM 執行個體。

Cloud Healthcare API 不支援 URI 服務、Worklist 服務、Non-Patient Instance 服務，或任何功能交易。

擷取交易

「擷取交易」是 RESTful 網路服務，用於擷取 DICOM 影像資料。

「Retrieve Transaction」支援擷取下列資源：

  • DICOM 資源：
    • 研究報告
    • 系列
    • 執行個體
    • 影格
    • Bulkdata
  • 中繼資料資源
    • 研究報告
    • 系列
    • 執行個體
  • 已算繪的資源
    • 執行個體
    • 影格

不支援縮圖資源。

如要瞭解這些方法的配額和限制，請參閱「配額與限制」。

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 會包含與大量資料定義相符的標記 BulkDataURI。

如果 DICOM 序列標記包含超過約 1 MiB 的資料，系統就不會在元資料資源中傳回該標記。這項限制僅適用於中繼資料資源。DICOM 資源仍會包含這些標記。

Bulkdata 資源

系統支援下列 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 (Explicit 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 無損)

如果原始檔案的轉移語法不在上述清單中，且您要求轉碼為其他格式，系統會傳回錯誤。

Cloud Healthcare API 無法將位元深度大於 8 的非單色圖片轉碼為 JPEG。此外，如果影像的「分配位元」(0028, 0100) 值為 1，或是儲存在「浮點像素資料」(7FE0,0008) 或「雙精度浮點像素資料」(7FE0,0009) 標記中，則只能在原生格式之間轉碼。

如要停用轉碼並從 API 擷取任何檔案，您可以在 Accept 標頭中設定 transfer-syntax=*。

狀態碼

程式碼 意義
200 (OK) 回應酬載包含所有目標資源的表示法。
400 (錯誤的要求) 指定目標資源的要求無效 (例如查詢參數或標頭有誤)，或缺少像素資料。
401 (未獲授權) 要求缺少驗證憑證。
403 (權限遭拒) 已通過驗證的使用者無法存取這項資源 (或資源不存在)。
406 (無法接受) 伺服器不支援任何可接受的媒體類型。
429 (要求數量過多) 用戶端超出配額。
503 (服務無法使用) 伺服器目前無法使用，或要求已超過期限。

商店交易

Store Transaction 是 RESTful 網路服務，用於儲存 DICOM 影像資料。

商店交易可直接接受第 10 部分 DICOM 二進位檔案，或接受將 DICOM 檔案分割為中繼資料 (以 JSON 表示) 和大量資料。這 2 個版本具有不同的語意，詳情請參閱以下各節。

如要瞭解這個方法的配額和限制，請參閱「配額與限制」。

DICOM 第 10 部分二進位檔案

系統支援的 Content-Type 如下：

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

伺服器不會強制或取代屬性。

這個版本接受所有傳輸語法和 SOP 類別。系統只會對 DICOM 檔案執行最基本的驗證，以擷取部分重要中繼資料屬性。

請注意，為方便起見，Store Transaction 也接受單一部分的 HTTP 要求，其中包含單一 DICOM 執行個體，且內容類型為 application/dicom。這並非 DICOMweb 標準的正式內容。

如需相關操作指南，請參閱「儲存 DICOM 執行個體」。

JSON 中繼資料和大量資料要求

使用 JSON 中繼資料和大量資料儲存執行個體時，第一個多部分必須包含 DICOM 執行個體的 JSON 陣列。

第一部分必須具有 application/dicom+json; transfer-syntax=TransferSyntaxUID 的 Content-Type，其中 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 (Explicit VR Big Endian)
  • 1.2.840.10008.1.2.1.99 (Deflated Explicit VR Little Endian)

在 JSON 中繼資料中，使用者可以為 VR 為 OB、OW 或 UN 的 DICOM 標記指定多個 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> 元組，系統會傳回「處理失敗」錯誤，並附上「已存在」FailureDetail 標記。

回應格式可以是 JSON 或 XML，可透過下列 Accept 標頭值控制：

  • application/dicom+xml (預設)
  • application/dicom+json

狀態碼

程式碼 意義
200 (OK) 資源已成功儲存。
400 (錯誤的要求) 要求無效 (例如不支援的媒體類型或轉移語法)。
401 (未獲授權) 要求缺少驗證憑證。
403 (權限遭拒) 已通過驗證的使用者無法存取這項資源 (或資源不存在)。
406 (無法接受) 伺服器不支援任何可接受的媒體類型。
409 (衝突) 至少有一項資源未儲存成功 (例如無效的 DICOM 檔案)。詳情請參閱回應主體中的 FailureDetail 標記。
429 (要求數量過多) 用戶端超出配額。
503 (服務無法使用) 伺服器目前無法使用，或要求已超過期限。

搜尋交易

搜尋交易是 RESTful 網路服務，用於查詢 DICOM 影像中繼資料。

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：可以設為以半形逗號分隔的 attributeID 清單，例如 DICOM 標記 ID 或關鍵字，也可以設為 all 值，傳回所有可用的標記。如需可用標記的清單，請參閱「傳回的結果」。

系統支援使用 limit 和 offset 查詢參數進行分頁。如果沒有其他結果，就不會有 Warning 回應標頭。您必須執行額外查詢，才能判斷是否有更多結果。

  • limit：應傳回的結果數上限，研究/系列最多 5,000 個，執行個體最多 50,000 個。研究/系列的預設結果數為 100，執行個體的預設結果數為 1,000。

  • offset：開頭要略過的結果數量，最多 1,000,000 個。

系統不支援「與世界標準時間的時區偏移」。

傳回的結果

回覆格式可以是 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 執行個體中的所有屬性，但下列例外狀況除外。

如果 DICOM 序列標記包含超過約 1 MiB 的資料，就不會在中繼資料回應中傳回。

中繼資料不一致/無效

如果使用 SearchForStudies/SearchForSeries，多個執行個體可能會出現不一致的研究/系列層級中繼資料。舉例來說，兩個執行個體可能上傳了相同的 StudyInstanceUID，但 StudyDate 不同。在這種情況下，搜尋行為的定義不明確。 在某些情況下，您或許可以依該值搜尋，但有時則不行，且不同呼叫傳回的值可能不同。

狀態碼

程式碼 意義
200 (OK) 回應酬載包含所有目標資源的表示法。
400 (錯誤的要求) 要求無效 (例如查詢參數無效)。
401 (未獲授權) 要求缺少驗證憑證。
403 (權限遭拒) 已通過驗證的使用者無法存取這項資源 (或資源不存在)。
406 (無法接受) 伺服器不支援任何可接受的媒體類型。
429 (要求數量過多) 用戶端超出配額。
503 (服務無法使用) 伺服器目前無法使用，或要求已超過期限。

刪除

Cloud Healthcare API 支援下列專屬動作類型：

  • DeleteStudy
  • DeleteSeries
  • DeleteInstance

這些路徑與 WADO-RS 對應路徑 (分別為 RetrieveStudy、RetrieveSeries 和 RetrieveInstance) 相同。系統會使用 DELETE 要求，而非 HTTP GET 要求。這麼做會刪除指定的檢查、系列或執行個體，以及其中包含的所有 DICOM 資源。

DeleteStudy 和 DeleteSeries 方法會傳回長期執行的作業，刪除研究或系列中的所有執行個體。請注意，如果作業正在刪除研究或系列，您必須等到作業完成，才能將執行個體插入研究或系列。

如需作業操作指南，請參閱「管理長時間執行的作業」。

成功的 DeleteInstance 要求會傳回空白回應。

狀態碼

程式碼 意義
200 (OK) 要求資源已刪除。
400 (錯誤的要求) 要求無效。
401 (未獲授權) 要求缺少驗證憑證。
403 (權限遭拒) 已通過驗證的使用者無法存取這項資源 (或資源不存在)。
429 (要求數量過多) 用戶端超出配額。
503 (服務無法使用) 伺服器目前無法使用，或要求已超過期限。

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 Definition

擷取中繼資料時，Cloud Healthcare API 會排除定義為大量資料的特定標記。這些標記會連同中繼資料一併傳回，並附上 BulkDataURI，方便使用者擷取這些標記的內容 (請參閱 RetrieveBulkdata)。 以下是 Cloud Healthcare API 使用的定義：

  • 任何 Pixel 資料標記：(7FE0,0008)、(7FE0,0009)、(7FE0,0010)。
  • VR 為 OB、OW 或 UN 的任何標記。
  • VR 為 OD、OF、OL 或 OV，且大於 2 KiB 的標記。
    • 基於舊版原因，如果標記大於 256 B (OF 和 OL) 或 512 B (OD)，則已擷取至 Cloud Healthcare API 的執行個體標記可能會視為大量資料。
  • VR 為 AT、FD、FL、UL、US、SV 或 UV，且值多重性 (VM) 大於 512 的標記。
    • 基於舊版原因，如果 VM 大於 64，已擷取至 Cloud Healthcare API 的執行個體標記可能會視為大量資料。

此外，下列標記會視為大量資料，但從中繼資料方法傳回時沒有 BulkDataURI，且內容無法使用 RetrieveBulkdata 擷取：

  • VR 為 SQ 且大小大約超過 1 MiB 的標記。