Store healthcare data with curl and PowerShell

Store healthcare data with curl and PowerShell

This page shows you how to use the Cloud Healthcare API and curl or Windows 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 are 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.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Cloud project. Learn how to check if billing is enabled on a project.

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

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

5. Make sure that billing is enabled for your Cloud project. Learn how to check if billing is enabled on a project.

6. Install and initialize the Google Cloud CLI.
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

Tip: Need a command prompt? You can use the Google Cloud Shell. Cloud Shell is a command line environment that already includes the Google Cloud CLI, so you don't need to install it. (The Google Cloud CLI also comes preinstalled on Compute Engine virtual machines.)

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.

Create a dataset using the datasets.create method:

curl

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

Replace PROJECT_ID with the ID of the Google Cloud project that you created or selected in Before you begin.

The response is the following. The response contains an identifier for a long-running operation. Long-running operations are returned when method calls might take a substantial amount of time to complete.

{
  "name": "projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/operations/OPERATION_ID",
}

In this output:

• PROJECT_ID, us-central1, my-dataset: the values that you provided in the method call
• OPERATION_ID: an identifier for the long-running operation provided by the Cloud Healthcare API

To track the status of the operation, use the operations.get method:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/operations/OPERATION_ID"

Replace the following:

• PROJECT_ID: the ID of your Google Cloud project
• OPERATION_ID: the ID returned from the long-running operation

The output is the following. If the response contains "done": true, then the operation is finished. If it doesn't, then the operation is still running; wait a few seconds and then call the operations.get method again.

{
  "name": "projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1.dataset.DatasetService.CreateDataset",
    "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.cloud.healthcare.v1.dataset.Dataset",
    "name": "projects/PROJECT_ID/locations/us-central1/datasets/my-dataset"
  }
}

PowerShell

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

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

Replace PROJECT_ID with the ID of the Google Cloud project that you created or selected in Before you begin.

The response is the following. The response contains an identifier for a long-running operation. Long-running operations are returned when method calls might take a substantial amount of time to complete.

{
  "name": "projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/operations/OPERATION_ID",
}

In this output:

• PROJECT_ID, us-central1, my-dataset: the values that you provided in the method call
• OPERATION_ID: an identifier for the long-running operation provided by the Cloud Healthcare API

To track the status of the operation, use the operations.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/us-central1/datasets/my-dataset/operations/OPERATION_ID" | Select-Object -Expand Content

Replace the following:

• PROJECT_ID: the ID of your Google Cloud project
• OPERATION_ID: the ID returned from the long-running operation

The output is the following. If the response contains "done": true, then the operation is finished. If it doesn't, then the operation is still running; wait a few seconds and then call the operations.get method again.

{
  "name": "projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1.dataset.DatasetService.CreateDataset",
    "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.cloud.healthcare.v1.dataset.Dataset",
    "name": "projects/PROJECT_ID/locations/us-central1/datasets/my-dataset"
  }
}

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

• Store and view a DICOM instance
• Store and view FHIR resources
• Store and view an HL7v2 message

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. Create a DICOM store using the dicomStores.create method:

curl

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

Replace PROJECT_ID with the ID of the Google Cloud project that you created or selected in Before you begin.

The output is the following:

{
  "name": "projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/dicomStores/my-dicom-store"
}

PowerShell

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

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

Replace PROJECT_ID with the ID of the Google Cloud project that you created or selected in Before you begin.

The output is the following:

