This page explains how to use the Cloud Healthcare API's implementation of DICOMweb to store and manage DICOM image data.
For more information on how the Cloud Healthcare API implements various DICOMweb REST services, see the DICOM conformance statement.
The DICOMweb implementation in the Cloud Healthcare API only supports REST, not RPC.
Install the Cloud Healthcare API DICOMweb CLI
Several of the samples on this page use the Cloud Healthcare API DICOMweb CLI, an open source tool that simplifies how to interact with DICOMweb servers. The tool provides functionality for storing, retrieving, deleting, and searching for DICOM files. The GitHub page for the tool contains further information such as detailed installation requirements and ways to customize the tool.
The tool runs using Python. For information on how to set up Python on Google Cloud, see Setting up a Python development environment.
After setting up Python, you can install the tool using Pip:
pip install https://github.com/GoogleCloudPlatform/healthcare-api-dicomweb-cli/archive/v1.0.zip
To use the tool, you must authenticate to the Google Cloud servers. You can do so using either of the following methods:
- Setting the
GOOGLE_APPLICATION_CREDENTIALS
environment variable - Authenticating through the Google Cloud CLI using
gcloud auth application-default login
After configuring either of these options, the tool automatically detects your credentials.
Storing DICOM data
Before you can store DICOM data, you need to create a DICOM store.
The Cloud Healthcare API implements the Store transaction RESTful web service when storing DICOM data. For more information, see Store transaction in the Cloud Healthcare API DICOM conformance statement.
You can store DICOM data using the following methods. In both cases, you must pass an application/dicom
Accept
header in your request.
- Store a DICOM instance (typically a
.dcm
file). Store DICOM JSON metadata with JPEG files.
All requests to store DICOM JSON metadata with JPEG files are multipart messages, which are designated by the
multipart/related
portion of theirContent-Type
. Themultipart/related
portion of theContent-Type
indicates that the request is made up of multiple parts of data that are combined after the request completes. Each of these sets of data must be separated using a boundary, as designated by theboundary
portion of theContent-Type
.
The following samples show how to store an instance in a DICOM store. For
more information, see
projects.locations.datasets.dicomStores.storeInstances
.
Storing a DICOM instance
The following samples show how to store a DICOM instance.
curl
To store a DICOM instance, make a POST
request and specify the following information:
- The name of the parent dataset
- The name of the DICOM store
- The DICOM instance file
- An access token
The following sample shows a POST
request using curl
.
curl -X POST \ -H "Content-Type: application/dicom" \ -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 @DCM_FILE.dcm
If the request is successful, the server returns the response in XML format:
<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_UID</Value> </DicomAttribute> <DicomAttribute tag="00081199" vr="SQ" keyword="ReferencedSOPSequence"> <Item number="1"> <DicomAttribute tag="00081150" vr="UI" keyword="ReferencedSOPClassUID"> <Value number="1">SOPClassUID</Value> </DicomAttribute> <DicomAttribute tag="00081155" vr="UI" keyword="ReferencedSOPInstanceUID"> <Value number="1">SOPInstanceUID</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_UID/series/SERIES_UID/instances/INSTANCE_UID</Value> </DicomAttribute> </Item> </DicomAttribute> </NativeDicomModel>
PowerShell
To store a DICOM instance, make a POST
request and specify the following information:
- The name of the parent dataset
- The name of the DICOM store
- The DICOM instance file
- An access token
The following sample shows a POST
request using Windows PowerShell.
$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } Invoke-WebRequest ` -Method Post ` -Headers $headers ` -ContentType: "application/dicom" ` -InFile DCM_FILE.dcm ` -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies" | Select-Object -Expand Content
If the request is successful, the server returns the response in XML format:
<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_UID</Value> </DicomAttribute> <DicomAttribute tag="00081199" vr="SQ" keyword="ReferencedSOPSequence"> <Item number="1"> <DicomAttribute tag="00081150" vr="UI" keyword="ReferencedSOPClassUID"> <Value number="1">SOPClassUID</Value> </DicomAttribute> <DicomAttribute tag="00081155" vr="UI" keyword="ReferencedSOPInstanceUID"> <Value number="1">SOPInstanceUID</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_UID/series/SERIES_UID/instances/INSTANCE_UID</Value> </DicomAttribute> </Item> </DicomAttribute> </NativeDicomModel>
Go
Java
Node.js
Python
Creating DICOM instances from JSON metadata and JPEG images
The Cloud Healthcare API can create DICOM instances using a JSON metadata file and a JPEG image. Create DICOM instances from JSON metadata and JPEG images if you prefer not to do DICOM parsing and serialization yourself, as the Cloud Healthcare API can do these tasks for you.
The HTTP request that stores this data must include the following
in the request's Content-Type
:
- The
multipart/related
media type - The MIME type
application/dicom+json
- A
boundary
separator
The following samples show how to store a JSON metadata file with a JPEG file.
curl
The following sample assumes that you have an existing JPEG image.
Storing a JSON metadata file with a JPEG image comprises three steps:
- Create a file that contains a JSON representation of a DICOM instance containing a JPEG image. A template file is provided below.
Create three boundary files:
opening.file
: Contains the opening boundary for the JSON metadata filemiddle.file
: Contains the middle boundary for the JPEG imageclosing.file
: Contains the closing boundary for all parts of the message
Create a file called
multipart-request.file
by enclosing the JSON metadata file and the JPEG image within the boundary files.
Note the following values that are provided by default in the JSON metadata template file:
- The Transfer Syntax UID (
1.2.840.10008.1.2.4.50
) designates the Transfer Syntax as JPEG Baseline. Most JPEG images are in the JPEG Baseline format. The Photometric Interpretation Value (YBR_FULL_422
) signifies that the image is in color, not grayscale. BulkDataUri
is an arbitrary descriptor for the image, and in the template it is set tojpeg-image
. This value is used when creating the image boundary.
The values for SOPClassUID, SOPInstanceUID, StudyInstanceUID, and SeriesInstanceUID can be any numeric value separated by periods. DICOM uses a hierarchy of identifiers for instances, patients, studies, and series, so choose a logical set of identifiers for these variables.
Replace SOP Class UID with a value from the table of Standard SOP Classes that designates the type of image being stored.
Replace Rows with the vertical height of the JPEG image in pixels. Replace Columns with the horizontal width of the JPEG image in pixels.
Complete the following steps:
Save the following text to a file called
instance.json
, replacing variables where specified.[{ "00020010":{"vr":"UI","Value":["1.2.840.10008.1.2.4.50"]}, "00080005":{"vr":"CS","Value":["ISO_IR 192"]}, "00080016":{"vr":"UI","Value":["SOPClassUID"]}, "00080018":{"vr":"UI","Value":["SOPInstanceUID"]}, "0020000D":{"vr":"UI","Value":["StudyInstanceUID"]}, "0020000E":{"vr":"UI","Value":["SeriesInstanceUID"]}, "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"} }]
To create the opening (for the JSON metadata), middle (for the JPEG image), and closing boundaries, run the following commands:
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
Wrap the JPEG image within middle and closing boundaries. The output file, which you send to the Cloud Healthcare API, is called
multipart-request.file
:cat opening.file instance.json middle.file image.jpg closing.file > multipart-request.file
Make a
POST
request and specify the following information:- The name of the parent dataset
- The name of the DICOM store
- The
multipart-request.file
file - An access token
The following sample shows a POST
request using curl
.
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
If the request is successful, the server returns the response in XML format:
<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_UID</Value> </DicomAttribute> <DicomAttribute tag="00081199" vr="SQ" keyword="ReferencedSOPSequence"> <Item number="1"> <DicomAttribute tag="00081150" vr="UI" keyword="ReferencedSOPClassUID"> <Value number="1">SOPClassUID</Value> </DicomAttribute> <DicomAttribute tag="00081155" vr="UI" keyword="ReferencedSOPInstanceUID"> <Value number="1">SOPInstanceUID</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_UID/series/SERIES_UID/instances/INSTANCE_UID</Value> </DicomAttribute> </Item> </DicomAttribute> </NativeDicomModel>
Using the DICOMweb CLI
The following samples show how to use the Cloud Healthcare API DICOMweb CLI to store one or more DICOM instances. There are more samples available in the DICOMweb CLI GitHub repository.
Storing a single DICOM instance:
dcmweb \ https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb \ store DCM_FILE
If the request is successful, the server returns a response similar to the following sample:
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_UID/series/SERIES_UID TIMESTAMP -- INSTANCE_UID TIMESTAMP -- Transferred SIZE in COUNT files
Storing multiple files in parallel using wildcards:
The following sample shows how to recursively store multiple DICOM
files in parallel from the current working directory. To store the
files in parallel, add the -m
flag.
dcmweb -m \ https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb \ store "./**.dcm"
If the request is successful, the server returns a response similar to the following sample:
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_UID/series/SERIES_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_UID/series/SERIES_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_UID/series/SERIES_UID TIMESTAMP -- INSTANCE_UID ... TIMESTAMP -- Transferred SIZE in COUNT files
Searching for studies, series, instances, and frames
The following samples show an implementation of the Search transaction to search for instances in a DICOM store. For more information, see Search transaction in the Cloud Healthcare API DICOM conformance statement.
The following samples show how to search for instances in a DICOM store. For more information, see
projects.locations.datasets.dicomStores.searchForInstances
.
curl
To search for instances in a DICOM store, make a GET
request
and specify the following information:
- The name of the parent dataset
- The name of the DICOM store
- An access token
The following sample shows a GET
request using curl
.
curl -X GET \ -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/instances"
If the request is successful, the server returns the response in JSON format:
[ { "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" } ] }, }, ... ]
PowerShell
To search for instances in a DICOM store, make a GET
request
and specify the following information:
- The name of the parent dataset
- The name of the DICOM store
- An access token
The following sample shows a GET
request using Windows PowerShell.
$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } 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/instances"
If the request is successful, the server returns the response in JSON format:
[ { "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" } ] }, }, ... ]
Go
Java
Node.js
Python
Searching using DICOM tags
You can refine your searches by appending DICOM tags to your requests in the form of query parameters. For example, you might want to search for studies containing a patient's name.
Like the preceding samples, the following samples show an implementation of the Search transaction to search for studies in a DICOM store. However, these samples show how to search for studies where the patient's name is "Sally Zhang."
The following sample shows a portion of a DICOM instance's metadata where the patient's name is listed:
...
{
"vr": "PN",
"Value": [
{
"Alphabetic": "Sally Zhang"
}
]
}
...
To search for studies in a DICOM store that pertain to the patient, add a
query parameter to your request where you search by the PatientName
DICOM tag.
For a list of supported search parameters in the Cloud Healthcare API,
see the Search transaction
documentation.
curl
To use tags when searching for studies in a DICOM store, make a GET
request
and specify the following information:
- The name of the parent dataset
- The name of the DICOM store
- The query parameter
- An access token
The following sample shows a GET
request using curl
.
curl -X GET \ -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?PatientName=Sally%20Zhang"
If the request is successful, the server returns the response in JSON format:
[ { "00080005": { "vr": "CS", "Value": [ "CODE_STRING" ] }, "00080020": { "vr": "DA", "Value": [ "DATE_TIME" ] }, "00080030": { "vr": "TM", "Value": [ "TIME" ] }, "00080050": { "vr": "SH" }, "00080090": { "vr": "PN", "Value": [ { "Alphabetic": "VALUE" } ] }, "00100010": { "vr": "PN", "Value": [ { "Alphabetic": "Sally Zhang" } ] }, "00100020": { "vr": "LO", "Value": [ "VALUE" ] }, "00100030": { "vr": "DA" }, "00100040": { "vr": "CS", "Value": [ "F" ] }, "0020000D": { "vr": "UI", "Value": [ "STUDY_INSTANCE_UID" ] }, "00200010": { "vr": "SH" } } ]
PowerShell
To use tags when searching for studies in a DICOM store, make a GET
request
and specify the following information:
- The name of the parent dataset
- The name of the DICOM store
- The query parameter
- An access token
The following sample shows a GET
request using Windows PowerShell.
$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } 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?PatientName=Sally%20Zhang"
If the request is successful, the server returns the response in JSON format:
[ { "00080005": { "vr": "CS", "Value": [ "CODE_STRING" ] }, "00080020": { "vr": "DA", "Value": [ "DATE_TIME" ] }, "00080030": { "vr": "TM", "Value": [ "TIME" ] }, "00080050": { "vr": "SH" }, "00080090": { "vr": "PN", "Value": [ { "Alphabetic": "VALUE" } ] }, "00100010": { "vr": "PN", "Value": [ { "Alphabetic": "Sally Zhang" } ] }, "00100020": { "vr": "LO", "Value": [ "VALUE" ] }, "00100030": { "vr": "DA" }, "00100040": { "vr": "CS", "Value": [ "F" ] }, "0020000D": { "vr": "UI", "Value": [ "STUDY_INSTANCE_UID" ] }, "00200010": { "vr": "SH" } } ]
Go
Java
Node.js
Python
Using the DICOMweb CLI
The following sample shows how to use the Cloud Healthcare API DICOMweb CLI to search for instances in a DICOM store. There are more samples, including how to filter your search, available in the DICOMweb CLI GitHub repository.
dcmweb \ https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb \ search instances
If the request is successful, the server returns the response in JSON format:
[ { "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" } ] }, }, ... ]
Retrieving DICOM data
The Cloud Healthcare API implements the Retrieve transaction for retrieving studies, series, instances, and frames in a DICOM store.
For more information, see Retrieve transaction in the Cloud Healthcare API DICOM conformance statement.
Retrieving a study
The following samples show how to retrieve a study. For more information, see DICOM study/series/instances in the Cloud Healthcare API DICOM conformance statement.
When specifying the output
file, use an extension like .multipart
. Then parse the multipart file to
get the individual series and instances in the study.
For more information, see
projects.locations.datasets.dicomStores.studies.retrieveStudy
.
curl
To retrieve a study, make a GET
request and specify the following information:
- The name of the parent dataset
- The name of the DICOM store
- The study unique identifier (UID)
- An output file
- An access token
The following sample shows a GET
request using curl
.
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_UID" --output FILENAME.multipart
If the request is successful, the DICOM file is written to your machine.
PowerShell
To retrieve a study, make a GET
request and specify the following information:
- The name of the parent dataset
- The name of the DICOM store
- The study unique identifier (UID)
- An output file
- An access token
The following sample shows a GET
request using Windows PowerShell.
$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_UID" | Select-Object -Expand Content -OutFile FILENAME.multipart `
If the request is successful, the DICOM file is written to your machine.
Go
Java
Node.js
Python
Retrieving an instance
The following samples show how to retrieve an instance. For more information, see DICOM instances in the Cloud Healthcare API DICOM conformance statement.
If you are retrieving an instance, you can avoid having to parse multipart
boundaries by using the Accept: application/dicom
HTTP header. Adding
transfer-syntax=*
avoids transcoding by returning the file in the format it
was originally stored in.
For more information, see projects.locations.datasets.dicomStores.studies.series.instances.retrieveInstance
.
curl
To retrieve an instance, make a GET
request and specify the following information:
- The name of the parent dataset
- The name of the DICOM store
- The study unique identifier (UID)
- The series UID, the instance UID
- An output filename
- An access token
The following sample shows a GET
request using curl
.
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_UID/series/SERIES_UID/instances/INSTANCE_UID" --output FILENAME.dcm
If the request is successful, the DICOM file is written to your machine.
PowerShell
To retrieve an instance, make a GET
request and specify the following information:
- The name of the parent dataset
- The name of the DICOM store
- The study unique identifier (UID)
- The series UID
- The instance UID
- An output filename
- An access token
The following sample shows a GET
request using Windows PowerShell.
$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_UID/series/SERIES_UID/instances/INSTANCE_UID" -OutFile FILENAME.dcm `
If the request is successful, the DICOM file is written to your machine.
Go
Java
Node.js
Python
Retrieving consumer image formats
The following samples show how to retrieve a consumer imaging format like JPEG or PNG using the Cloud Healthcare API implementation of Rendered Resources. For more information, see Rendered resources in the Cloud Healthcare API DICOM conformance statement.
For more information, see
projects.locations.datasets.dicomStores.studies.series.instances.retrieveRendered
.
curl
To retrieve an image, make a GET
request and specify the following information:
- The name of the parent dataset
- The name of the DICOM store
- The study unique identifier (UID)
- The series UID
- The instance UID
- An output filename
- An access token
The following sample shows how to retrieve a PNG image
with a GET
request using curl
.
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_UID/series/SERIES_UID/instances/INSTANCE_UID/rendered" --output FILENAME.png
If the request is successful, the PNG file is written to your machine.
PowerShell
To retrieve an image, make a GET
request and specify the following information:
- The name of the parent dataset
- The name of the DICOM store
- The study unique identifier (UID)
- The series UID
- The instance UID
- An output filename
- An access token
The following sample shows how to retrieve a PNG image with
a GET
request using Windows PowerShell.
$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_UID/series/SERIES_UID/instances/INSTANCE_UID/rendered" -OutFile FILENAME.png `
If the request is successful, the PNG file is written to your machine.
Go
Java
Node.js
Python
Retrieving metadata
You can retrieve the metadata for all instances in a studies or series. The following sample shows how to retrieve the metadata for an instance. For more information, see Metadata resources in the Cloud Healthcare API DICOM conformance statement.
For more information, see projects.locations.datasets.dicomStores.studies.series.instances.retrieveMetadata
.
When you call retrieveMetadata
, the method returns the same set of fields
that are returned when you search for an instance
with the includefield=all
query parameter. If your application is
latency-sensitive and you want to retrieve the
metadata for a specific set of fields (rather than all fields), don't call
retrieveMetadata
. Instead, call
one of the searchForInstances
methods and specify the fields. The response
will be a smaller set of fields, and a smaller set of fields is helpful for
latency-sensitive applications.
curl
To retrieve the metadata for an instance with bulk data removed, make a GET
request and specify the following information:
- The name of the parent dataset
- The name of the DICOM store
- The study unique identifier (UID)
- The series UID
- The instance UID
- An access token
The following sample shows a GET
request using curl
.
curl -X GET \ -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/STUDY_UID/series/SERIES_UID/instances/INSTANCE_UID/metadata"
If the request is successful, the response contains the metadata for the DICOM attributes in the instance in JSON format.
[ { "00020002": { "vr": "UI", "Value": [ "UNIQUE_IDENTIFIER" ] }, "00020003": { "vr": "UI", "Value": [ "UNIQUE_IDENTIFIER" ] }, "00020010": { "vr": "UI", "Value": [ "UNIQUE_IDENTIFIER" ] }, "00020012": { "vr": "UI", "Value": [ "UNIQUE_IDENTIFIER" ] }, "00020013": { "vr": "SH", "Value": [ "OFFIS_DCMTK_" ] }, "00080016": { "vr": "UI", "Value": [ "UNIQUE_IDENTIFIER" ] }, ... ]
PowerShell
To retrieve the metadata for an instance with bulk data removed, make a GET
request and specify the following information:
- The name of the parent dataset
- The name of the DICOM store
- The study unique identifier (UID)
- The series UID
- The instance UID
- An access token
The following sample shows a GET
request using Windows PowerShell.
$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } 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_UID/series/SERIES_UID/instances/INSTANCE_UID/metadata"
If the request is successful, the response contains the metadata for the DICOM attributes in the instance in JSON format:
[ { "00020002": { "vr": "UI", "Value": [ "UNIQUE_IDENTIFIER" ] }, "00020003": { "vr": "UI", "Value": [ "UNIQUE_IDENTIFIER" ] }, "00020010": { "vr": "UI", "Value": [ "UNIQUE_IDENTIFIER" ] }, "00020012": { "vr": "UI", "Value": [ "UNIQUE_IDENTIFIER" ] }, "00020013": { "vr": "SH", "Value": [ "OFFIS_DCMTK_" ] }, "00080016": { "vr": "UI", "Value": [ "UNIQUE_IDENTIFIER" ] }, ... ]
Using the DICOMweb CLI
The following sample shows how to use the Cloud Healthcare API DICOMweb CLI to retrieve all instances in a DICOM store and save them to your machine in the current working directory. There are more samples available in the DICOMweb CLI GitHub repository.
dcmweb \ https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb \ retrieve
If the request is successful, the server returns a response similar to the following and the DICOM files are written to your machine:
TIMESTAMP -- Saving files into ./ TIMESTAMP -- Transferred SIZE in COUNT files
Deleting a study, series, or instance
The Cloud Healthcare API implements a proprietary web service for deleting DICOM studies, series, and instances. This service is not part of the DICOMweb standard services. For more information, see the Delete section in the Cloud Healthcare API DICOM conformance statement.
Deletion requests for studies and series return a long-running operation. After the operation completes, all instances in the study or series are deleted.
Deletion requests for instances do not return a long-running operation, instead they return an empty response body like the following:
{}
The following samples show how to delete a DICOM study. For more information,
see
projects.locations.datasets.dicomStores.studies.delete
.
curl
To delete a DICOM study, make a DELETE
request and specify the following information:
- The name of the parent dataset
- The name of the DICOM store
- The study's unique identifier (UID)
- An access token
The following sample shows how to delete a study with a DELETE
request
using curl
.
curl -X DELETE \ -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/STUDY_UID"
If the request is successful, the server returns the response in JSON format:
{ "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" }
The response contains an operation name. To track the status of the operation,
you can use the
Operation get
method:
curl -X GET \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
If the request is successful, the server returns a response with the status of the operation in JSON format:
{ "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata", "apiMethodName": "google.cloud.healthcare.v1.dicomweb.DicomWebService.DeleteStudy", "createTime": "CREATE_TIME", "endTime": "END_TIME", "logsUrl": "https://console.cloud.google.com/logs/query/CLOUD_LOGGING_URL", }, "done": true, "response": { "@type": "type.googleapis.com/google.protobuf.Empty", } }
PowerShell
To delete a DICOM study, make a DELETE
request and specify the following information:
- The name of the parent dataset
- The name of the DICOM store
- The study's unique identifier (UID)
- An access token
The following sample shows how to delete a study with a DELETE
request using
Windows PowerShell.
$cred = gcloud auth application-default 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_UID" | Select-Object -Expand Content
If the request is successful, the server returns the response in JSON format:
{ "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" }
The response contains an operation name. To track the status of the operation,
you can use the
Operation get
method:
$cred = gcloud auth application-default 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 Content
If the request is successful, the server returns a response with the status of the operation in JSON format:
{ "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata", "apiMethodName": "google.cloud.healthcare.v1.dicomweb.DicomWebService.DeleteStudy", "createTime": "CREATE_TIME", "endTime": "END_TIME", "logsUrl": "https://console.cloud.google.com/logs/query/CLOUD_LOGGING_URL", }, "done": true, "response": { "@type": "type.googleapis.com/google.protobuf.Empty", } }
Go
Java
Node.js
Python
Using the DICOMweb CLI
The following sample shows how to use the Cloud Healthcare API DICOMweb CLI to delete a study:
dcmweb \ https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb \ delete studies/STUDY_UID
If the request is successful, the server returns an operation which the CLI tool polls until the deletion operation completes.