Store healthcare data with curl and PowerShell

This page shows you how to use the Cloud Healthcare API and curl or PowerShell to complete the following tasks:

  1. Create a Cloud Healthcare API dataset.
  2. Create one of the following data stores inside the dataset:
    • Digital Imaging and Communications in Medicine (DICOM) store
    • Fast Healthcare Interoperability Resources (FHIR) store
    • Health Level Seven International Version 2 (HL7v2) store
  3. Store and inspect a particular type of medical data in the DICOM, FHIR, or HL7v2 store.

If you're only interested in working with one type of data store, you can skip directly to that section of the quickstart after completing the steps in Before you begin and Create a dataset.

Before you begin

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  5. Make sure that billing is enabled for your Google Cloud project.

  6. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  7. Use the Google Cloud CLI to test your authentication environment. Check that the following command outputs a text string without errors:
    gcloud auth application-default print-access-token

Create a dataset

Datasets contain data stores, and data stores contain healthcare data. To use the Cloud Healthcare API, you must create at least one dataset.

The following sample shows how to create a dataset named my-dataset in the us-central1 region. You use the dataset throughout this quickstart to create DICOM stores, FHIR stores, and HL7v2 stores.

REST

Create a dataset using the projects.locations.datasets.create method.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: the ID of the Google Cloud project that you created or selected in Before you begin

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/json; charset=utf-8" \
-d "" \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/datasets?datasetId=my-dataset"

PowerShell

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/datasets?datasetId=my-dataset" | 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.

The output is the result from a long-running operation that runs when you create a dataset. Long-running operations are returned when method calls might take a substantial amount of time to complete. Creating a dataset is usually a quick operation, so the output is returned almost immediately.

To complete this quickstart, choose from one of the following sections:

Store and view a DICOM instance

This section shows how to complete the following tasks:

  1. Create a DICOM store.
  2. Store a DICOM instance in the DICOM store.
  3. View the DICOM instance's metadata.

The Cloud Healthcare API implements the DICOMweb standard to store and access medical imaging data.

Create a DICOM store

DICOM stores exist inside datasets and hold DICOM instances. The following sample shows how to create a DICOM store named my-dicom-store.

REST

Create a DICOM store using the projects.locations.datasets.dicomStores.create method.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: the ID of the Google Cloud project that you created or selected in Before you begin

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/json; charset=utf-8" \
-d "" \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/dicomStores?dicomStoreId=my-dicom-store"

PowerShell

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/dicomStores?dicomStoreId=my-dicom-store" | 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:

Store a DICOM instance

  1. Download the sample DICOM instance file to your machine. The file contains a de-identified patient X-ray.

    curl

    curl -O https://cloud.google.com/healthcare-api/docs/resources/dicom_00000001_000.dcm
    

    PowerShell

    Invoke-WebRequest -Uri "https://cloud.google.com/healthcare-api/docs/resources/dicom_00000001_000.dcm" -OutFile $pwd/dicom_00000001_000.dcm
    
  2. Store the DICOM instance using the dicomStores.storeInstances method. This quickstart assumes you're running the command in the same directory where you downloaded the DICOM instance.

    REST

    Before using any of the request data, make the following replacements:

    • PROJECT_ID: the ID of the Google Cloud project that you created or selected in Before you begin

    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_00000001_000.dcm \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/dicomStores/my-dicom-store/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_00000001_000.dcm `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/dicomStores/my-dicom-store/dicomWeb/studies" | Select-Object -Expand Content

    The output is the following XML response. In this output:

    • PROJECT_ID, us-central1, my-dataset, my-dicom-store: the values you provided when running the command
    • SOPClassUID: uniquely identifies the Service-Object Pair (SOP) class
    • SOPInstanceUID: uniquely identifies the Service-Object Pair (SOP) instance
    • STUDY_UID: uniquely identifies the study instance
    • SERIES_UID: uniquely identifies the series instance
    • INSTANCE_UID: uniquely identifies the instance

View DICOM instance metadata

REST

View the metadata for the instance using the dicomStores.searchForInstances method.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: the ID of the Google Cloud project that you created or selected in Before you begin

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/us-central1/datasets/my-dataset/dicomStores/my-dicom-store/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/us-central1/datasets/my-dataset/dicomStores/my-dicom-store/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:

After storing and viewing the DICOM instance in the Cloud Healthcare API, continue to Clean up to avoid incurring charges to your Google Cloud account for the resources used in this page.

For more information on working with DICOM data, see What's next.

Store and view FHIR resources

This section shows how to complete the following tasks:

  1. Create a FHIR store.
  2. Store a FHIR resource in the FHIR store.
  3. View the FHIR resource's data.

The Cloud Healthcare API implements the FHIR standard to store and access FHIR data.

Create a FHIR store

FHIR stores exist inside datasets and contain FHIR resources. The following sample shows how to create a FHIR store named my-fhir-store that uses FHIR version R4.

REST

Create a FHIR store using the projects.locations.datasets.fhirStores.create method.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: the ID of the Google Cloud project that you created or selected in Before you begin

Request JSON body:

{
  "version": "R4"
}

To send your request, choose one of these options:

curl

Save the request body in a file named request.json. Run the following command in the terminal to create or overwrite this file in the current directory:

cat > request.json << 'EOF'
{
  "version": "R4"
}
EOF

Then execute the following command to send your REST request:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/fhirStores?fhirStoreId=my-fhir-store"

PowerShell

Save the request body in a file named request.json. Run the following command in the terminal to create or overwrite this file in the current directory:

@'
{
  "version": "R4"
}
'@  | Out-File -FilePath request.json -Encoding utf8

Then execute the following command to send your REST request:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/fhirStores?fhirStoreId=my-fhir-store" | Select-Object -Expand Content

APIs Explorer

Copy the request body and 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. Paste the request body in this tool, complete any other required fields, and click Execute.

You should receive a JSON response similar to the following:

Store a FHIR resource

REST

Create a Patient resource in the FHIR store using the projects.locations.datasets.fhirStores.fhir.create method.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: the ID of the Google Cloud project that you created or selected in Before you begin

Request JSON body:

{
  "name": [
    {
      "use": "official",
      "family": "Smith",
      "given": [
        "Darcy"
      ]
    }
  ],
  "gender": "female",
  "birthDate": "1970-01-01",
  "resourceType": "Patient"
}

To send your request, choose one of these options:

curl

Save the request body in a file named request.json. Run the following command in the terminal to create or overwrite this file in the current directory:

cat > request.json << 'EOF'
{
  "name": [
    {
      "use": "official",
      "family": "Smith",
      "given": [
        "Darcy"
      ]
    }
  ],
  "gender": "female",
  "birthDate": "1970-01-01",
  "resourceType": "Patient"
}
EOF

Then execute the following command to send your REST request:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/fhir+json" \
-d @request.json \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/fhirStores/my-fhir-store/fhir/Patient"

PowerShell

Save the request body in a file named request.json. Run the following command in the terminal to create or overwrite this file in the current directory:

@'
{
  "name": [
    {
      "use": "official",
      "family": "Smith",
      "given": [
        "Darcy"
      ]
    }
  ],
  "gender": "female",
  "birthDate": "1970-01-01",
  "resourceType": "Patient"
}
'@  | Out-File -FilePath request.json -Encoding utf8

Then execute the following command to send your REST request:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/fhir+json" `
-InFile request.json `
-Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/fhirStores/my-fhir-store/fhir/Patient" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

View FHIR resource contents

REST

View information about the Patient resource using the projects.locations.datasets.fhirStores.fhir.search method.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: the ID of the Google Cloud project that you created or selected in Before you begin

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/us-central1/datasets/my-dataset/fhirStores/my-fhir-store/fhir/Patient"

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/us-central1/datasets/my-dataset/fhirStores/my-fhir-store/fhir/Patient" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "entry": [
    {
      "fullUrl": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/fhirStores/my-fhir-store/fhir/Patient/PATIENT_ID",
      "resource": {
        "birthDate": "1970-01-01",
        "gender": "female",
        "id": "PATIENT_ID",
        "meta": {
          "lastUpdated": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
          "versionId": "MTY5MDQxMDk5ODU1OTkxNTAwMA"
        },
        "name": [
          {
            "family": "Smith",
            "given": [
              "Darcy"
            ],
            "use": "official"
          }
        ],
        "resourceType": "Patient"
      },
      "search": {
        "mode": "match"
      }
    }
  ],
  "link": [
    {
      "relation": "search",
      "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/fhirStores/my-fhir-store/fhir/Patient/?"
    },
    {
      "relation": "first",
      "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/fhirStores/my-fhir-store/fhir/Patient/?"
    },
    {
      "relation": "self",
      "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/fhirStores/my-fhir-store/fhir/Patient/?"
    }
  ],
  "resourceType": "Bundle",
  "total": 1,
  "type": "searchset"
}

After storing and viewing a FHIR resource in the Cloud Healthcare API, continue to Clean up to avoid incurring charges to your Google Cloud account for the resources used in this page.

For more information on working with FHIR data, see What's next.

Store and view an HL7v2 message

This section shows how to complete the following tasks:

  1. Create an HL7v2 store.
  2. Store an HL7v2 message in the HL7v2 store.
  3. View the HL7v2 message data.

The HL7v2 implementation in the Cloud Healthcare API aligns with the HL7v2 standard.

Create an HL7v2 store

HL7v2 stores exist inside datasets and hold HL7v2 messages. The following sample shows how to create an HL7v2 store named my-hl7v2-store.

REST

Create an HL7v2 store using the projects.locations.datasets.hl7V2Stores.create method.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: the ID of the Google Cloud project that you created or selected in Before you begin

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/json; charset=utf-8" \
-d "" \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/hl7V2Stores?hl7V2StoreId=my-hl7v2-store"

PowerShell

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/hl7V2Stores?hl7V2StoreId=my-hl7v2-store" | 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:

Create an HL7v2 message

  1. Download the sample HL7v2 message file to your machine:

    curl

    curl -O https://cloud.google.com/healthcare-api/docs/resources/hl7v2-sample.json
    

    PowerShell

    Invoke-WebRequest -Uri "https://cloud.google.com/healthcare-api/docs/resources/hl7v2-sample.json" -OutFile $pwd/hl7v2-sample.json
    

    The HL7v2 message contains the following information base-64 encoded in the data field of the sample file:

    MSH|^~\&|A|SEND_FACILITY|A|A|20180101000000||TYPE^A|20180101000000|T|0.0|||AA||00|ASCII
    EVN|A00|20180101040000
    PID||14^111^^^^MRN|11111111^^^^MRN~1111111111^^^^ORGNMBR
    
  2. Store the HL7v2 message in the HL7v2 store using the projects.locations.datasets.hl7V2Stores.messages.create method. This quickstart assumes you're running the command in the same directory where you downloaded the HL7v2 message.

    REST

    Before using any of the request data, make the following replacements:

    • PROJECT_ID: the ID of the Google Cloud project that you created or selected in Before you begin

    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/json; charset=utf-8" \
    --data-binary @hl7v2-sample.json \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/hl7V2Stores/my-hl7v2-store/messages"

    PowerShell

    Execute the following command:

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -InFile hl7v2-sample.json `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/hl7V2Stores/my-hl7v2-store/messages" | 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.

    The output is the following. In this output:

    • PROJECT_ID, us-central1, my-dataset, my-hl7v2-store: the values you provided in the method call
    • MESSAGE_ID: an identifier for the HL7v2 message provided by the Cloud Healthcare API. Note the value of MESSAGE_ID. You need this value in the next step.

