Quickstart using curl or Windows PowerShell

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

1. Create a Cloud Healthcare API dataset.
2. Create a DICOM, FHIR, or HL7v2 store inside the dataset.
3. Store and inspect a particular type of medical data in the DICOM, FHIR, or HL7v2 store.

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 confirm that billing is enabled for your project.

4. Enable the Cloud Healthcare API.

   Enable the API

5. Install and initialize the Cloud SDK.
6. Use the gcloud command-line tool 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. The Google Cloud Shell is a command line environment that already includes the Google Cloud SDK, so you don't need to install it. (The Google Cloud SDK also comes preinstalled on Google Compute Engine Virtual Machines.)

Creating a dataset

Datasets are the basic containers that hold healthcare data in Google Cloud. To use the Cloud Healthcare API, you must create at least one dataset.

curl

To create a dataset, make a POST request and provide a name and location for the dataset. The following sample shows a POST request using curl.

When setting the LOCATION variable, use us-central1, us-west2, us-east4, europe-west2, europe-west4, europe-west6, northamerica-northeast1, southamerica-east1, asia-east2, asia-northeast1, asia-southeast1, australia-southeast1, or us.

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/LOCATION/datasets?datasetId=DATASET_ID"

If the request is successful, the server returns the response in JSON format. 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/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
}

The response contains an operation name. To track the status of the operation, you can use the Operation get method:

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

If the request is successful, the server returns a response with the status of the operation in JSON format. You can tell that the operation finished when the response contains "done": true.

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1.dataset.DatasetService.CreateDataset",
    "createTime": "CREATE_TIME",
    "endTime": "END_TIME",
    "logsUrl": "https://console.cloud.google.com/logs/viewer/CLOUD_LOGGING_URL"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.dataset.Dataset",
    "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID"
  }
}

PowerShell

To create a dataset, make a POST request and provide a name and location for the dataset. The following sample shows a POST request using Windows PowerShell.

When setting the LOCATION variable, use us-central1, us-west2, us-east4, europe-west2, europe-west4, europe-west6, northamerica-northeast1, southamerica-east1, asia-east2, asia-northeast1, asia-southeast1, australia-southeast1, or us.

$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/LOCATION/datasets?datasetId=DATASET_ID" | Select-Object -Expand Content

If the request is successful, the server returns the response in JSON format. 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/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
}

The response contains an operation name. To track the status of the operation, you can use the Operation get method:

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

