本頁說明如何使用 Cloud Healthcare API 實作的 DICOMweb,儲存及管理 DICOM 影像資料。
如要進一步瞭解 Cloud Healthcare API 如何導入各種 DICOMweb REST 服務,請參閱 DICOM 符合聲明。
Cloud Healthcare API 中的 DICOMweb 實作僅支援 REST,不支援 RPC。
安裝 Cloud Healthcare API DICOMweb CLI
本頁面的幾個範例會使用 Cloud Healthcare API DICOMweb CLI,這項開放原始碼工具可簡化與 DICOMweb 伺服器的互動方式。這項工具提供儲存、擷取、刪除及搜尋 DICOM 檔案的功能。如需詳細安裝需求和工具自訂方式等進一步資訊,請參閱工具的 GitHub 頁面。
這項工具會使用 Python 執行。如要瞭解如何在 Google Cloud上設定 Python,請參閱「設定 Python 開發環境」。
設定 Python 後,您可以使用 Pip 安裝工具:
pip install https://github.com/GoogleCloudPlatform/healthcare-api-dicomweb-cli/archive/v1.0.zip
如要使用這項工具,必須先向 Google Cloud 伺服器進行驗證。你可以使用下列任一方法:
- 設定
GOOGLE_APPLICATION_CREDENTIALS
環境變數 - 透過 Google Cloud CLI 使用
gcloud auth application-default login
進行驗證
設定任一選項後,工具會自動偵測您的憑證。
儲存 DICOM 資料
您必須先建立 DICOM 儲存庫,才能儲存 DICOM 資料。
儲存 DICOM 資料時,Cloud Healthcare API 會導入 Store 交易 RESTful 網路服務。詳情請參閱 Cloud Healthcare API DICOM 符合聲明中的「儲存交易」。
請使用下列任一方法儲存 DICOM 資料。在要求中加入 application/dicom
Accept
標頭。
- 儲存 DICOM 執行個體:通常是
.dcm
檔案。 使用多部分 (multipart) 訊息儲存多個項目:建構多部分檔案,其中包含以界線分隔的多個資料部分。在要求中,將
Content-Type
設為multipart/related; type=application/dicom; boundary=BOUNDARY
,其中BOUNDARY
是使用者定義的值,代表訊息的不同部分。如要瞭解如何建立多部分訊息,請參閱 RFC 1341。使用多部分郵件儲存下列 DICOM 資料類型:
- 包含多個執行個體的 DICOM 研究或系列。請使用界線分隔每個執行個體。 如需操作說明,請參閱「使用多部分訊息儲存 DICOM 研究或系列」。
- 內含 JPEG 檔案的 DICOM JSON 中繼資料。請使用邊界分隔每組資料。 如需操作說明,請參閱「從 JSON 中繼資料和 JPEG 圖片建立 DICOM 執行個體」。
系統會根據提供的中繼資料填入 SOP_CLASS_UID
、SOP_INSTANCE_UID
、STUDY_INSTANCE_UID
和 SERIES_INSTANCE_UID
值。UID 必須符合下列規定:
- 只能包含以半形句號分隔的數值。
- 不得包含受保護的健康資訊 (PHI)。
下列範例說明如何在 DICOM 儲存庫中儲存執行個體。詳情請參閱projects.locations.datasets.dicomStores.storeInstances
。
儲存 DICOM 執行個體
下列範例說明如何儲存 DICOM 執行個體。詳情請參閱 projects.locations.datasets.dicomStores.storeInstances
。
REST
使用任何要求資料之前,請先替換以下項目:
PROJECT_ID
:您的 Google Cloud 專案 IDLOCATION
:資料集位置DATASET_ID
:DICOM 儲存庫的父項資料集DICOM_STORE_ID
:DICOM 儲存庫 IDDICOM_INSTANCE_FILE
:本機上 DICOM 執行個體檔案的路徑,結尾為.dcm
後置字元
如要傳送要求,請選擇以下其中一個選項:
curl
執行下列指令:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/dicom" \
--data-binary @DICOM_INSTANCE_FILE \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies"
PowerShell
執行下列指令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-InFile DICOM_INSTANCE_FILE `
-Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies" | Select-Object -Expand Content
Go
Java
Node.js
Python
使用多部分訊息儲存 DICOM 研究或系列
下列範例說明如何使用多部分訊息,儲存由多個執行個體組成的 DICOM 研究或系列。
REST
使用任何要求資料之前,請先替換以下項目:
PROJECT_ID
:您的 Google Cloud 專案 IDLOCATION
:資料集位置DATASET_ID
:DICOM 儲存庫的父項資料集DICOM_STORE_ID
:DICOM 儲存庫 IDMULTIPART_FILE
:本機上多部分檔案的路徑。檔案包含多個 DICOM 執行個體,每個執行個體之間以邊界分隔。BOUNDARY
:用於分隔多部分檔案中 DICOM 執行個體的界線
如要傳送要求,請選擇以下其中一個選項:
curl
執行下列指令:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: multipart/related; type=application/dicom; boundary=BOUNDARY" \
--data-binary @MULTIPART_FILE \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies"
PowerShell
執行下列指令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-InFile MULTIPART_FILE `
-Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies" | Select-Object -Expand Content
指定 DICOM 執行個體的儲存空間級別
根據預設,projects.locations.datasets.dicomStores.storeInstances
方法會將 DICOM 執行個體儲存在具有標準儲存空間類別的 DICOM 儲存庫中。從本機儲存 DICOM 物件時,您可以設定儲存空間級別。詳情請參閱「變更 DICOM 儲存空間級別」。
以下範例說明如何從本機儲存 DICOM 物件時指定儲存空間類別。
curl
請使用 projects.locations.datasets.dicomStores.storeInstances
方法。使用任何要求資料之前,請先替換以下項目:
PROJECT_ID
:您的 Google Cloud 專案 IDLOCATION
:資料集位置DATASET_ID
:DICOM 儲存庫的父項資料集DICOM_STORE_ID
:DICOM 儲存庫 IDDICOM_INSTANCE_FILE
:本機上 DICOM 執行個體檔案的路徑,結尾為.dcm
後置字元STORAGE_CLASS
:DICOM 儲存庫中 DICOM 執行個體的儲存空間類別,來自STANDARD
、NEARLINE
、COLDLINE
和ARCHIVE
curl -X POST \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/dicom" \ -H "Storage-Class: STORAGE_CLASS" \ --data-binary @DICOM_INSTANCE_FILE \ "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies"
如果要求成功,伺服器會傳回下列回應:
<NativeDicomModel> <DicomAttribute tag="00081190" vr="UR" keyword="RetrieveURL"> <Value number="1">https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_INSTANCE_UID</Value> </DicomAttribute> <DicomAttribute tag="00081199" vr="SQ" keyword="ReferencedSOPSequence"> <Item number="1"> <DicomAttribute tag="00081150" vr="UI" keyword="ReferencedSOPClassUID"> <Value number="1">SOP_CLASS_UID</Value> </DicomAttribute> <DicomAttribute tag="00081155" vr="UI" keyword="ReferencedSOPInstanceUID"> <Value number="1">SOP_INSTANCE_UID</Value> </DicomAttribute> <DicomAttribute tag="00081190" vr="UR" keyword="RetrieveURL"> <Value number="1">https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_INSTANCE_UID/series/SERIES_INSTANCE_UID/instances/INSTANCE_UID</Value> </DicomAttribute> </Item> </DicomAttribute> </NativeDicomModel>
PowerShell
請使用 projects.locations.datasets.dicomStores.storeInstances
方法。
使用任何要求資料之前,請先替換以下項目:
PROJECT_ID
:您的 Google Cloud 專案 IDLOCATION
:資料集位置DATASET_ID
:DICOM 儲存庫的父項資料集DICOM_STORE_ID
:DICOM 儲存庫 IDDICOM_INSTANCE_FILE
:本機上 DICOM 執行個體檔案的路徑,結尾為.dcm
後置字元STORAGE_CLASS
:DICOM 儲存庫中 DICOM 執行個體的儲存空間類別,來自STANDARD
、NEARLINE
、COLDLINE
和ARCHIVE
$cred = gcloud auth application-default print-access-token $headers = @{ "Authorization" = "Bearer $cred"; "Storage-Class" = "STORAGE_CLASS" } Invoke-WebRequest ` -Method Post ` -Headers $headers ` -ContentType: "application/dicom" ` -InFile DCM_FILE.dcm ` -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies" | Select-Object -Expand Content
如果要求成功,伺服器會以 JSON 格式傳回回應:
<NativeDicomModel> <DicomAttribute tag="00081190" vr="UR" keyword="RetrieveURL"> <Value number="1">https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_INSTANCE_UID</Value> </DicomAttribute> <DicomAttribute tag="00081199" vr="SQ" keyword="ReferencedSOPSequence"> <Item number="1"> <DicomAttribute tag="00081150" vr="UI" keyword="ReferencedSOPClassUID"> <Value number="1">SOP_CLASS_UID</Value> </DicomAttribute> <DicomAttribute tag="00081155" vr="UI" keyword="ReferencedSOPInstanceUID"> <Value number="1">SOP_INSTANCE_UID</Value> </DicomAttribute> <DicomAttribute tag="00081190" vr="UR" keyword="RetrieveURL"> <Value number="1">https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_INSTANCE_UID/series/SERIES_INSTANCE_UID/instances/INSTANCE_UID</Value> </DicomAttribute> </Item> </DicomAttribute> </NativeDicomModel>
從 JSON 中繼資料和 JPEG 圖片建立 DICOM 執行個體
Cloud Healthcare API 可使用 JSON 中繼資料檔案和 JPEG 檔案建立 DICOM 執行個體。如果您不想自行剖析及序列化 DICOM,可以從 JSON 中繼資料和 JPEG 檔案建立 DICOM 執行個體,因為 Cloud Healthcare API 可以為您執行這些工作。
儲存這項資料的 HTTP 要求必須在要求的 Content-Type
中包含下列項目:
multipart/related
媒體類型- MIME 類型
application/dicom+json
boundary
分隔符
下列範例說明如何將 JSON 中繼資料檔案與 JPEG 檔案一併儲存。
curl
以下範例假設您已有 JPEG 圖片。
儲存含有 JPEG 圖片的 JSON 中繼資料檔案包含三個步驟:
- 建立檔案,內含含有 JPEG 圖片的 DICOM 執行個體 JSON 表示法。下方提供範本檔案。
建立三個邊界檔案:
opening.file
:包含 JSON 中繼資料檔案的開頭界線middle.file
:包含 JPEG 圖片的中間邊界closing.file
:包含訊息所有部分的結尾界線
將 JSON 中繼資料檔案和 JPEG 圖片放在邊界檔案內,建立名為
multipart-request.file
的檔案。
請注意 JSON 中繼資料範本檔案中預設提供的下列值:
- 轉移語法 UID (
1.2.840.10008.1.2.4.50
) 會將轉移語法指定為 JPEG 基準。大多數 JPEG 圖片都採用 JPEG Baseline 格式。光度解譯值 (YBR_FULL_422
) 表示圖片為彩色,而非灰階。 BulkDataUri
是圖片的任意描述元,在範本中會設為jpeg-image
。建立圖片邊界時會使用這個值。
SOP_CLASS_UID、SOP_INSTANCE_UID、STUDY_INSTANCE_UID 和 SERIES_INSTANCE_UID 的值可以是任何以半形句號分隔的數值。DICOM 會使用執行個體、病患、研究和系列的 ID 階層,因此請為這些變數選擇一組邏輯 ID。
請將 SOP Class UID 替換為標準 SOP 類別表中的值,該值會指定儲存的影像類型。
將 Rows 替換為 JPEG 圖片的垂直高度 (以像素為單位)。將 Columns 換成 JPEG 圖片的水平寬度 (以像素為單位)。
操作步驟如下:
將下列文字儲存為
instance.json
檔案,並視需要替換變數。[{ "00020010":{"vr":"UI","Value":["1.2.840.10008.1.2.4.50"]}, "00080005":{"vr":"CS","Value":["ISO_IR 192"]}, "00080016":{"vr":"UI","Value":["SOP_CLASS_UID"]}, "00080018":{"vr":"UI","Value":["SOP_INSTANCE_UID"]}, "0020000D":{"vr":"UI","Value":["STUDY_INSTANCE_UID"]}, "0020000E":{"vr":"UI","Value":["SERIES_INSTANCE_UID"]}, "00280002":{"vr":"US","Value":[3]}, "00280004":{"vr":"CS","Value":["YBR_FULL_422"]}, "00280006":{"vr":"US","Value":[0]}, "00280008":{"vr":"IS","Value":[1]}, "00280010":{"vr":"US","Value":[Rows]}, "00280011":{"vr":"US","Value":[Columns]}, "00280100":{"vr":"US","Value":[8]}, "00280101":{"vr":"US","Value":[8]}, "00280102":{"vr":"US","Value":[7]}, "00280103":{"vr":"US","Value":[0]}, "7FE00010":{"vr":"OB","BulkDataURI":"jpeg-image"} }]
如要建立開頭 (適用於 JSON 中繼資料)、中間 (適用於 JPEG 圖片) 和結尾界線,請執行下列指令:
echo -ne "--DICOMwebBoundary\r\nContent-Type: application/dicom+json\r\n\r\n" > opening.file echo -ne "\r\n--DICOMwebBoundary\r\nContent-Location: jpeg-image\r\nContent-Type: image/jpeg; transfer-syntax=1.2.840.10008.1.2.4.50\r\n\r\n" > middle.file echo -ne "\r\n--DICOMwebBoundary--" > closing.file
將 JPEG 圖片包裝在中間和結尾界線內。您傳送至 Cloud Healthcare API 的輸出檔案稱為
multipart-request.file
:cat opening.file instance.json middle.file image.jpg closing.file > multipart-request.file
提出
POST
要求,並指定下列資訊:- 父項資料集的名稱
- DICOM 儲存庫名稱
multipart-request.file
檔案- 存取權杖
以下範例顯示如何使用 curl
發出 POST
要求。
curl -X POST \ -H "Content-Type: multipart/related; type=\"application/dicom+json\"; boundary=DICOMwebBoundary" \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies \ --data-binary @multipart-request.file
如果要求成功,伺服器會以 XML 格式傳回回應:
<NativeDicomModel> <DicomAttribute tag="00081190" vr="UR" keyword="RetrieveURL"> <Value number="1">https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_INSTANCE_UID</Value> </DicomAttribute> <DicomAttribute tag="00081199" vr="SQ" keyword="ReferencedSOPSequence"> <Item number="1"> <DicomAttribute tag="00081150" vr="UI" keyword="ReferencedSOPClassUID"> <Value number="1">SOP_CLASS_UID</Value> </DicomAttribute> <DicomAttribute tag="00081155" vr="UI" keyword="ReferencedSOPInstanceUID"> <Value number="1">SOP_INSTANCE_UID</Value> </DicomAttribute> <DicomAttribute tag="00081190" vr="UR" keyword="RetrieveURL"> <Value number="1">https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_INSTANCE_UID/series/SERIES_INSTANCE_UID/instances/INSTANCE_UID</Value> </DicomAttribute> </Item> </DicomAttribute> </NativeDicomModel>
使用 DICOMweb CLI
下列範例說明如何使用 Cloud Healthcare API DICOMweb CLI 儲存一或多個 DICOM 執行個體。如需更多範例,請前往 DICOMweb CLI GitHub 存放區。
儲存單一 DICOM 執行個體:
dcmweb \ https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb \ store DCM_FILE
如果要求成功,伺服器會傳回類似以下範例的回應:
TIMESTAMP -- DCM_FILE.dcm uploaded as https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_INSTANCE_UID/series/SERIES_INSTANCE_UID TIMESTAMP -- INSTANCE_UID TIMESTAMP -- Transferred SIZE in COUNT files
使用萬用字元平行儲存多個檔案:
以下範例說明如何從目前的工作目錄,以遞迴方式平行儲存多個 DICOM 檔案。如要平行儲存檔案,請新增 -m
旗標。
dcmweb -m \ https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb \ store "./**.dcm"
如果要求成功,伺服器會傳回類似以下範例的回應:
TIMESTAMP -- DCM_FILE_1.dcm uploaded as https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_INSTANCE_UID/series/SERIES_INSTANCE_UID TIMESTAMP -- INSTANCE_UID TIMESTAMP -- DCM_FILE_2.dcm uploaded as https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_INSTANCE_UID/series/SERIES_INSTANCE_UID TIMESTAMP -- INSTANCE_UID TIMESTAMP -- DCM_FILE_3.dcm uploaded as https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_INSTANCE_UID/series/SERIES_INSTANCE_UID TIMESTAMP -- INSTANCE_UID ... TIMESTAMP -- Transferred SIZE in COUNT files
搜尋 DICOM 資料
您可以搜尋研究、系列項目、執行個體和影格。以下範例說明如何實作搜尋交易,在 DICOM 儲存庫中搜尋執行個體。詳情請參閱 Cloud Healthcare API DICOM 符合聲明中的「搜尋交易」。
下列範例說明如何在 DICOM 儲存庫中搜尋執行個體。詳情請參閱 projects.locations.datasets.dicomStores.searchForInstances
。
REST
使用任何要求資料之前,請先替換以下項目:
PROJECT_ID
:您的 Google Cloud 專案 IDLOCATION
:資料集位置DATASET_ID
:DICOM 儲存庫的父項資料集DICOM_STORE_ID
:DICOM 儲存庫 ID
如要傳送要求,請選擇以下其中一個選項:
curl
執行下列指令:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/instances"
PowerShell
執行下列指令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/instances" | Select-Object -Expand Content
APIs Explorer
開啟方法參考頁面。系統會在頁面右側開啟 APIs Explorer 面板。您可以使用這項工具來傳送要求。完成任何必填欄位,然後按一下「執行」。
您應該會收到如下的 JSON 回應:
Go
Java
Node.js
Python
使用 DICOM 標記搜尋
您可以將 DICOM 標記附加至要求,以查詢參數的形式調整搜尋範圍。舉例來說,您可能想搜尋含有患者姓名的研究。
與先前的範例類似,以下範例顯示如何實作「搜尋交易」,在 DICOM 儲存庫中搜尋研究。不過,這些範例說明如何搜尋患者姓名為「Sally Zhang」的研究。
以下範例顯示 DICOM 執行個體的部分中繼資料,其中列出病患姓名:
...
{
"vr": "PN",
"Value": [
{
"Alphabetic": "Sally Zhang"
}
]
}
...
如要搜尋 DICOM 儲存庫中與病患相關的研究,請在要求中加入查詢參數,並依 PatientName
DICOM 標記搜尋。如要查看 Cloud Healthcare API 支援的搜尋參數清單,請參閱「搜尋交易」說明文件。
REST
使用任何要求資料之前,請先替換以下項目:
PROJECT_ID
:您的 Google Cloud 專案 IDLOCATION
:資料集位置DATASET_ID
:DICOM 儲存庫的父項資料集DICOM_STORE_ID
:DICOM 儲存庫 ID
如要傳送要求,請選擇以下其中一個選項:
curl
執行下列指令:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies?PatientName=Sally%20Zhang"
PowerShell
執行下列指令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies?PatientName=Sally%20Zhang" | Select-Object -Expand Content
APIs Explorer
開啟方法參考頁面。系統會在頁面右側開啟 APIs Explorer 面板。您可以使用這項工具來傳送要求。完成任何必填欄位,然後按一下「執行」。
您應該會收到如下的 JSON 回應:
Go
Java
Node.js
Python
使用 DICOMweb CLI
以下範例說明如何使用 Cloud Healthcare API DICOMweb CLI,在 DICOM 存放區中搜尋執行個體。如要查看更多範例 (包括如何篩選搜尋結果),請前往 DICOMweb CLI GitHub 存放區。
dcmweb \ https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb \ search instances
如果要求成功,伺服器會以 JSON 格式傳回回應:
[ { "00080005":{ "vr":"CS", "Value":[ "CODE_STRING" ] }, "00080016":{ "vr":"UI", "Value":[ "UNIQUE_IDENTIFIER" ] }, "00080018":{ "vr":"UI", "Value":[ "UNIQUE_IDENTIFIER" ] }, "00080020":{ "vr":"DA", "Value":[ "DATE_TIME" ] }, "00080030":{ "vr":"TM", "Value":[ "TIME" ] }, "00080060":{ "vr":"CS", "Value":[ "CODE_STRING" ] }, "0008103E":{ "vr":"LO", "Value":[ "LONG_STRING" ] }, "00100010":{ "vr":"PN", "Value":[ { "Alphabetic":"Anonymized" } ] }, }, ... ]
擷取 DICOM 資料
Cloud Healthcare API 會實作「擷取交易」,用於擷取 DICOM Store 中的研究、系列、執行個體和影格。
詳情請參閱 Cloud Healthcare API DICOM 符合聲明中的「擷取交易」。
擷取研究
下列範例說明如何擷取研究。詳情請參閱 Cloud Healthcare API DICOM 符合聲明中的「DICOM 研究/系列/例項」。
指定輸出檔案時,請使用 .multipart
等副檔名。然後剖析多部分檔案,取得研究中的個別序列和執行個體。
詳情請參閱 projects.locations.datasets.dicomStores.studies.retrieveStudy
。
curl
如要擷取研究,請發出 GET
要求並指定下列資訊:
- 父項資料集的名稱
- DICOM 儲存庫名稱
- 研究專屬 ID (UID)
- 輸出檔案
- 存取權杖
以下範例顯示如何使用 curl
發出 GET
要求。
curl -X GET \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Accept: multipart/related; type=application/dicom; transfer-syntax=*" \ "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_INSTANCE_UID" \ --output FILENAME.multipart
如果要求成功,DICOM 檔案會寫入您的電腦。
PowerShell
如要擷取研究,請發出 GET
要求並指定下列資訊:
- 父項資料集的名稱
- DICOM 儲存庫名稱
- 研究專屬 ID (UID)
- 輸出檔案
- 存取權杖
下列範例顯示如何使用 Windows PowerShell 提出 GET
要求。
$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred"; Accept = "multipart/related; type=application/dicom; transfer-syntax=*" } Invoke-WebRequest ` -Method Get ` -Headers $headers ` -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_INSTANCE_UID" | Select-Object -Expand Content -OutFile FILENAME.multipart `
如果要求成功,DICOM 檔案會寫入您的電腦。
Go
Java
Node.js
Python
擷取執行個體
下列範例說明如何擷取執行個體。詳情請參閱 Cloud Healthcare API DICOM 符合聲明中的「DICOM 執行個體」。
如要擷取執行個體,可以使用 Accept: application/dicom
HTTP 標頭,避免剖析多部分界。加入 transfer-syntax=*
可避免轉碼,因為系統會以原始儲存格式傳回檔案。
詳情請參閱 projects.locations.datasets.dicomStores.studies.series.instances.retrieveInstance
。
curl
如要擷取執行個體,請發出 GET
要求並指定下列資訊:
- 父項資料集的名稱
- DICOM 儲存庫名稱
- 研究專屬 ID (UID)
- 系列 UID、執行個體 UID
- 輸出檔案名稱
- 存取權杖
以下範例顯示如何使用 curl
發出 GET
要求。
curl -X GET \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Accept: application/dicom; transfer-syntax=*" \ "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_INSTANCE_UID/series/SERIES_INSTANCE_UID/instances/INSTANCE_UID" \ --output FILENAME.dcm
如果要求成功,DICOM 檔案會寫入您的電腦。
PowerShell
如要擷取執行個體,請發出 GET
要求並指定下列資訊:
- 父項資料集的名稱
- DICOM 儲存庫名稱
- 研究專屬 ID (UID)
- 系列 UID
- 執行個體 UID
- 輸出檔案名稱
- 存取權杖
下列範例顯示如何使用 Windows PowerShell 提出 GET
要求。
$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred"; Accept = "application/dicom; transfer-syntax=*" } Invoke-RestMethod ` -Method Get ` -Headers $headers ` -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_INSTANCE_UID/series/SERIES_INSTANCE_UID/instances/INSTANCE_UID" -OutFile FILENAME.dcm `
如果要求成功,DICOM 檔案會寫入您的電腦。
Go
Java
Node.js
Python
擷取消費者圖片格式
下列範例說明如何使用 Cloud Healthcare API 實作的「已轉譯資源」,擷取 JPEG 或 PNG 等消費者成像格式。詳情請參閱 Cloud Healthcare API DICOM 符合聲明中的「Rendered resources」。
詳情請參閱 projects.locations.datasets.dicomStores.studies.series.instances.retrieveRendered
。
curl
如要擷取圖片,請發出 GET
要求並指定下列資訊:
- 父項資料集的名稱
- DICOM 儲存庫名稱
- 研究專屬 ID (UID)
- 系列 UID
- 執行個體 UID
- 輸出檔案名稱
- 存取權杖
以下範例說明如何使用 curl
,透過 GET
要求擷取 PNG 圖片。
curl -X GET \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Accept: image/png" \ "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_INSTANCE_UID/series/SERIES_INSTANCE_UID/instances/INSTANCE_UID/rendered" \ --output FILENAME.png
如果要求成功,系統會將 PNG 檔案寫入您的電腦。
PowerShell
如要擷取圖片,請發出 GET
要求並指定下列資訊:
- 父項資料集的名稱
- DICOM 儲存庫名稱
- 研究專屬 ID (UID)
- 系列 UID
- 執行個體 UID
- 輸出檔案名稱
- 存取權杖
下列範例說明如何使用 Windows PowerShell,透過 GET
要求擷取 PNG 圖片。
$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred"; Accept = "image/png" } Invoke-RestMethod ` -Method Get ` -Headers $headers ` -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_INSTANCE_UID/series/SERIES_INSTANCE_UID/instances/INSTANCE_UID/rendered" -OutFile FILENAME.png `
如果要求成功,系統會將 PNG 檔案寫入您的電腦。
Go
Java
Node.js
Python
擷取中繼資料
您可以擷取研究或序列中所有執行個體的中繼資料。 下列範例說明如何擷取執行個體的中繼資料。詳情請參閱 Cloud Healthcare API DICOM 符合聲明中的中繼資料資源。
詳情請參閱 projects.locations.datasets.dicomStores.studies.series.instances.retrieveMetadata
。
呼叫 retrieveMetadata
時,這個方法會傳回與搜尋執行個體時傳回的相同欄位集,並使用 includefield=all
查詢參數。如果應用程式對延遲時間很敏感,且您想擷取特定欄位組合 (而非所有欄位) 的中繼資料,請勿呼叫 retrieveMetadata
。請改為呼叫其中一個 searchForInstances
方法,並指定欄位。回應會是較小的欄位集,而較小的欄位集有助於延遲時間敏感型應用程式。
根據預設,retrieveMetadata
會傳回 JSON 回應。如要傳回 XML 回應,請在要求中傳遞 Accept: multipart/related; type="application/dicom+xml"
HTTP 標頭。
REST
使用任何要求資料之前,請先替換以下項目:
PROJECT_ID
:您的 Google Cloud 專案 IDLOCATION
:資料集位置DATASET_ID
:DICOM 儲存庫的父項資料集DICOM_STORE_ID
:DICOM 儲存庫 IDSTUDY_INSTANCE_UID
:研究執行個體的專屬 IDSERIES_INSTANCE_UID
:系列執行個體的專屬 IDINSTANCE_UID
:執行個體專屬 ID
如要傳送要求,請選擇以下其中一個選項:
curl
執行下列指令:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_INSTANCE_UID/series/SERIES_INSTANCE_UID/instances/INSTANCE_UID/metadata"
PowerShell
執行下列指令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_INSTANCE_UID/series/SERIES_INSTANCE_UID/instances/INSTANCE_UID/metadata" | Select-Object -Expand Content
APIs Explorer
開啟方法參考頁面。系統會在頁面右側開啟 APIs Explorer 面板。您可以使用這項工具來傳送要求。完成任何必填欄位,然後按一下「執行」。
您應該會收到如下的 JSON 回應:
擷取大量資料
DICOM 執行個體包含許多資料元素。雖然大多數資料元素都包含少量中繼資料 (例如病患姓名或研究日期),但有些元素可能包含大量資料,又稱為「大量資料」。如要瞭解 Cloud Healthcare API 中的「大量資料」是指哪些資料,請參閱「大量資料定義」。
Cloud Healthcare API 會分別處理這些「大量資料」元素。如要擷取原始值位元組,請使用下列其中一個選項呼叫 projects.locations.datasets.dicomStores.studies.series.instances.bulkdata.retrieveBulkdata
:
直接擷取:如果您知道研究、系列、執行個體和要擷取的特定標記的 ID,可以建構要求網址並直接呼叫
retrieveBulkdata
。 直接擷取是最有效率的方法,因為只需要單一 API 呼叫。透過 DICOM 執行個體中繼資料擷取:擷取執行個體的中繼資料時,回應會包含每個支援的 bulkdata 標記的
BulkDataURI
。您可以使用這個 URI 執行retrieveBulkdata
要求。 這個方法有助於在擷取執行個體前,找出可用的大量資料標記。
下列範例說明如何使用直接擷取功能,大量擷取資料:
REST
使用任何要求資料之前,請先替換以下項目:
PROJECT_ID
:您的 Google Cloud 專案 IDLOCATION
:資料集位置DATASET_ID
:DICOM 儲存庫的父項資料集DICOM_STORE_ID
:DICOM 儲存庫 IDSTUDY_INSTANCE_UID
:研究執行個體的專屬 IDSERIES_INSTANCE_UID
:系列執行個體的專屬 IDINSTANCE_UID
:執行個體專屬 IDBULK_DATA_PATH
:大量資料標記,例如PixelData
的7FE00010
。如果序列 (BBBB,BBBB) 中項目索引 i 的標記為 (AAAA,AAAA),路徑會是BBBBBBBB/i/AAAAAAAA
OUTPUT_FILE_PATH
:本機電腦上的路徑,其中以 DAT 檔案形式儲存大量資料。您必須指定.dat
擴充功能。
如要傳送要求,請選擇以下其中一個選項:
curl
執行下列指令:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
--output OUTPUT_FILE_PATH \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_INSTANCE_UID/series/SERIES_INSTANCE_UID/instances/INSTANCE_UID/bulkdata/BULK_DATA_PATH"
PowerShell
執行下列指令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-OutFile OUTPUT_FILE_PATH `
-Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_INSTANCE_UID/series/SERIES_INSTANCE_UID/instances/INSTANCE_UID/bulkdata/BULK_DATA_PATH"
使用 DICOMweb CLI
以下範例說明如何使用 Cloud Healthcare API DICOMweb CLI,擷取 DICOM 存放區中的所有執行個體,並將其儲存至電腦的目前工作目錄。如需更多範例,請前往 DICOMweb CLI GitHub 存放區。
dcmweb \ https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb \ retrieve
如果要求成功,伺服器會傳回類似下列內容的回應,且 DICOM 檔案會寫入您的電腦:
TIMESTAMP -- Saving files into ./ TIMESTAMP -- Transferred SIZE in COUNT files
刪除研究、系列或執行個體
Cloud Healthcare API 會實作專屬的網路服務,用於刪除 DICOM 研究、系列和執行個體。這項服務不屬於 DICOMweb 標準服務。詳情請參閱 Cloud Healthcare API DICOM 符合聲明中的刪除部分。
研究和序列的刪除要求會傳回長時間執行的作業。 作業完成後,研究或系列中的所有執行個體都會遭到刪除。
執行個體的刪除要求不會傳回長時間執行的作業,而是會傳回空白的回應內容,如下所示:
{}
下列範例說明如何刪除 DICOM 研究。詳情請參閱「projects.locations.datasets.dicomStores.studies.delete
」一文。
REST
刪除研究。
使用任何要求資料之前,請先替換以下項目:
PROJECT_ID
:您的 Google Cloud 專案 IDLOCATION
:資料集位置DATASET_ID
:DICOM 儲存庫的父項資料集DICOM_STORE_ID
:DICOM 儲存庫 IDSTUDY_INSTANCE_UID
:研究執行個體的專屬 ID
如要傳送要求,請選擇以下其中一個選項:
curl
執行下列指令:
curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_INSTANCE_UID"PowerShell
執行下列指令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method DELETE `
-Headers $headers `
-Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_INSTANCE_UID" | Select-Object -Expand ContentAPIs Explorer
開啟方法參考頁面。系統會在頁面右側開啟 APIs Explorer 面板。您可以使用這項工具來傳送要求。完成任何必填欄位,然後按一下「執行」。
您應該會收到如下的 JSON 回應:
取得長時間執行作業的狀態。
使用任何要求資料之前,請先替換以下項目:
PROJECT_ID
:您的 Google Cloud 專案 IDLOCATION
:資料集位置DATASET_ID
:DICOM 儲存庫的父項資料集OPERATION_ID
:長時間執行的作業傳回的 ID
如要傳送要求,請選擇以下其中一個選項:
curl
執行下列指令:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"PowerShell
執行下列指令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" | Select-Object -Expand ContentAPIs Explorer
開啟方法參考頁面。系統會在頁面右側開啟 APIs Explorer 面板。您可以使用這項工具來傳送要求。完成任何必填欄位,然後按一下「執行」。
您應該會收到如下的 JSON 回應:
Go
Java
Node.js
Python
使用 DICOMweb CLI
以下範例說明如何使用 Cloud Healthcare API DICOMweb CLI 刪除研究:
dcmweb \ https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb \ delete studies/STUDY_INSTANCE_UID
如果要求成功,伺服器會傳回作業,CLI 工具會輪詢該作業,直到刪除作業完成為止。