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.
Store 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 SOP_CLASS_UID
, SOP_INSTANCE_UID
, STUDY_INSTANCE_UID
, and SERIES_INSTANCE_UID
values are populated from the provided metadata. UIDs must meet these requirements:
- Contain only numeric values separated by periods.
- Contain no protected health information (PHI).
The following samples show how to store an instance in a DICOM store. For
more information, see
projects.locations.datasets.dicomStores.storeInstances
.
Store a DICOM instance
The following samples show how to store a DICOM instance. For more information, see
projects.locations.datasets.dicomStores.storeInstances
.
REST
Before using any of the request data, make the following replacements:
PROJECT_ID
: the ID of your Google Cloud projectLOCATION
: the dataset locationDATASET_ID
: the DICOM store's parent datasetDICOM_STORE_ID
: the DICOM store IDDICOM_INSTANCE_FILE
: the path to a DICOM instance file on your local machine ending in the.dcm
suffix
To send your request, choose one of these options:
curl
Execute the following command:
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
Execute the following command:
$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
Specify storage class to store DICOM instances (Preview)
By default, the projects.locations.datasets.dicomStores.storeInstances
method
stores a DICOM instance in a DICOM store with a standard storage class. You
can set the storage class when you store DICOM objects from your local
machine.
For more information, see
Change DICOM storage class.
The following samples show how to specify the storage class when you store DICOM objects from your local machine.
curl
Use the
projects.locations.datasets.dicomStores.storeInstances
method.
Before using any of the request data, make the following replacements:
PROJECT_ID
: the ID of your Google Cloud projectLOCATION
: the dataset locationDATASET_ID
: the DICOM store's parent datasetDICOM_STORE_ID
: the DICOM store IDDICOM_INSTANCE_FILE
: the path to a DICOM instance file on your local machine ending in the.dcm
suffixSTORAGE_CLASS
: the storage class for the DICOM instance in the DICOM store fromSTANDARD
,NEARLINE
,COLDLINE
, andARCHIVE
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"
If the request is successful, the server returns the response:
<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
Use the
projects.locations.datasets.dicomStores.storeInstances
method.
Before using any of the request data, make the following replacements:
PROJECT_ID
: the ID of your Google Cloud projectLOCATION
: the dataset locationDATASET_ID
: the DICOM store's parent datasetDICOM_STORE_ID
: the DICOM store IDDICOM_INSTANCE_FILE
: the path to a DICOM instance file on your local machine ending in the.dcm
suffixSTORAGE_CLASS
: the storage class for the DICOM instance in the DICOM store fromSTANDARD
,NEARLINE
,COLDLINE
, andARCHIVE
$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
If the request is successful, the server returns the response in JSON format:
<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>
Create DICOM instances from JSON metadata and JPEG images
The Cloud Healthcare API can create DICOM instances using a JSON metadata file and a JPEG file. Create DICOM instances from JSON metadata and JPEG file 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 SOP_CLASS_UID, SOP_INSTANCE_UID, STUDY_INSTANCE_UID, and SERIES_INSTANCE_UID 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":["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"} }]
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_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>
Use 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_INSTANCE_UID/series/SERIES_INSTANCE_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_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
Search for DICOM data
You can search 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
.
REST
Before using any of the request data, make the following replacements:
PROJECT_ID
: the ID of your Google Cloud projectLOCATION
: the dataset locationDATASET_ID
: the DICOM store's parent datasetDICOM_STORE_ID
: the DICOM store ID
To send your request, choose one of these options:
curl
Execute the following command:
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
Execute the following command:
$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
Open the method reference page. The APIs Explorer panel opens on the right side of the page. You can interact with this tool to send requests. Complete any required fields and click Execute.
You should receive a JSON response similar to the following:
Go
Java
Node.js
Python
Search 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.
REST
Before using any of the request data, make the following replacements:
PROJECT_ID
: the ID of your Google Cloud projectLOCATION
: the dataset locationDATASET_ID
: the DICOM store's parent datasetDICOM_STORE_ID
: the DICOM store ID
To send your request, choose one of these options:
curl
Execute the following command:
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
Execute the following command:
$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
Open the method reference page. The APIs Explorer panel opens on the right side of the page. You can interact with this tool to send requests. Complete any required fields and click Execute.
You should receive a JSON response similar to the following:
Go
Java
Node.js
Python
Use 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" } ] }, }, ... ]
Retrieve 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.
Retrieve 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_INSTANCE_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_INSTANCE_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
Retrieve 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_INSTANCE_UID/series/SERIES_INSTANCE_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_INSTANCE_UID/series/SERIES_INSTANCE_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
Retrieve 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_INSTANCE_UID/series/SERIES_INSTANCE_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_INSTANCE_UID/series/SERIES_INSTANCE_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
Retrieve 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.
By default, retrieveMetadata
returns a JSON response. To return an XML response,
pass an Accept: multipart/related; type="application/dicom+xml"
HTTP header in your request.
REST
Before using any of the request data, make the following replacements:
PROJECT_ID
: the ID of your Google Cloud projectLOCATION
: the dataset locationDATASET_ID
: the DICOM store's parent datasetDICOM_STORE_ID
: the DICOM store IDSTUDY_INSTANCE_UID
: the study instance unique identifierSERIES_INSTANCE_UID
: the series instance unique identifierINSTANCE_UID
: the instance unique identifier
To send your request, choose one of these options:
curl
Execute the following command:
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
Execute the following command:
$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
Open the method reference page. The APIs Explorer panel opens on the right side of the page. You can interact with this tool to send requests. Complete any required fields and click Execute.
You should receive a JSON response similar to the following:
Retrieve bulkdata
You can retrieve the raw bytes for a specific bulkdata tag in a stored instance. When retrieving metadata from an instance using Preview methods, BulkDataURIs will be generated for supported bulkdata tags (see Bulkdata definition).
For more information, see projects.locations.datasets.dicomStores.studies.series.instances.bulkdata.retrieveBulkdata
.
The following example will create the request URL directly based on the known
path of a bulkdata tag (without using retrieveMetadata
to get the
BulkDataURI).
curl
To retrieve bulkdata, 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
- The path of the target bulkdata tag
- For a tag (XXXX,XXXX) within a sequence (YYYY,YYYY) at index i, the path would be "YYYYYYYY/i/XXXXXXXX"
- An output filename
- An access token
The following sample shows how to retrieve a DAT file
with a GET
request using curl
.
curl -X GET \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Accept: application/octet-stream; transfer-syntax=*" \ "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/bulkdata/BULKDATA_PATH" \ --output FILENAME.dat
If the request is successful, the DAT file containing raw bytes from the instance is written to your machine.
PowerShell
To retrieve bulkdata, 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
- The path of the target bulkdata tag
- For a tag (XXXX,XXXX) within a sequence (YYYY,YYYY) at index i, the path would be "YYYYYYYY/i/XXXXXXXX"
- An output filename
- An access token
The following sample shows how to retrieve a DAT file with
a GET
request using Windows PowerShell.
$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred"; Accept = "application/octet-stream; transfer-syntax=*" } Invoke-RestMethod ` -Method Get ` -Headers $headers ` -Uri "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/bulkdata/BULKDATA_PATH" -OutFile FILENAME.DAT `
If the request is successful, the DAT file containing raw bytes from the instance is written to your machine.
Use 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
Delete 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
.
REST
Delete the study.
Before using any of the request data, make the following replacements:
PROJECT_ID
: the ID of your Google Cloud projectLOCATION
: the dataset locationDATASET_ID
: the DICOM store's parent datasetDICOM_STORE_ID
: the DICOM store IDSTUDY_INSTANCE_UID
: the study instance unique identifier
To send your request, choose one of these options:
curl
Execute the following command:
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
Execute the following command:
$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
Open the method reference page. The APIs Explorer panel opens on the right side of the page. You can interact with this tool to send requests. Complete any required fields and click Execute.
You should receive a JSON response similar to the following:
Get the status of the long-running operation.
Before using any of the request data, make the following replacements:
PROJECT_ID
: the ID of your Google Cloud projectLOCATION
: the dataset locationDATASET_ID
: the DICOM store's parent datasetOPERATION_ID
: the ID returned from the long-running operation
To send your request, choose one of these options:
curl
Execute the following command:
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
Execute the following command:
$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
Open the method reference page. The APIs Explorer panel opens on the right side of the page. You can interact with this tool to send requests. Complete any required fields and click Execute.
You should receive a JSON response similar to the following:
Go
Java
Node.js
Python
Use 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_INSTANCE_UID
If the request is successful, the server returns an operation which the CLI tool polls until the deletion operation completes.