Invoke-WebRequest `
  -Method Get `
  -Headers $headers `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" | Select-Object -Expand Content

If the request is successful, the server returns a response with the status of the operation in JSON format. You can tell that the operation finished when the response contains "done": true.

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1.dataset.DatasetService.CreateDataset",
    "createTime": "CREATE_TIME",
    "endTime": "END_TIME",
    "logsUrl": "https://console.cloud.google.com/logs/viewer/CLOUD_LOGGING_URL"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.dataset.Dataset",
    "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID"
  }
}

Storing and viewing DICOM, FHIR, and HL7v2 data

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

• Storing and viewing DICOM instances
• Storing and viewing FHIR resources
• Storing and viewing HL7v2 messages

Storing and viewing DICOM instances

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.

1. DICOM stores exist inside datasets and hold DICOM instances. You create a DICOM store using the projects.locations.datasets.dicomStores.create method.

   curl

   To create a DICOM store, make a POST request and specify the following information:

   • The name and location of the parent dataset
   • A name for the DICOM store. The DICOM store ID must be unique in its parent dataset. It can be any Unicode string from 1 through 256 characters consisting of numbers, letters, underscores, dashes, and periods.

   The following sample shows a POST request using 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/LOCATION/datasets/DATASET_ID/dicomStores?dicomStoreId=DICOM_STORE_ID"
   

   If the request is successful, the server returns the following response in JSON format:

   {
     "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID"
   }
   

   PowerShell

   To create a DICOM store, make a POST request and specify the following information:

   • The name and location of the parent dataset
   • A name for the DICOM store. The DICOM store ID must be unique in its parent dataset. It can be any Unicode string from 1 through 256 characters consisting of numbers, letters, underscores, dashes, and periods.

   The following sample shows a POST request using Windows PowerShell:

   $cred = gcloud auth application-default print-access-token
   $headers = @{ Authorization = "Bearer $cred" }
   
   Invoke-WebRequest `
     -Method Post `
     -Headers $headers `
     -ContentType: "application/json; charset=utf-8" `
     -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores?dicomStoreId=DICOM_STORE_ID" | Select-Object -Expand Content
   

   If the request is successful, the server returns a response similar to the following sample in JSON format:

   {
     "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID"
   }
   

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

3. Run the following command to store the DICOM instance in the DICOM store you created:

   curl

   To store the DICOM instance, make a POST request and specify the following information:

   • The name and location of the parent dataset
   • The name of the DICOM store
   • The filename and location of the DICOM instance file on your machine

   The following sample shows a POST request using curl:

   curl -X POST \
       -H "Content-Type: application/dicom" \
       -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
       --data-binary @dicom_00000001_000.dcm \
       https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies
   

   If the request is successful, the server returns the following 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/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/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/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

   To store the DICOM instance, make a POST request and specify the following information:

   • The name and location of the parent dataset
   • The name of the DICOM store
   • The filename and location of the DICOM instance file on your machine

   The following sample shows a POST request using Windows PowerShell:

   $cred = gcloud auth application-default print-access-token
   $headers = @{ Authorization = "Bearer $cred" }
   
   Invoke-WebRequest `
     -Method Post `
     -Headers $headers `
     -ContentType: "application/dicom" `
     -InFile dicom_00000001_000.dcm `
     -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies" | Select-Object -Expand Content
   

   If the request is successful, the server returns the following 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/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/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/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>
   

