搭配 cURL 使用 DICOMweb 標準 API

發行項
09/03/2024

本文說明如何透過 cURL 和 .dcm DICOM® 檔案範例來使用 DICOMweb 服務。

使用這些檔案範例：

blue-circle.dcm
dicom-metadata.csv
green-square.dcm
red-triangle.dcm

DICOM 檔案範例的檔名、studyUID、seriesUID 和 instanceUID 為：

檔案	StudyUID	SeriesUID	InstanceUID
green-square.dcm	1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420	1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652	1.2.826.0.1.3680043.8.498.12714725698140337137334606354172323212
red-triangle.dcm	1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420	1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652	1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395
blue-circle.dcm	1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420	1.2.826.0.1.3680043.8.498.77033797676425927098669402985243398207	1.2.826.0.1.3680043.8.498.13273713909719068980354078852867170114

注意

其中每一個檔案都代表單一執行個體，而且是相同研究的一部分。此外，綠色方形和紅色三角形是相同系列的一部分，而藍色圓圈則位於個別系列中。

必要條件

若要使用 DICOM 標準 API，您必須部署 DICOM 服務的執行個體。如需詳細資訊，請參閱使用 Azure 入口網站部署 DICOM 服務。

部署 DICOM 服務的執行個體之後，擷取應用程式服務的 URL。

登入 Azure 入口網站。
搜尋最近使用的資源，然後選取您的 DICOM 服務執行個體。
複製 DICOM 服務的服務 URL。
如果您需要存取權杖，請參閱取得 DICOM 服務的存取權杖。

此程式碼可用來存取公開預覽版 Azure 服務。切勿上傳任何私人健康資訊 (PHI)。

使用 DICOM 服務

DICOMweb 標準會大量使用結合 DICOM 專屬接受標頭的 multipart/related HTTP 要求。熟悉其他 REST 型 API 的開發人員通常會在使用 DICOMweb 標準時覺得不習慣。不過，啟動並執行之後，您就能輕易上手。只有剛開始時需要熟悉一下。

cURL 命令各含有至少一個 (有時兩個) 必須取代的變數。若要簡化命令執行，請搜尋下列變數並取代為您的特定值。

{Service URL} 服務 URL 是存取您在 Azure 入口網站中佈建的 DICOM 服務的 URL，例如 https://<workspacename-dicomservicename>.dicom.azurehealthcareapis.com。建立要求時，請務必將版本指定為 URL 的一部分。如需詳細資訊，請參閱適用於 DICOM 服務的 API 版本設定文件。
{path-to-dicoms} - red-triangle.dcm 檔案所在目錄的路徑，例如 C:/dicom-server/docs/dcms
- 請務必使用正斜線作為分隔符號，且在目錄結尾不使用尾端正斜線。

上傳 DICOM 執行個體 (STOW)

使用 multipart/related 儲存執行個體

此要求打算示範如何使用 multipart/related 來上傳 DICOM 檔案。

注意

DICOM 服務比 DICOM 標準更寬容。不過，此範例示範嚴格符合標準的 POST 要求。

詳細資料：

路徑：../studies
方法：POST
Headers：
- Accept: application/dicom+json
- Content-Type: multipart/related; type="application/dicom"
- Authorization: Bearer {token value}
本文：
- Content-Type：每個上傳檔案的 application/dicom，以界限值分隔

某些程式設計語言和工具的行為不同。例如，有些會要求您定義自己的界限。針對這些工具，您可能需要使用稍微修改的 Content-Type 標頭。您可以順利地使用下列工具。

Content-Type: multipart/related; type="application/dicom"; boundary=ABCD1234
Content-Type: multipart/related; boundary=ABCD1234
Content-Type: multipart/related

curl --location --request POST "{Service URL}/v{version}/studies"
--header "Accept: application/dicom+json"
--header "Content-Type: multipart/related; type=\"application/dicom\""
--header "Authorization: Bearer {token value}"
--form "file1=@{path-to-dicoms}/red-triangle.dcm;type=application/dicom"
--trace-ascii "trace.txt"

儲存特定研究的執行個體

此要求示範如何使用 multipart/related 將 DICOM 檔案上傳至指定的研究。

詳細資料：