{
  "name": "projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/dicomStores/my-dicom-store"
}

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 that you are running the command from the same directory where you downloaded the DICOM instance.

   curl

   curl -X POST \
       -H "Content-Type: application/dicom" \
       -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
       --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
   

   Replace PROJECT_ID with the ID of the Google Cloud project that you created or selected in Before you begin.

   The output is the following in XML format:

   <NativeDicomModel>
     <DicomAttribute tag="00081190" vr="UR" keyword="RetrieveURL">
       <Value number="1">https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/dicomStores/my-dicom-store/dicomWeb/studies/1.3.6.1.4.1.11129.5.5.111396399361969898205364400549799252857604</Value>
     </DicomAttribute>
     <DicomAttribute tag="00081199" vr="SQ" keyword="ReferencedSOPSequence">
       <Item number="1">
         <DicomAttribute tag="00081150" vr="UI" keyword="ReferencedSOPClassUID">
           <Value number="1">1.2.840.10008.5.1.4.1.1.7</Value>
         </DicomAttribute>
         <DicomAttribute tag="00081155" vr="UI" keyword="ReferencedSOPInstanceUID">
           <Value number="1">1.3.6.1.4.1.11129.5.5.153751009835107614666834563294684339746480</Value>
         </DicomAttribute>
         <DicomAttribute tag="00081190" vr="UR" keyword="RetrieveURL">
           <Value number="1">https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/dicomStores/my-dicom-store/dicomWeb/studies/1.3.6.1.4.1.11129.5.5.111396399361969898205364400549799252857604/series/1.3.6.1.4.1.11129.5.5.195628213694300498946760767481291263511724/instances/1.3.6.1.4.1.11129.5.5.153751009835107614666834563294684339746480</Value>
         </DicomAttribute>
       </Item>
     </DicomAttribute>
   </NativeDicomModel>
   

   PowerShell

   $cred = gcloud auth application-default print-access-token
   $headers = @{ Authorization = "Bearer $cred" }
   
   Invoke-WebRequest `
     -Method Post `
     -Headers $headers `
     -ContentType: "application/dicom" `
     -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
   

   Replace PROJECT_ID with the ID of the Google Cloud project that you created or selected in Before you begin.

   The output is the following in XML format:

   <NativeDicomModel>
     <DicomAttribute tag="00081190" vr="UR" keyword="RetrieveURL">
       <Value number="1">https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/dicomStores/my-dicom-store/dicomWeb/studies/1.3.6.1.4.1.11129.5.5.111396399361969898205364400549799252857604</Value>
     </DicomAttribute>
     <DicomAttribute tag="00081199" vr="SQ" keyword="ReferencedSOPSequence">
       <Item number="1">
         <DicomAttribute tag="00081150" vr="UI" keyword="ReferencedSOPClassUID">
           <Value number="1">1.2.840.10008.5.1.4.1.1.7</Value>
         </DicomAttribute>
         <DicomAttribute tag="00081155" vr="UI" keyword="ReferencedSOPInstanceUID">
           <Value number="1">1.3.6.1.4.1.11129.5.5.153751009835107614666834563294684339746480</Value>
         </DicomAttribute>
         <DicomAttribute tag="00081190" vr="UR" keyword="RetrieveURL">
           <Value number="1">https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/dicomStores/my-dicom-store/dicomWeb/studies/1.3.6.1.4.1.11129.5.5.111396399361969898205364400549799252857604/series/1.3.6.1.4.1.11129.5.5.195628213694300498946760767481291263511724/instances/1.3.6.1.4.1.11129.5.5.153751009835107614666834563294684339746480</Value>
         </DicomAttribute>
       </Item>
     </DicomAttribute>
   </NativeDicomModel>
   

View DICOM instance metadata

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

curl

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/dicomStores/my-dicom-store/dicomWeb/instances"

Replace PROJECT_ID with the ID of the Google Cloud project that you created or selected in Before you begin.

The output is the following:

[
  {
    "00080016": {
      "vr": "UI",
      "Value": [
        "1.2.840.10008.5.1.4.1.1.7"
      ]
    },
    "00080018": {
      "vr": "UI",
      "Value": [
        "1.3.6.1.4.1.11129.5.5.153751009835107614666834563294684339746480"
      ]
    },
    "00080060": {
      "vr": "CS",
      "Value": [
        "DX"
      ]
    },
    "00100020": {
      "vr": "LO",
      "Value": [
        "1"
      ]
    },
    "00100040": {
      "vr": "CS",
      "Value": [
        "M"
      ]
    },
    "0020000D": {
      "vr": "UI",
      "Value": [
        "1.3.6.1.4.1.11129.5.5.111396399361969898205364400549799252857604"
      ]
    },
    "0020000E": {
      "vr": "UI",
      "Value": [
        "1.3.6.1.4.1.11129.5.5.195628213694300498946760767481291263511724"
      ]
    },
    "00280010": {
      "vr": "US",
      "Value": [
        1024
      ]
    },
    "00280011": {
      "vr": "US",
      "Value": [
        1024
      ]
    },
    "00280100": {
      "vr": "US",
      "Value": [
        8
      ]
    }
  }
]

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

