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 服務、工作清單服務、非病患例項服務或任何功能交易。

擷取交易

擷取交易是擷取 DICOM 影像資料的 RESTful 網路服務。

擷取交易支援擷取下列資源：

  • 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

僅支援擷取例項或影格資源。

除了Viewport，系統不支援其他網址參數。

中繼資料資源

系統支援下列 Accept 標頭：

  • application/dicom+json (預設)
  • multipart/related; type=application/dicom+xml

標記會以小端位元組順序編碼，因為要求中繼資料資源的端點不支援傳輸構詞參數。

根據預設，RetrieveMetadata 不會傳回任何屬性，其 DICOM 值表示法為 OB、OW 或 UN。如要針對符合預覽 大量資料定義的標記傳回大量資料 URI，請使用 Preview version。

含有超過 1 MiB 資料的 DICOM 序列標記不會在中繼資料資源中傳回。這項限制僅適用於中繼資料資源。DICOM 資源仍會包含這些標記。

大量資料資源 (預先發布版)

系統支援下列 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 (明確的 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 Lossless)

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

Cloud Healthcare API 無法將位元深度大於 8 的非單色圖片轉碼為 JPEG。此外，如果圖片的 Bits Allocated (0028, 0100) 值為 1，或是儲存在 Float Pixel Data (7FE0,0008)、Double Float Pixel Data (7FE0,0009) 標記中的圖片，只能在原生格式之間進行轉碼。

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

狀態碼

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

商店交易

儲存交易是用於儲存 DICOM 影像資料的 RESTful 網路服務。

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

如要進一步瞭解此方法的配額和限制，請參閱「配額與限制」。

DICOM 10 部分二進位檔案

系統支援以下 Content-Types：

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

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

這個版本接受所有轉移語法和 SOP 類別。只會對 DICOM 檔案進行最少的驗證，以便擷取一些重要的中繼資料屬性。

請注意，為了方便起見，儲存交易也接受單一部分 HTTP 要求，其中包含單一 DICOM 例項，且內容類型為 application/dicom。這不是官方 DICOMweb 標準的一部分。

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

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

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

第一部分必須具有 application/dicom+json; transfer-syntax=TransferSyntaxUID 的 Content-Type，其中 TransferSyntaxUID 是用於在 InlineBinary 物件中編碼二進位資料的轉移語法。如果中繼資料中沒有 InlineBinary 物件，可以省略 transfer-syntax 參數。

以下 DICOM 元素必須出現在 JSON 中繼資料的每個例項中：

  • SpecificCharacterSet
  • TransferSyntaxUID
  • SOPClassUID
  • StudyInstanceUID
  • SeriesInstanceUID
  • SOPInstanceUID

SpecificCharacterSet 元素必須設為 ISO_IR 192，且 JSON 中繼資料必須以萬國碼 UTF-8 編碼。TransferSyntaxUID 可設為任何有效的轉移語法，但以下不支援的轉移語法除外：

  • 1.2.840.10008.1.2.2 (明確的 VR Big Endian)
  • 1.2.840.10008.1.2.1.99 (Deflated Explicit VR Little Endian)

在 JSON 中繼資料中，使用者可以為 DICOM 標記指定多個 BulkDataURI，其中 VR 為 OB、OW 或 UN。這些 BulkDataURI 表示含有 URI 的標記的二進位資料會在後續部分傳送，而該部分的 Content-Location 標頭已設為 BulkDataURI。

JSON 中繼資料中的每個例項最多只能包含一個 BulkDataURI。JSON 中繼資料中不得有重複的 BulkDataURI。壓縮圖片大量資料只能傳送至 PixelData 代碼，且在傳送時，大量資料部分中指定的轉移語法必須與例項的 TransferSyntaxUID 元素值相符。

系統支援以下 Content-Types 的大量資料部分：

  • 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 中繼資料中使用內嵌二進位物件時，必須在 JSON 中繼資料部分的 Content-Type 中指定用於編碼的轉移語法。

伺服器不會擷取圖片像素說明巨集屬性。

如需相關操作說明，請參閱「從 JSON 中繼資料和 JPEG 檔案建立 DICOM 例項」一文。

回應

發生錯誤時，系統會傳回額外的 FailureDetail (0009, 0097) 標記 (適用於 XML 回應) 或 FailureDetailJSON (0009, 1097) 標記 (適用於 JSON 回應)。FailureDetail 標記會提供錯誤的使用者可讀說明。

如果 DICOM 例項的 <StudyInstanceUID, SeriesInstanceUID, SOPInstanceUID> 元組與 DICOM 儲存庫中已有的例項相同，系統會傳回「Processing failure」錯誤，並附上「already exists」FailureDetail 標記。

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

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

狀態碼

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

搜尋交易

Search Transaction 是用於查詢 DICOM 影像中繼資料的 RESTful 網路服務。

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

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

  • 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 例項中的所有屬性，但以下例外。

根據預設，searchForInstances 不會傳回任何屬性，這些屬性具有 DICOM 值表示法 OB、OW 或 UN。如要針對符合預覽 大量資料定義的標記傳回大量資料 URI，請使用 Preview searchForInstances。

中繼資料回應中不會傳回含有超過 1 MiB 資料的 DICOM 序列標記。

中繼資料不一致/無效

在 SearchForStudies/SearchForSeries 的情況下，多個執行個體可能會有不一致的研究/系列層級中繼資料。舉例來說，兩個例項可能會使用相同的 StudyInstanceUID 上傳，但有不同的 StudyDate。在這種情況下，搜尋行為並未明確定義。在某些情況下，使用該值進行搜尋可能有效，但在其他情況下則不行，且傳回的值可能因不同呼叫而異。

狀態碼

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

刪除

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

  • DeleteStudy
  • DeleteSeries
  • DeleteInstance

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

DeleteStudy 和 DeleteSeries 方法會傳回長時間執行的作業，用來刪除研究或系列中的所有例項。請注意，在作業完成之前，您無法將例項插入作業刪除的研究或系列中。

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

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

狀態碼

程式碼 意義
200 (OK) 要求資源已刪除。
400 (Bad Request) 要求無效。
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 時產生資料欄名稱。

大量資料標記定義 (預先發布版)

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

  • 任何像素資料標記：(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。