路徑：../studies/{study}
方法：POST
Headers：
- Accept: application/dicom+json
- Content-Type: multipart/related; type="application/dicom"
- Authorization: Bearer {token value}
本文：
- Content-Type：每個上傳檔案的 application/dicom，以界限值分隔

某些程式設計語言和工具的行為不同。例如，有些會要求您定義自己的界限。針對這些語言和工具，您可能需要使用稍微修改的 Content-Type 標頭。您可以順利地使用下列工具。

Content-Type: multipart/related; type="application/dicom"; boundary=ABCD1234
Content-Type: multipart/related; boundary=ABCD1234
Content-Type: multipart/related

curl --request POST "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420"
--header "Accept: application/dicom+json"
--header "Content-Type: multipart/related; type=\"application/dicom\""
--header "Authorization: Bearer {token value}"
--form "file1=@{path-to-dicoms}/blue-circle.dcm;type=application/dicom"

Store-single-instance

注意

這是一種非標準 API，允許上傳單一 DICOM 檔案，而不需要設定 multipart/related 的 POST。雖然 cURL 可以妥善處理 multipart/related，但此 API 可讓 Postman 之類的工具將檔案上傳至 DICOM 服務。

以下是上傳單一 DICOM 檔案所需的方法。

詳細資料：

路徑：../studies
方法：POST
Headers：
- Accept: application/dicom+json
- Content-Type: application/dicom
- Authorization: Bearer {token value}
本文：
- 包含二進位位元組形式的單一 DICOM 檔案。

curl --location --request POST "{Service URL}/v{version}/studies"
--header "Accept: application/dicom+json"
--header "Content-Type: application/dicom"
--header "Authorization: Bearer {token value}"
--data-binary "@{path-to-dicoms}/green-square.dcm"

使用 multipart/related 更新插入執行個體

注意

這是一種非標準 API，允許使用 multipart/related 來更新插入 DICOM 檔案。

詳細資料：

路徑：../studies
方法：PUT
Headers：
- Accept: application/dicom+json
- Content-Type: multipart/related; type="application/dicom"
- Authorization: Bearer {token value}
本文：
- Content-Type：每個上傳檔案的 application/dicom，以界限值分隔

Content-Type: multipart/related; type="application/dicom"; boundary=ABCD1234
Content-Type: multipart/related; boundary=ABCD1234
Content-Type: multipart/related

curl --location --request PUT "{Service URL}/v{version}/studies"
--header "Accept: application/dicom+json"
--header "Content-Type: multipart/related; type=\"application/dicom\""
--header "Authorization: Bearer {token value}"
--form "file1=@{path-to-dicoms}/red-triangle.dcm;type=application/dicom"
--trace-ascii "trace.txt"

更新插入特定研究的執行個體

注意

這是一種非標準 API，允許使用 multipart/related 將 DICOM 檔案更新插入至指定研究。

詳細資料：

路徑：../studies/{study}
方法：PUT
Headers：
- Accept: application/dicom+json
- Content-Type: multipart/related; type="application/dicom"
- Authorization: Bearer {token value}
本文：
- Content-Type：每個上傳檔案的 application/dicom，以界限值分隔

Content-Type: multipart/related; type="application/dicom"; boundary=ABCD1234
Content-Type: multipart/related; boundary=ABCD1234
Content-Type: multipart/related

curl --request PUT "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420"
--header "Accept: application/dicom+json"
--header "Content-Type: multipart/related; type=\"application/dicom\""
--header "Authorization: Bearer {token value}"
--form "file1=@{path-to-dicoms}/blue-circle.dcm;type=application/dicom"

更新插入單一執行個體

注意

這是一種非標準 API，允許更新插入單一 DICOM 檔案。

使用此方法上傳單一 DICOM 檔案。

詳細資料：

路徑：../studies
方法：PUT
Headers：
- Accept: application/dicom+json
- Content-Type: application/dicom
- Authorization: Bearer {token value}
本文：
- 包含二進位位元組形式的單一 DICOM 檔案。

curl --location --request PUT "{Service URL}/v{version}/studies"
--header "Accept: application/dicom+json"
--header "Content-Type: application/dicom"
--header "Authorization: Bearer {token value}"
--data-binary "@{path-to-dicoms}/green-square.dcm"