Replace PROJECT_ID with the ID of the Google Cloud project that you created or selected in Before you begin.

The output is the following:

[
  {
    "00080016": {
      "vr": "UI",
      "Value": [
        "1.2.840.10008.5.1.4.1.1.7"
      ]
    },
    "00080018": {
      "vr": "UI",
      "Value": [
        "1.3.6.1.4.1.11129.5.5.153751009835107614666834563294684339746480"
      ]
    },
    "00080060": {
      "vr": "CS",
      "Value": [
        "DX"
      ]
    },
    "00100020": {
      "vr": "LO",
      "Value": [
        "1"
      ]
    },
    "00100040": {
      "vr": "CS",
      "Value": [
        "M"
      ]
    },
    "0020000D": {
      "vr": "UI",
      "Value": [
        "1.3.6.1.4.1.11129.5.5.111396399361969898205364400549799252857604"
      ]
    },
    "0020000E": {
      "vr": "UI",
      "Value": [
        "1.3.6.1.4.1.11129.5.5.195628213694300498946760767481291263511724"
      ]
    },
    "00280010": {
      "vr": "US",
      "Value": [
        1024
      ]
    },
    "00280011": {
      "vr": "US",
      "Value": [
        1024
      ]
    },
    "00280100": {
      "vr": "US",
      "Value": [
        8
      ]
    }
  }
]

Now that you've stored and viewed a 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 specification standard to store and access FHIR data.

Create a FHIR store

FHIR stores exist inside datasets and hold FHIR resources. Create a FHIR store using the fhirStores.create method:

curl

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

Replace PROJECT_ID with the ID of the Google Cloud project that you created or selected in Before you begin.

The output is the following:

{
  "name": "projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/fhirStores/my-fhir-store",
  "version": "R4"
}

PowerShell

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

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

Replace PROJECT_ID with the ID of the Google Cloud project that you created or selected in Before you begin.

The output is the following:

{
  "name": "projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/fhirStores/my-fhir-store",
  "version": "R4"
}

Store a FHIR resource

1. Download the sample JSON FHIR resource file. The file contains basic data for a Patient resource.

   curl

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

   PowerShell

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

2. Store the Patient resource using the fhir.create method. This quickstart assumes that you are running the command from the same directory where you downloaded the Patient resource.

   curl

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

   Replace PROJECT_ID with the ID of the Google Cloud project that you created or selected in Before you begin.

   The output is the following:

   {
     "birthDate": "1970-01-01",
     "gender": "female",
     "id": "PATIENT_ID",
     "meta": {
       "lastUpdated": "LAST_UPDATED",
       "versionId": "VERSION_ID"
     },
     "name": [
       {
         "family": "Smith",
         "given": [
           "Darcy"
         ],
         "use": "official"
       }
     ],
     "resourceType": "Patient"
   }
   

   PowerShell

   $cred = gcloud auth application-default print-access-token
   $headers = @{ Authorization = "Bearer $cred" }
   
   Invoke-WebRequest `
     -Method Post `
     -Headers $headers `
     -ContentType: "application/dicom" `
     -InFile Patient.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
   

   Replace PROJECT_ID with the ID of the Google Cloud project that you created or selected in Before you begin.

   The output is the following:

   {
     "birthDate": "1970-01-01",
     "gender": "female",
     "id": "PATIENT_ID",
     "meta": {
       "lastUpdated": "LAST_UPDATED",
       "versionId": "VERSION_ID"
     },
     "name": [
       {
         "family": "Smith",
         "given": [
           "Darcy"
         ],
         "use": "official"
       }
     ],
     "resourceType": "Patient"
   }
   

View FHIR resource contents

View information about the Patient resource using the fhir.search method. The following samples show how to search for all Patient resources with the last name "Smith".

curl

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/fhirStores/my-fhir-store/fhir/Patient?family:exact=Smith"

Replace PROJECT_ID with the ID of the Google Cloud project that you created or selected in Before you begin.