View HL7v2 message contents

Find the MESSAGE_ID in the response you received when you created the HL7v2 message.

REST

View the HL7v2 message details using the projects.locations.datasets.hl7V2stores.messages.get method.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: the ID of the Google Cloud project that you created or selected in Before you begin
  • HL7V2_MESSAGE_ID: the ID in the response you received when you created the HL7v2 message

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/us-central1/datasets/my-dataset/hl7V2Stores/my-hl7v2-store/messages/HL7V2_MESSAGE_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/us-central1/datasets/my-dataset/hl7V2Stores/my-hl7v2-store/messages/HL7V2_MESSAGE_ID" | 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:

After storing and viewing the HL7v2 message in the Cloud Healthcare API, continue to Clean up to avoid incurring charges to your Google Cloud account for the resources used in this page.

For more information on working with HL7v2 data, see What's next.

Clean up

To avoid incurring charges to your Google Cloud account for the resources used on this page, delete the Google Cloud project with the resources.

If you created a new project for this quickstart, follow the steps in Delete the project. Otherwise, follow the steps in Delete the dataset.

Delete the project

    Delete a Google Cloud project:

    gcloud projects delete PROJECT_ID

Delete the dataset

If you no longer need the dataset created in this quickstart, you can delete it. Deleting a dataset permanently deletes the dataset and any FHIR, HL7v2, or DICOM stores it contains.

REST

Delete the dataset using the projects.locations.datasets.delete method.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: the ID of the Google Cloud project that you created or selected in Before you begin

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/us-central1/datasets/my-dataset"

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/us-central1/datasets/my-dataset" | 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 successful status code (2xx) and an empty response.

How did it go?

What's next

See the following sections for general information on the Cloud Healthcare API and how to perform the tasks in this quickstart using another interface:

DICOM

See the DICOM conformance statement for information on how the Cloud Healthcare API implements the DICOMweb standard.

FHIR

See the FHIR conformance statement for information on how the Cloud Healthcare API implements the FHIR standard.

HL7v2