Creating and managing annotation records

This page explains how to create, view, list, and delete annotation records. Examples of annotation records include labels and tags for healthcare text, image, and audio. For an overview of annotation stores and annotation records, see Annotations.

Creating an annotation record

Before you can create an annotation record, you need to create an annotation store.

The following samples show how to create an annotation record. For more information, see projects.locations.datasets.annotationStores.annotations.create.

curl

To create an annotation record, make a POST request and provide the following information:

  • The name of the parent dataset
  • The name of the parent annotation store
  • The source of the annotation record
  • The type of annotation record
  • An access token

The following sample shows a POST request using curl that creates an annotation record for a DICOM image. The annotation uses a bounding box to mark the dimensions of a part of the image and labels the bounded area with the name "bounding-box." This sample assumes that you have already stored a DICOM instance in a DICOM store. This DICOM instance is referenced in the name field of cloudHealthcareSource.

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{
      'annotationSource': {
        'cloudHealthcareSource': {
          'name': 'projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID'
        }
      },
      'imageAnnotation': {
        'boundingPolys': [
          {
            'vertices': [
              {
                'x': 100,
                'y': 100
              },
              {
                'x': 100,
                'y': 400
              },
              {
                'x': 400,
                'y': 100
              },
              {
                'x': 400,
                'y': 400
              }
            ],
            'label': 'bounding-box'
          }
        ]
      }
    }" \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations"

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

{
  "name": "projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations/ANNOTATION_ID",
  "annotationSource": {
    "cloudHealthcareSource": {
      "name": "projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID"
    }
  },
  "imageAnnotation": {
    "boundingPolys": [
      {
        "vertices": [
          {
            "x": 100,
            "y": 100
          },
          {
            "x": 100,
            "y": 400
          },
          {
            "x": 400,
            "y": 100
          },
          {
            "x": 400,
            "y": 400
          }
        ],
        "label": "bounding-box"
      }
    ]
  }
}

PowerShell

To create an annotation record, make a POST request and provide the following information:

  • The name of the parent dataset
  • The name of the parent annotation store
  • The source of the annotation record
  • The type of annotation record
  • An access token

The following sample shows a POST request using Windows PowerShell that creates an annotation record for a DICOM image. The annotation uses a bounding box to mark the dimensions of a part of the image and labels the bounded area with the name "bounding-box." This sample assumes that you have already stored a DICOM instance in a DICOM store. This DICOM instance is referenced in the name field of cloudHealthcareSource.

$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 "{
    'annotationSource': {
      'cloudHealthcareSource': {
        'name': 'projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID'
      }
    },
    'imageAnnotation': {
      'boundingPolys': [
        {
          'vertices': [
            {
              'x': 100,
              'y': 100
            },
            {
              'x': 100,
              'y': 400
            },
            {
              'x': 400,
              'y': 100
            },
            {
              'x': 400,
              'y': 400
            }
          ],
          'label': 'bounding-box'
        }
      ]
    }
  }" `
  -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations" | Select-Object -Expand Content

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

{
  "name": "projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations/ANNOTATION_ID",
  "annotationSource": {
    "cloudHealthcareSource": {
      "name": "projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID"
    }
  },
  "imageAnnotation": {
    "boundingPolys": [
      {
        "vertices": [
          {
            "x": 100,
            "y": 100
          },
          {
            "x": 100,
            "y": 400
          },
          {
            "x": 400,
            "y": 100
          },
          {
            "x": 400,
            "y": 400
          }
        ],
        "label": "bounding-box"
      }
    ]
  }
}

Editing an annotation record

The following samples show how to edit the annotation record from Creating an annotation record so that it has a resource type label. For more information, see projects.locations.datasets.annotationStores.annotations.patch.

curl

To edit an annotation record, make a PATCH request and provide the following information:

  • The name of the parent dataset
  • The name of the parent annotation store
  • The annotation record ID
  • The data to update
  • An update mask
  • An access token

The following sample shows a PATCH request using curl on an annotation record for a DICOM instance.

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{
      'resourceAnnotation': {
        'label': 'VALUE'
      }
    }" \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations/ANNOTATION_ID?updateMask=resourceAnnotation"

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