The server returns the response as a FHIR Bundle in JSON format. The Bundle.type is searchset and the search results are entries in the Bundle.entry array. In this example, the request returns a single Patient resource including the data inside that resource:

{
  "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": "LAST_UPDATED",
          "versionId": "VERSION_ID"
        },
        "name": [
          {
            "family": "Smith",
            "given": [
              "Darcy"
            ],
            "use": "official"
          }
        ],
        "resourceType": "Patient"
      },
      "search": {
        "mode": "match"
      }
    }
  ],
  "link": [
    {
      "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/fhirStores/my-fhir-store/fhir/Patient/?family%3Aexact=Smith"
    }
  ],
  "resourceType": "Bundle",
  "total": 1,
  "type": "searchset"
}

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/us-central1/datasets/my-dataset/fhirStores/my-fhir-store/fhir/RESOURCE_TYPE?family:exact=Smith" | ConvertTo-Json

Replace PROJECT_ID with the ID of the Google Cloud project that you created or selected in Before you begin.

The server returns the response as a FHIR Bundle in JSON format. The Bundle.type is searchset and the search results are entries in the Bundle.entry array. In this example, the request returns a single Patient resource including the data inside that resource:

{
  "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": "LAST_UPDATED",
          "versionId": "VERSION_ID"
        },
        "name": [
          {
            "family": "Smith",
            "given": [
              "Darcy"
            ],
            "use": "official"
          }
        ],
        "resourceType": "Patient"
      },
      "search": {
        "mode": "match"
      }
    }
  ],
  "link": [
    {
      "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/fhirStores/my-fhir-store/fhir/Patient/?family%3Aexact=Smith"
    }
  ],
  "resourceType": "Bundle",
  "total": 1,
  "type": "searchset"
}

Now that you've stored and viewed 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's 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. Create an HL7v2 store using the hl7V2Stores.create method:

curl

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

Replace PROJECT_ID with the ID of the Google Cloud project that you created or selected in Before you begin.

The output is the following:

{
  "name": "projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/hl7V2Stores/my-hl7v2-store"
}

PowerShell

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

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

Replace PROJECT_ID with the ID of the Google Cloud project that you created or selected in Before you begin.

The output is the following:

{
  "name": "projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/hl7V2Stores/my-hl7v2-store"
}

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 basic information, where it is 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 using the messages.create method. This quickstart assumes that you are running the command from the same directory where you downloaded the HL7v2 message file.

   curl

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth application-default 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"
   

   Replace PROJECT_ID with the ID of the Google Cloud project that you created or selected in Before you begin.

   The output is the following:

   {
     "name": "projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/hl7V2Stores/my-hl7v2-store/messages/MESSAGE_ID",
     "data": "TVNIfF5+XCZ8QXxTRU5EX0ZBQ0lMSVRZfEF8QXwyMDE4MDEwMTAwMDAwMHx8VFlQRV5BfDIwMTgwMTAxMDAwMDAwfFR8MC4wfHx8QUF8fDAwfEFTQ0lJDUVWTnxBMDB8MjAxODAxMDEwNDAwMDANUElEfHwxNAExMTFeXl5eTVJOfDExMTExMTExXl5eXk1STn4xMTExMTExMTExXl5eXk9SR05NQlI=",
     "sendFacility": "SEND_FACILITY",
     "sendTime": "2018-01-01T00:00:00Z",
     "messageType": "TYPE",
     "createTime": "CREATE_TIME",
     "patientIds": [
       {
         "value": "14\u0001111",
         "type": "MRN"
       },
       {
         "value": "11111111",
         "type": "MRN"
       },
       {
         "value": "1111111111",
         "type": "ORGNMBR"
       }
     ]
   }
   

   In this output:

   • PROJECT_ID, us-central1, my-dataset, my-hl7v2-store: the values that you provided in the method call
   • MESSAGE_ID: an identifier for the HL7v2 message provided by the Cloud Healthcare API
   • CREATE_TIME: a timestamp for when the message was sent to the Cloud Healthcare API

   PowerShell

   $cred = gcloud auth application-default print-access-token
   $headers = @{ Authorization = "Bearer $cred" }
   
   Invoke-WebRequest `
     -Method Post `
     -Headers $headers `
     -ContentType: "application/json; charset=utf-8" `
     -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
   

   Replace PROJECT_ID with the ID of the Google Cloud project that you created or selected in Before you begin.

   The output is the following:

   {
     "name": "projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/hl7V2Stores/my-hl7v2-store/messages/MESSAGE_ID",
     "data": "TVNIfF5+XCZ8QXxTRU5EX0ZBQ0lMSVRZfEF8QXwyMDE4MDEwMTAwMDAwMHx8VFlQRV5BfDIwMTgwMTAxMDAwMDAwfFR8MC4wfHx8QUF8fDAwfEFTQ0lJDUVWTnxBMDB8MjAxODAxMDEwNDAwMDANUElEfHwxNAExMTFeXl5eTVJOfDExMTExMTExXl5eXk1STn4xMTExMTExMTExXl5eXk9SR05NQlI=",
     "sendFacility": "SEND_FACILITY",
     "sendTime": "2018-01-01T00:00:00Z",
     "messageType": "TYPE",
     "createTime": "CREATE_TIME",
     "patientIds": [
       {
         "value": "14\u0001111",
         "type": "MRN"
       },
       {
         "value": "11111111",
         "type": "MRN"
       },
       {
         "value": "1111111111",
         "type": "ORGNMBR"
       }
     ]
   }
   

   In this output:

   • PROJECT_ID, us-central1, my-dataset, my-hl7v2-store: the values that you provided in the method call
   • MESSAGE_ID: an identifier for the HL7v2 message provided by the Cloud Healthcare API
   • CREATE_TIME: a timestamp for when the message was sent to the Cloud Healthcare API