擷取 DICOM (WADO)

擷取研究中的所有執行個體

此要求會擷取單一研究中的所有執行個體，並在 multipart/related 位元組集合中傳回這些執行個體。

詳細資料：

路徑：../studies/{study}
方法：GET
Headers：
- Accept: multipart/related; type="application/dicom"; transfer-syntax=*
- Authorization: Bearer {token value}

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420"
--header "Accept: multipart/related; type=\"application/dicom\"; transfer-syntax=*"
--header "Authorization: Bearer {token value}"
--output "suppressWarnings.txt"

這個 cURL 命令會顯示輸出檔案 (suppressWarnings.txt) 中已下載的位元組，但並不是直接的 DICOM 檔案，而是 multipart/related 下載的文字表示法。

擷取研究中所有執行個體的中繼資料

此要求會擷取單一研究內所有執行個體的中繼資料。

詳細資料：

路徑：../studies/{study}/metadata
方法：GET
Headers：
- Accept: application/dicom+json
- Authorization: Bearer {token value}

這個 cURL 命令會顯示輸出檔案 (suppressWarnings.txt) 中已下載的位元組，但並不是直接的 DICOM 檔案，而是 multipart/related 下載的文字表示法。

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/metadata"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

擷取系列中的所有執行個體

此要求會擷取單一系列研究中的所有執行個體，並在 multipart/related 位元組集合中傳回這些執行個體。

詳細資料：

路徑：../studies/{study}/series/{series}
方法：GET
Headers：
- Accept: multipart/related; type="application/dicom"; transfer-syntax=*
- Authorization: Bearer {token value}

這個 cURL 命令會顯示輸出檔案 (suppressWarnings.txt) 中已下載的位元組，但並不是直接的 DICOM 檔案，而是 multipart/related 下載的文字表示法。

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652"
--header "Accept: multipart/related; type=\"application/dicom\"; transfer-syntax=*"
--header "Authorization: Bearer {token value}"
--output "suppressWarnings.txt"

擷取系列內所有執行個體的中繼資料

此要求會擷取單一研究中所有執行個體的中繼資料。

詳細資料：

路徑：../studies/{study}/series/{series}/metadata
方法：GET
Headers：
- Accept: application/dicom+json
- Authorization: Bearer {token value}

curl --request GET "{Service URL}/v{version}/studies1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/metadata"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

擷取一系列研究內的單一執行個體

此要求會擷取單一執行個體，並將它當作 DICOM 格式化的位元組資料流傳回。

詳細資料：

路徑：../studies/{study}/series{series}/instances/{instance}
方法：GET
Headers：
- Accept: application/dicom; transfer-syntax=*
- Authorization: Bearer {token value}

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/instances/1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395"
--header "Accept: application/dicom; transfer-syntax=*"
--header "Authorization: Bearer {token value}"
--output "suppressWarnings.txt"

擷取一系列研究內單一執行個體的中繼資料

此要求會擷取單一研究和系列中單一執行個體的中繼資料。

詳細資料：

路徑：../studies/{study}/series/{series}/instances/{instance}/metadata
方法：GET
Headers：
- Accept: application/dicom+json
- Authorization: Bearer {token value}

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/instances/1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395/metadata"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

從單一執行個體擷取一個或多個畫面格

此要求會從單一執行個體擷取一或多個框架，並在 multipart/related 位元組集合中傳回這些執行個體。您可以傳遞以逗號分隔的框架編號清單來擷取多個框架。所有具有映像的 DICOM 執行個體至少會有一個框架，通常只是與執行個體本身相關聯的映像。

詳細資料：

路徑：../studies/{study}/series{series}/instances/{instance}/frames/1,2,3
方法：GET
Headers：
- Accept: multipart/related; type="application/octet-stream"; transfer-syntax=1.2.840.10008.1.2.1 (預設) 或
- Accept: multipart/related; type="application/octet-stream"; transfer-syntax=* 或
- Accept: multipart/related; type="application/octet-stream"；
- Authorization: Bearer {token value}

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/instances/1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395/frames/1"
--header "Accept: multipart/related; type=\"application/octet-stream\"; transfer-syntax=1.2.840.10008.1.2.1"
--header "Authorization: Bearer {token value}"
--output "suppressWarnings.txt"