{
  "name": "projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations/ANNOTATION_ID",
  "annotationSource": {
    "cloudHealthcareSource": {
      "name": "projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID"
    }
  },
  "resourceAnnotation": {
    "label": "VALUE"
  }
}

PowerShell

To edit an annotation record, make a PATCH request and provide the following information:

  • The name of the parent dataset
  • The name of the parent annotation store
  • The annotation record ID
  • The data to update
  • An update mask
  • An access token

The following sample shows a PATCH request using Windows PowerShell on an annotation record for a DICOM instance.

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

Invoke-WebRequest `
  -Method Patch `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -Body "{
    'resourceAnnotation': {
      'label': 'VALUE'
    }
  }" `
  -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations/ANNOTATION_ID?updateMask=resourceAnnotation" | Select-Object -Expand Content

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

{
  "name": "projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations/ANNOTATION_ID",
  "annotationSource": {
    "cloudHealthcareSource": {
      "name": "projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID"
    }
  },
  "resourceAnnotation": {
    "label": "VALUE"
  }
}

Getting annotation record details

The following samples show how to get details about an annotation record. For more information, see projects.locations.datasets.annotationStores.annotations.get.

curl

To get details about an annotation record, make a GET request and provide the following information:

  • The name of the parent dataset
  • The name of the parent annotation store
  • The annotation record ID
  • An access token

The following sample shows a GET request using curl to view an annotation record for a DICOM instance.

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations/ANNOTATION_ID"

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

{
  "name": "projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations/ANNOTATION_ID",
  "annotationSource": {
    "cloudHealthcareSource": {
      "name": "projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID"
    }
  }
}

If you configured any fields in the Annotation resource, they also appear in the response.

PowerShell

To get details about an annotation record, make a GET request and provide the following information:

  • The name of the parent dataset
  • The name of the parent annotation store
  • The annotation record ID
  • An access token

The following sample shows a GET request using Windows PowerShell to view an annotation record for a DICOM instance.

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

Invoke-WebRequest `
  -Method Get `
  -Headers $headers `
  -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations/ANNOTATION_ID" | Select-Object -Expand Content

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

{
  "name": "projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations/ANNOTATION_ID",
  "annotationSource": {
    "cloudHealthcareSource": {
      "name": "projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID"
    }
  }
}

If you configured any fields in the Annotation resource, they also appear in the response.

Listing annotation records in an annotation store

The following samples show how to list the annotation records in an annotation store. For more information, see projects.locations.datasets.annotationStores.annotations.list.

curl

To list the annotations records in an annotation store, make a GET request and provide the following information:

  • The name of the parent dataset
  • The name of the annotation store
  • An access token

The following sample shows a GET request using curl on an annotation store containing annotation records for a DICOM instance.

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations"

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

{
  "annotations": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations/ANNOTATION_ID",
      "annotationSource": {
        "cloudHealthcareSource": {
          "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID"
        }
      }
    }
  ]
}

If you configured any fields in the Annotation resource, they also appear in the response.

PowerShell

To list the annotations records in an annotation store, make a GET request and provide the following information:

  • The name of the parent dataset
  • The name of the annotation store
  • An access token

The following sample shows a GET request using Windows PowerShell on an annotation store containing annotation records for a DICOM instance.

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

Invoke-WebRequest `
  -Method Get `
  -Headers $headers `
  -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations" | Select-Object -Expand Content

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

{
  "annotations": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations/ANNOTATION_ID",
      "annotationSource": {
        "cloudHealthcareSource": {
          "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID"
        }
      }
    }
  ]
}

If you configured any fields in the Annotation resource, they also appear in the response.

Deleting an annotation record

The following samples show how to delete an annotation record. For more information, see projects.locations.datasets.annotationStores.annotations.delete.

curl

To delete an annotation record, make a DELETE request and provide the following information:

  • The name of the parent dataset
  • The name of the parent annotation store
  • The annotation record ID
  • An access token

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/v1beta1/projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations/ANNOTATION_ID"

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

{}

PowerShell

To delete an annotation record, make a DELETE request and provide the following information:

  • The name of the parent dataset
  • The name of the parent annotation store
  • The annotation record ID
  • An access token

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 `
  -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations/ANNOTATION_ID" | Select-Object -Expand Content

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

{}