Creating and managing annotation stores

This page explains how to create, label, view, list, and delete annotation stores. Annotation stores hold annotation records, which are labels that you can add to healthcare resources.

For an overview of annotation stores and annotation records, see Annotations.

Creating an annotation store

Before you can create an annotation store, you need to create a dataset.

The following samples show how to create an annotation store.

gcloud

To create an annotation store, run the gcloud beta healthcare annotation-stores create command:

  • The ANNOTATION_STORE_ID must be unique within the region. It can be any Unicode string of 1 to 256 characters consisting of numbers, letters, underscores, dashes, and periods.
gcloud beta healthcare annotation-stores create ANNOTATION_STORE_ID \
  --dataset=DATASET_ID \
  --location=LOCATION

If the request is successful, the command prompt displays the following message:

Created annotationStore [ANNOTATION_STORE_ID].

API

To create an annotation store, use the projects.locations.datasets.annotationStores.create method.

curl

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

  • The parent dataset
  • A name for the annotation store. The annotation 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.
  • An access token

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/v1beta1/projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/annotationStores?annotationStoreId=ANNOTATION_STORE_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"
}

PowerShell

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

  • The parent dataset
  • A name for the annotation store. The annotation 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.
  • An access token

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/v1beta1/projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/annotationStores?annotationStoreId=ANNOTATION_STORE_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"
}

Labeling an annotation store

You can add one or more key-value labels to an annotation store. One use case for adding labels could be adding labels and tags for annotation records relating to text or images.

The following samples show how to add labels to an annotation store.

gcloud

The gcloud CLI does not support editing annotation store labels. Instead, use curl, Windows PowerShell, or your preferred language.

API

To add labels to an annotation store, use the projects.locations.datasets.annotationStores.patch command.

curl

To label an annotation store, make a PATCH request and provide the following information:

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

The following sample shows a PATCH request using curl.

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

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",
  "labels": {
    "KEY": "VALUE"
  }
}

PowerShell

To label an annotation store, make a PATCH request and provide the following information:

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

The following sample shows a PATCH request using Windows PowerShell.

$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 "{
      'labels': {
        'KEY': 'VALUE'
      }
  }" `
  -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/annotationStores/ANNOTATION_STORE_ID?updateMask=labels" | 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",
  "labels": {
    "KEY": "VALUE"
  }
}

Getting annotation store details

The following samples show how to get details about an annotation store.

gcloud

To get details about an annotation store, run the gcloud beta healthcare annotation-stores describe command:

gcloud beta healthcare annotation-stores describe ANNOTATION_STORE_ID \
  --dataset=DATASET_ID \
  --location=LOCATION

If the request is successful, the command prompt displays the annotation store details:

name: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/annotation-stores/ANNOTATION_STORE_ID

API

To get details about an annotation store, use the projects.locations.datasets.annotationStores.get method.

curl

To get details about 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.

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"

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

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

PowerShell

To get details about 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.

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

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

Listing annotation stores in a dataset

The following samples show how to list the annotation stores in a dataset.

gcloud

To list the annotation stores in a dataset, run the gcloud beta healthcare annotation-stores list command:

gcloud beta healthcare annotation-stores list \
  --dataset=DATASET_ID \
  --location=LOCATION

If the request is successful, the command prompt lists the annotation stores:

ID                   LOCATION
ANNOTATION_STORE_ID  LOCATION

API

To list the annotation stores in a dataset, use the projects.locations.datasets.annotationStores.list method.

curl

To list the annotation stores in a dataset, make a GET request and provide the following information:

  • The name of the parent dataset
  • An access token

The following sample shows a GET request using curl.

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

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

{
  "annotationStores": [
    {
      "name": "projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/annotationStores/ANNOTATION_STORE_ID"
    },
    {
      ...
    }
  ]
}

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

PowerShell

To list the annotation stores in a dataset, make a GET request and provide the following information:

  • The name of the parent dataset
  • An access token

The following sample shows a GET request using Windows PowerShell.

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

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

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

{
  "annotationStores": [
    {
      "name": "projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/annotationStores/ANNOTATION_STORE_ID"
    },
    {
      ...
    }
  ]
}

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

Deleting an annotation store

The following samples show how to delete an annotation store.

gcloud

To delete an annotation store, run the gcloud beta healthcare annotation-stores delete command:

  1. Run the delete command.

    gcloud beta healthcare annotation-stores delete ANNOTATION_STORE_ID \
  --dataset=DATASET_ID \
  --location=LOCATION

  2. To confirm, type Y.

If the request is successful, the command prompt displays the following:

Deleted annotationStore [ANNOTATION_STORE_ID].

API

To delete an annotation store, use the projects.locations.datasets.annotationStores.delete command.

curl

To delete an annotation store, make a DELETE 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 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"

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

{}

PowerShell

To delete an annotation store, make a DELETE 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 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" | Select-Object -Expand Content

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

{}