4. Search for instances in the DICOM store to view the metadata for the instance you stored:

   curl

   To view the metadata for the DICOM instance you stored, make a GET request and specify the following information:

   • The name and location of the parent dataset
   • The name of the DICOM store

   The following sample shows a GET request using curl to search for instances in the DICOM store:

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
        "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/instances"
   

   If the request is successful, the server returns the response in JSON format:

   [
     {
       "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

   To view the metadata for the DICOM instance you stored, make a GET request and specify the following information:

   • The name and location of the parent dataset
   • The name of the DICOM store

   The following sample shows a GET request using Windows PowerShell to search for instances in the DICOM store:

   $cred = gcloud auth application-default print-access-token
   $headers = @{ Authorization = "Bearer $cred" }
   
   Invoke-RestMethod `
     -Method Get `
     -Headers $headers `
     -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/instances"
   

   If the request is successful, the server returns the response in JSON format:

   [
     {
       "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 What's next for information on next steps.

Storing and viewing 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.

1. FHIR stores exist inside datasets and hold FHIR resources. You create a FHIR store using the projects.locations.datasets.fhirStores.create method:

   curl

   To create a FHIR store, make a POST request and specify the following information:

   • The name and location of the parent dataset
   • A name for the FHIR store. The FHIR store ID must be unique in its parent dataset. It can be any Unicode string from 1 through 256 characters consisting of numbers, letters, underscores, dashes, and periods.
   • The FHIR version of the FHIR store. The available options are DSTU2, STU3, or R4. For this quickstart, use R4.

   The following sample shows a POST request using 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/LOCATION/datasets/DATASET_ID/fhirStores?fhirStoreId=FHIR_STORE_ID"
   

   If the request is successful, the server returns the following response in JSON format:

   {
     "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
     "version": "R4"
   }
   

   PowerShell

   To create a FHIR store, make a POST request and specify the following information:

   • The name and location of the parent dataset
   • A name for the FHIR store. The FHIR store ID must be unique in its parent dataset. It can be any Unicode string from 1 through 256 characters consisting of numbers, letters, underscores, dashes, and periods.
   • The FHIR version of the FHIR store: DSTU2, STU3, or R4

   The following sample shows a POST request using Windows PowerShell:

   $cred = gcloud auth application-default print-access-token
   $headers = @{ Authorization = "Bearer $cred" }
   
   Invoke-WebRequest `
     -Method Post `
     -Headers $headers `
     -ContentType: "application/json; charset=utf-8" `
     -Body "{
         'version': 'R4'
     }" `
     -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores?fhirStoreId=FHIR_STORE_ID" | Select-Object -Expand Content
   

   If the request is successful, the server returns the response in JSON format:

   {
     "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
     "version": "R4"
   }
   

2. Save the sample JSON FHIR resource file. The file contains basic data for a Patient resource.

3. Run the following command to store the Patient resource in the FHIR store you created:

   curl

   To create the Patient resource from the sample file, make a POST request and specify the following information:

   • The name and location of the parent dataset
   • The name of the FHIR store
   • The filename and location of the FHIR resource file on your machine

   The following sample shows how to send a POST request using curl to create the Patient resource:

   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/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient"
   

   If the request is successful, the server returns the following response:

   {
     "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

   To create the Patient resource from the sample file, make a POST request and specify the following information:

   • The name and location of the parent dataset
   • The name of the FHIR store
   • The filename and location of the FHIR resource file on your machine

   The following sample shows how to send a POST request using Windows PowerShell to create the Patient resource:

   $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/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient" | Select-Object -Expand Content
   

   If the request is successful, the server returns the following response:

   {
     "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"
   }
   

4. Search for the resource in your FHIR store to view information about the patient:

   curl

   To search for the Patient resource and view its details, make a GET request and specify the following information:

   • The name and location of the parent dataset
   • The name of the FHIR store
   • A query string containing the information you're searching for. In this sample, you search on the patient's last name.

   The following sample shows a GET request using curl to search for all patients with the last name "Smith".

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

   If the request is successful, 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/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/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/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/?family%3Aexact=Smith"
       }
     ],
     "resourceType": "Bundle",
     "total": 1,
     "type": "searchset"
   }
   

   PowerShell

   To search for the Patient resource and view its details, make a GET request and specify the following information:

   • The name and location of the parent dataset
   • The name of the FHIR store
   • A query string containing the information you're searching for. In this sample, you search on the patient's last name.

   The following sample shows a GET request using Windows PowerShell to search for all patients with the last name "Smith".

   $cred = gcloud auth application-default print-access-token
   $headers = @{ Authorization = "Bearer $cred" }
   
   Invoke-RestMethod `
     -Method Get `
     -Headers $headers `
     -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE_TYPE?family:exact=Smith" | ConvertTo-Json
   

   If the request is successful, 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/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/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/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/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 What's next for information on next steps.

Storing and viewing HL7v2 messages

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.

1. HL7v2 stores exist inside datasets and hold HL7v2 messages. You create an HL7v2 store using the projects.locations.datasets.hl7V2Stores.create method.

   curl

   To create an HL7v2 store, make a POST request and specify the following information:

   • The name and location of the parent dataset
   • A name for the HL7v2 store. The HL7v2 store ID must be unique in its parent dataset. It can be any Unicode string from 1 through 256 characters consisting of numbers, letters, underscores, dashes, and periods.

   The following sample shows a POST request using 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/LOCATION/datasets/DATASET_ID/hl7V2Stores?hl7V2StoreId=HL7V2_STORE_ID"
   

   If the request is successful, the server returns the following response in JSON format:

   {
     "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID"
   }
   

   PowerShell

   To create an HL7v2 store, make a POST request and specify the following information:

   • The name and location of the parent dataset
   • A name for the HL7v2 store. The HL7v2 store ID must be unique in its parent dataset. It can be any Unicode string from 1 through 256 characters consisting of numbers, letters, underscores, dashes, and periods.

   The following sample shows a POST request using Windows PowerShell:

   $cred = gcloud auth application-default print-access-token
   $headers = @{ Authorization = "Bearer $cred" }
   
   Invoke-WebRequest `
     -Method Post `
     -Headers $headers `
     -ContentType: "application/json; charset=utf-8" `
     -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/hl7V2Stores?hl7V2StoreId=HL7V2_STORE_ID" | Select-Object -Expand Content
   

   If the request is successful, the server returns a response similar to the following sample in JSON format:

   {
     "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID"
   }
   

2. Download the sample HL7v2 message file to your machine. The 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
   

3. There are two methods to store an HL7v2 message: creation and ingestion. See Overview of creating and ingesting HL7v2 messages for more information. In this sample, you store the HL7v2 message using the create method, because the ingest method typically consumes an HL7v2 message that comes from a care center.

   Run the following command to store the HL7v2 message in the HL7v2 store you created:

   curl

   To store the HL7v2 message, make a POST request and specify the following information:

   • The name and location of the parent dataset
   • The name of the HL7v2 store
   • The name and location of the HL7v2 message file on your machine

   The following sample shows a POST request using 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/LOCATION/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID/messages"
   

   If the request is successful, the server returns the following response in JSON format:

   {
     "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID/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"
       }
     ]
   }
   

   PowerShell

   To store the HL7v2 message, make a POST request and specify the following information:

   • The name and location of the parent dataset
   • The name of the HL7v2 store
   • The name and location of the HL7v2 message file on your machine

   The following sample shows a POST request using Windows PowerShell:

   $cred = gcloud auth application-default print-access-token
   $headers = @{ Authorization = "Bearer $cred" }
   
   Invoke-WebRequest `
     -Method Post `
     -Headers $headers `
     -ContentType: "application/json; charset=utf-8" `
     -InFile hl7v2-sample.json `
     -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID/messages" | Select-Object -Expand Content
   

   If the request is successful, the server returns the following response in JSON format:

   {
     "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID/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"
       }
     ]
   }
   