View HL7v2 message contents

Note the MESSAGE_ID from the response you received when you created the HL7v2 message. View the HL7v2 message's details using the messages.get method.

curl

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/hl7V2Stores/my-hl7v2-store/messages/MESSAGE_ID"

Replace the following:

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

The output is the following:

{
  "name": "projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/hl7V2Stores/my-hl7v2-store/messages/MESSAGE_ID",
  "data": "TVNIfF5+XCZ8QXxTRU5EX0ZBQ0lMSVRZfEF8QXwyMDE4MDEwMTAwMDAwMHx8VFlQRV5BfDIwMTgwMTAxMDAwMDAwfFR8MC4wfHx8QUF8fDAwfEFTQ0lJDUVWTnxBMDB8MjAxODAxMDEwNDAwMDANUElEfHwxNAExMTFeXl5eTVJOfDExMTExMTExXl5eXk1STn4xMTExMTExMTExXl5eXk9SR05NQlI=",
  "sendFacility": "SEND_FACILITY",
  "sendTime": "2018-01-01T00:00:00Z",
  "messageType": "TYPE",
  "createTime": "CREATE_TIME",
  "patientIds": [
    {
      "value": "14\u0001111",
      "type": "MRN"
    },
    {
      "value": "11111111",
      "type": "MRN"
    },
    {
      "value": "1111111111",
      "type": "ORGNMBR"
    }
  ],
  "parsedData": {
    "segments": [
      {
        "segmentId": "MSH",
        "fields": {
          "5": "A",
          "8.1": "TYPE",
          "6": "20180101000000",
          "8.2": "A",
          "3": "SEND_FACILITY",
          "4": "A",
          "11": "0.0",
          "10": "T",
          "1": "^~\\&",
          "17": "ASCII",
          "2": "A",
          "0": "MSH",
          "14": "AA",
          "9": "20180101000000",
          "16": "00"
        }
      },
      {
        "segmentId": "EVN",
        "fields": {
          "2": "20180101040000",
          "0": "EVN",
          "1": "A00"
        }
      },
      {
        "segmentId": "PID",
        "fields": {
          "3[0].5": "MRN",
          "3[1].1": "1111111111",
          "3[1].5": "ORGNMBR",
          "0": "PID",
          "2.1": "14\u0001111",
          "2.5": "MRN",
          "3[0].1": "11111111"
        }
      }
    ]
  }
}

PowerShell

$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/us-central1/datasets/my-dataset/hl7V2Stores/my-hl7v2-store/messages/MESSAGE_ID" | Select-Object -Expand Content

Replace the following:

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

The output is the following:

{
  "name": "projects/PROJECT_ID/locations/us-central1/datasets/my-dataset/hl7V2Stores/my-hl7v2-store/messages/MESSAGE_ID",
  "data": "TVNIfF5+XCZ8QXxTRU5EX0ZBQ0lMSVRZfEF8QXwyMDE4MDEwMTAwMDAwMHx8VFlQRV5BfDIwMTgwMTAxMDAwMDAwfFR8MC4wfHx8QUF8fDAwfEFTQ0lJDUVWTnxBMDB8MjAxODAxMDEwNDAwMDANUElEfHwxNAExMTFeXl5eTVJOfDExMTExMTExXl5eXk1STn4xMTExMTExMTExXl5eXk9SR05NQlI=",
  "sendFacility": "SEND_FACILITY",
  "sendTime": "2018-01-01T00:00:00Z",
  "messageType": "TYPE",
  "createTime": "CREATE_TIME",
  "patientIds": [
    {
      "value": "14\u0001111",
      "type": "MRN"
    },
    {
      "value": "11111111",
      "type": "MRN"
    },
    {
      "value": "1111111111",
      "type": "ORGNMBR"
    }
  ],
  "parsedData": {
    "segments": [
      {
        "segmentId": "MSH",
        "fields": {
          "5": "A",
          "8.1": "TYPE",
          "6": "20180101000000",
          "8.2": "A",
          "3": "SEND_FACILITY",
          "4": "A",
          "11": "0.0",
          "10": "T",
          "1": "^~\\&",
          "17": "ASCII",
          "2": "A",
          "0": "MSH",
          "14": "AA",
          "9": "20180101000000",
          "16": "00"
        }
      },
      {
        "segmentId": "EVN",
        "fields": {
          "2": "20180101040000",
          "0": "EVN",
          "1": "A00"
        }
      },
      {
        "segmentId": "PID",
        "fields": {
          "3[0].5": "MRN",
          "3[1].1": "1111111111",
          "3[1].5": "ORGNMBR",
          "0": "PID",
          "2.1": "14\u0001111",
          "2.5": "MRN",
          "3[0].1": "11111111"
        }
      }
    ]
  }
}

Now that you've stored and viewed an 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, follow these steps.

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

Caution: Deleting a project has the following effects:

• Everything in the project is deleted. If you used an existing project for this tutorial, when you delete it, you also delete any other work you've done in the project.
• Custom project IDs are lost. When you created this project, you might have created a custom project ID that you want to use in the future. To preserve the URLs that use the project ID, such as an appspot.com URL, delete selected resources inside the project instead of deleting the whole project.

If you plan to explore multiple tutorials and quickstarts, reusing projects can help you avoid exceeding project quota limits.

1. In the console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

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.

curl

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/datasets/my-dataset"

Replace PROJECT_ID with the ID of the Google Cloud project that you created or selected in Before you begin.

The output is the following:

{}

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

Replace PROJECT_ID with the ID of the Google Cloud project that you created or selected in Before you begin.

The output is the following:

{}

How did it go?

It worked!

Great! What did you like about the quickstart? What could we have done better? Let us know!.

I got stuck.

We're sorry to hear that. Let us know what went wrong. We'll want to fix it.

What's next

See the following sections for general information on the Cloud Healthcare API and how to perform tasks using the console and the Google Cloud CLI:

• Read an overview of Cloud Healthcare API concepts
• Use the Cloud Healthcare API with console
• Use the Cloud Healthcare API with the gcloud CLI

DICOM

Continue to the DICOM guide to read topics such as the following:

• Creating and managing DICOM stores
• Connecting a PACS to the Cloud Healthcare API
• Using the DICOMweb standard
• Importing and exporting DICOM data using Cloud Storage

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

FHIR

Continue to the FHIR guide to read topics such as the following:

• Creating and managing FHIR stores
• Creating and managing FHIR resources
• Importing and exporting FHIR data using Cloud Storage

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

HL7v2

Continue to the HL7v2 guide to read topics such as the following:

• Creating and managing HL7v2 stores
• Creating and managing HL7v2 messages
• Transmitting HL7v2 messages over TCP/IP connections
• Importing and exporting HL7v2 messages using Cloud Storage