4. Using the MESSAGE_ID from the response you received when you created the message, run the following command to view the message's details:

   curl

   To get the contents of the HL7v2 message, make a GET request and specify the following information:

   • The name and location of the parent dataset
   • The name of the HL7v2 store
   • The message ID

   The following sample shows a GET request using curl:

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
        "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID/messages/MESSAGE_ID"
   

   If the request is successful, the server returns the response in JSON format:

   {
     "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID/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

   To get the contents of the HL7v2 message, make a GET request and specify the following information:

   • The name and location of the parent dataset
   • The name of the HL7v2 store
   • The message ID

   The following sample shows a GET request using Windows 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/LOCATION/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID/messages/MESSAGE_ID" | Select-Object -Expand Content
   

   If the request is successful, the server returns the response in JSON format:

   {
     "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID/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 What's next for information on next steps.

Clean up

To avoid incurring charges to your Google Cloud account for the resources used in this tutorial, you can clean up the resources you created on Google Cloud. If you created a new project for this tutorial, 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 Cloud 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

To delete a dataset, make a DELETE request, providing the name and location. The following sample shows a DELETE request using curl:

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

If the request is successful, the server returns the response in JSON format:

{}

PowerShell

To delete a dataset, make a DELETE request, providing the name and location of the dataset. The following sample shows a DELETE request using Windows PowerShell:

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

Invoke-WebRequest `
  -Method Delete `
  -Headers $headers `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID" | Select-Object -Expand Content

If the request is successful, the server returns the response in JSON format:

{}

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 Cloud Console and the gcloud command-line tool:

• Read an overview of Cloud Healthcare API concepts
• Use the Cloud Healthcare API with Cloud Console
• Use the Cloud Healthcare API with the gcloud tool

DICOM

Continue to the DICOM guide to review topics such as:

• How to manage and customize 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 review topics such as:

• How to manage and customize 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 review topics such as:

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