Package google.cloud.healthcare.v1beta1.annotation

Index

AnnotationService

A service for handling Cloud Healthcare Data Annotations.

CreateAnnotation

rpc CreateAnnotation(CreateAnnotationRequest) returns (Annotation)

Creates a new Annotation record. It is valid to create Annotation objects for the same source more than once since a unique ID is assigned to each record by this service.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/cloud-healthcare
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
CreateAnnotationStore

rpc CreateAnnotationStore(CreateAnnotationStoreRequest) returns (AnnotationStore)

Creates a new Annotation store within the parent dataset.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/cloud-healthcare
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
DeleteAnnotation

rpc DeleteAnnotation(DeleteAnnotationRequest) returns (Empty)

Deletes an Annotation or returns NOT_FOUND if it does not exist.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/cloud-healthcare
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
DeleteAnnotationStore

rpc DeleteAnnotationStore(DeleteAnnotationStoreRequest) returns (Empty)

Deletes the specified Annotation store and removes all annotations that are contained within it.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/cloud-healthcare
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
EvaluateAnnotationStore

rpc EvaluateAnnotationStore(EvaluateAnnotationStoreRequest) returns (Operation)

Evaluate an Annotation store against a ground truth Annotation store. When the operation finishes successfully, a detailed response is returned of type EvaluateAnnotationStoreResponse, contained in the [response] [google.longrunning.Operation.result.response]. The metadata field type is OperationMetadata. Errors are logged to Cloud Logging (see Viewing error logs in Cloud Logging).

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/cloud-healthcare
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
ExportAnnotations

rpc ExportAnnotations(ExportAnnotationsRequest) returns (Operation)

Export Annotations from the Annotation store. If the request is successful, a detailed response is returned of type ExportAnnotationsResponse, contained in the [response][google.longrunning.Operation.result.response] field when the operation finishes. The metadata field type is OperationMetadata. Errors are logged to Cloud Logging (see Viewing error logs in Cloud Logging).

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/cloud-healthcare
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
GetAnnotation

rpc GetAnnotation(GetAnnotationRequest) returns (Annotation)

Gets an Annotation.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/cloud-healthcare
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
GetAnnotationStore

rpc GetAnnotationStore(GetAnnotationStoreRequest) returns (AnnotationStore)

Gets the specified Annotation store or returns NOT_FOUND if it does not exist.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/cloud-healthcare
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
ImportAnnotations

rpc ImportAnnotations(ImportAnnotationsRequest) returns (Operation)

Import Annotations to the Annotation store by loading data from the specified sources. If the request is successful, a detailed response is returned as of type ImportAnnotationsResponse, contained in the [response][google.longrunning.Operation.result.response] field when the operation finishes. The metadata field type is OperationMetadata. Errors are logged to Cloud Logging (see Viewing error logs in Cloud Logging).

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/cloud-healthcare
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
ListAnnotationStores

rpc ListAnnotationStores(ListAnnotationStoresRequest) returns (ListAnnotationStoresResponse)

Lists the Annotation stores in the given dataset for a source store.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/cloud-healthcare
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
ListAnnotations

rpc ListAnnotations(ListAnnotationsRequest) returns (ListAnnotationsResponse)

Lists the Annotations in the given Annotation store for a source resource.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/cloud-healthcare
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
UpdateAnnotation

rpc UpdateAnnotation(UpdateAnnotationRequest) returns (Annotation)

Updates the Annotation.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/cloud-healthcare
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
UpdateAnnotationStore

rpc UpdateAnnotationStore(UpdateAnnotationStoreRequest) returns (AnnotationStore)

Updates the specified Annotation store.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/cloud-healthcare
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

Annotation

An annotation record.

Fields
name

string

Identifier. Resource name of the Annotation, of the form projects/{project_id}/locations/{location_id}/datasets/{dataset_id}/annotationStores/{annotation_store_id}/annotations/{annotation_id}.
annotation_source

AnnotationSource

Required. Details of the source.
custom_data

map<string, string>

Additional information for this annotation record, such as annotator and verifier information or study campaign.

Union field data.

data can be only one of the following:
resource_annotation

ResourceAnnotation

Annotations for resource. For example, classification tags.
image_annotation

ImageAnnotation

Annotations for images. For example, bounding polygons.
text_annotation

SensitiveTextAnnotation

Annotations for sensitive texts. For example, a range that describes the location of sensitive text.

AnnotationSource

AnnotationSource holds the source information of the annotation.

Fields

Union field source.

source can be only one of the following:
cloud_healthcare_source

CloudHealthcareSource

Cloud Healthcare API resource.

CloudHealthcareSource

Cloud Healthcare API resource.

Fields
name

string

Full path of a Cloud Healthcare API resource.

AnnotationStore

An Annotation store that can store annotation resources such as labels and tags for text, image and audio.

Fields
name

string

Identifier. Resource name of the Annotation store, of the form projects/{project_id}/locations/{location_id}/datasets/{dataset_id}/annotationStores/{annotation_store_id}.
labels

map<string, string>

Optional. User-supplied key-value pairs used to organize Annotation stores.

Label keys must be between 1 and 63 characters long, have a UTF-8 encoding of maximum 128 bytes, and must conform to the following PCRE regular expression: [\p{Ll}\p{Lo}][\p{Ll}\p{Lo}\p{N}_-]{0,62}

Label values must be between 1 and 63 characters long, have a UTF-8 encoding of maximum 128 bytes, and must conform to the following PCRE regular expression: [\p{Ll}\p{Lo}\p{N}_-]{0,63}

No more than 64 labels can be associated with a given store.

AnnotationView

The optional view on Annotation.

Enums
ANNOTATION_VIEW_UNSPECIFIED Same as BASIC.
ANNOTATION_VIEW_BASIC Only name, annotation_source and custom_data fields are populated.
ANNOTATION_VIEW_FULL All fields are populated.

BigQueryDestination

The BigQuery table for export.

Fields
table_uri

string

BigQuery URI to a table, up to 2000 characters long, must be of the form bq://projectId.bqDatasetId.tableId.
force

bool

Use write_disposition instead. If write_disposition is specified, this parameter is ignored. force=false is equivalent to write_disposition=WRITE_EMPTY and force=true is equivalent to write_disposition=WRITE_TRUNCATE.
schema_type

SchemaType

Specifies the schema format to export.
write_disposition

WriteDisposition

Determines if existing data in the destination dataset is overwritten, appended to, or not written if the tables contain data. If a write_disposition is specified, the force parameter is ignored.

SchemaType

Enums
SCHEMA_TYPE_UNSPECIFIED Same as SIMPLE.
SIMPLE A flatterned version of Annotation.

WriteDisposition

The BigQuery WriteDispostion used by the export operation.

Enums
WRITE_DISPOSITION_UNSPECIFIED Default behavior is the same as WRITE_EMPTY.
WRITE_EMPTY Only export data if the destination table is empty.
WRITE_TRUNCATE Erase all existing data in a table before writing the instances.
WRITE_APPEND Append data to the existing table.

CreateAnnotationRequest

Creates an Annotation record for a source and adds it to Annotation store.

Fields
parent

string

Required. The name of the Annotation store this annotation belongs to. For example, projects/my-project/locations/us-central1/datasets/mydataset/annotationStores/myannotationstore.

Authorization requires the following IAM permission on the specified resource parent:

  • healthcare.annotations.create
annotation

Annotation

Required. Annotation to create.

CreateAnnotationStoreRequest

Request to create a new Annotation store.

Fields
parent

string

Required. The name of the dataset this Annotation store belongs to.

Authorization requires the following IAM permission on the specified resource parent:

  • healthcare.annotationStores.create
annotation_store_id

string

Required. The ID of the Annotation store that is being created. The string must match the following regex: [\p{L}\p{N}_\-\.]{1,256}.
annotation_store

AnnotationStore

Configuration info for this Annotation store.

DeleteAnnotationRequest

Deletes an Annotation from the specified Annotation store.

Fields
name

string

Required. The resource name of the Annotation to delete.

Authorization requires the following IAM permission on the specified resource name:

  • healthcare.annotations.delete

DeleteAnnotationStoreRequest

Deletes the specified Annotation store.

Fields
name

string

Required. The resource name of the Annotation store to delete.

Authorization requires the following IAM permission on the specified resource name:

  • healthcare.annotationStores.delete

EvaluateAnnotationStoreRequest

Request to evaluate an Annotation store against a ground truth [Annotation store].

Fields
name

string

Required. The Annotation store to compare against golden_store, in the format of projects/{project_id}/locations/{location_id}/datasets/{dataset_id}/annotationStores/{annotation_store_id}.

Authorization requires the following IAM permission on the specified resource name:

  • healthcare.annotationStores.evaluate
eval_info_type_mapping

map<string, string>

Optional. InfoType mapping for eval_store. Different resources can map to the same infoType. For example, PERSON_NAME, PERSON, NAME, and HUMAN are different. To map all of these into a single infoType (such as PERSON_NAME), specify the following mapping:

  info_type_mapping["PERSON"] = "PERSON_NAME"
  info_type_mapping["NAME"] = "PERSON_NAME"
  info_type_mapping["HUMAN"] = "PERSON_NAME"

Unmentioned infoTypes, such as DATE, are treated as identity mapping. For example:

  info_type_mapping["DATE"] = "DATE"

InfoTypes are case-insensitive.
golden_store

string

Required. The Annotation store to use as ground truth, in the format of projects/{project_id}/locations/{location_id}/datasets/{dataset_id}/annotationStores/{annotation_store_id}.
golden_info_type_mapping

map<string, string>

Optional. Similar to eval_info_type_mapping, infoType mapping for golden_store.
info_type_config

InfoTypeConfig
Union field report_destination. Specifies the report location. report_destination can be only one of the following:
bigquery_destination

BigQueryDestination

The BigQuery table where the server writes the output. BigQueryDestination requires the roles/bigquery.dataEditor and roles/bigquery.jobUser Cloud IAM roles.

InfoTypeConfig

Specifies how to use infoTypes for evaluation. For example, a user might only want to evaluate PERSON, LOCATION, and AGE.

Fields
strict_matching

bool

If TRUE, infoTypes described by filter are used for evaluation. Otherwise, infoTypes are not considered for evaluation. For example:

  • Annotated text: "Toronto is a location"
  • Finding 1: {"infoType": "PERSON", "quote": "Toronto", "start": 0, "end": 7}
  • Finding 2: {"infoType": "CITY", "quote": "Toronto", "start": 0, "end": 7}
  • Finding 3: {}
  • Ground truth: {"infoType": "LOCATION", "quote": "Toronto", "start": 0, "end": 7}

When strict_matching is TRUE:

  • Finding 1: 1 false positive
  • Finding 2: 1 false positive
  • Finding 3: 1 false negative

When strict_matching is FALSE:

  • Finding 1: 1 true positive
  • Finding 2: 1 true positive
  • Finding 3: 1 false negative
Union field filter. filter allows users to flexibly choose a subset of infoTypes for evaluation. If not specified, default behavior is to keep all infoTypes. filter can be only one of the following:
evaluate_list

FilterList
ignore_list

FilterList

FilterList

List of infoTypes to be filtered.

Fields
info_types[]

string

These infoTypes are based on after the eval_info_type_mapping and golden_info_type_mapping.

EvaluateAnnotationStoreResponse

This type has no fields.

Response for successful Annotation store evaluation operations. This structure is included in the response upon operation completion.

ExportAnnotationsRequest

Request to export Annotations. The export operation is not atomic. If a failure occurs, any annotations already exported are not removed.

Fields
name

string

Required. The name of the Annotation store to export annotations to, in the format of projects/{project_id}/locations/{location_id}/datasets/{dataset_id}/annotationStores/{annotation_store_id}.

Authorization requires the following IAM permission on the specified resource name:

  • healthcare.annotationStores.export
Union field destination. Destination for export. destination can be only one of the following:
gcs_destination

GcsDestination

The Cloud Storage destination, which requires the roles/storage.objectAdmin Cloud IAM role.
bigquery_destination

BigQueryDestination

The BigQuery output destination, which requires two IAM roles: roles/bigquery.dataEditor and roles/bigquery.jobUser.

ExportAnnotationsResponse

This type has no fields.

Response for successful annotation export operations. This structure is included in response upon operation completion.

GcsDestination

The Cloud Storage location for export.

Fields
uri_prefix

string

The Cloud Storage destination to export to. URI for a Cloud Storage directory where the server writes result files, in the format gs://{bucket-id}/{path/to/destination/dir}. If there is no trailing slash, the service appends one when composing the object path. The user is responsible for creating the Cloud Storage bucket referenced in uri_prefix.

GcsSource

Specifies the configuration for importing data from Cloud Storage.

Fields
uri

string

Points to a Cloud Storage URI containing file(s) with content only. The URI must be in the following format: gs://{bucket_id}/{object_id}. The URI can include wildcards in object_id and thus identify multiple files. Supported wildcards: '*' to match 0 or more non-separator characters '**' to match 0 or more characters (including separators). Must be used at the end of a path and with no other wildcards in the path. Can also be used with a file extension (such as .dcm), which imports all files with the extension in the specified directory and its sub-directories. For example, gs://my-bucket/my-directory/**.json imports all files with .json extensions in my-directory/ and its sub-directories. '?' to match 1 character All other URI formats are invalid. Files matching the wildcard are expected to contain content only, no metadata.

GetAnnotationRequest

Gets an Annotation from the specified Annotation store.

Fields
name

string

Required. The resource name of the Annotation to retrieve.

Authorization requires the following IAM permission on the specified resource name:

  • healthcare.annotations.get

GetAnnotationStoreRequest

Gets an Annotation store.

Fields
name

string

Required. The resource name of the Annotation store to get.

Authorization requires the following IAM permission on the specified resource name:

  • healthcare.annotationStores.get

ImageAnnotation

Image annotation.

Fields
bounding_polys[]

BoundingPoly

The list of polygons outlining the sensitive regions in the image.
frame_index

int32

0-based index of the image frame. For example, an image frame in a DICOM instance.

BoundingPoly

A bounding polygon for the detected image annotation.

Fields
vertices[]

Vertex

List of the vertices of this polygon.
label

string

A description of this polygon.

Vertex

A 2D coordinate in an image. The origin is the top-left.

Fields
x

float

X coordinate.
y

float

Y coordinate.

ImportAnnotationsRequest

Request to import Annotations. The Annotations to be imported must have client-supplied resource names which indicate the annotation resource. The import operation is not atomic. If a failure occurs, any annotations already imported are not removed.

Fields
name

string

Required. The name of the Annotation store to which the server imports annotations, in the format projects/{project_id}/locations/{location_id}/datasets/{dataset_id}/annotationStores/{annotation_store_id}.

Authorization requires the following IAM permission on the specified resource name:

  • healthcare.annotationStores.import

Union field source. The Annotation must be provided in JSON format of the Annotation. For example, an annotation might look like the following: json { "annotation_source": { "cloud_healthcare_source": { "name": "projects/test_project/locations/test_location/datasets/test_dataset/fhirStores/test_fhir_store/resources/test_type/test_id" } }, "text_annotation": { "details": { "patient/text/div/value": { "findings": [ { "info_type": "PERSON_NAME", "start": "4", "end": "12", "quote": "John Doe", }, { "info_type": "DATE", "start": "37", "end": "47", "quote": "1900-12-24", } ] }, "patient/birth_date/value_us": { "findings": [ { "info_type": "DATE", "start": "0", "end": "10", "quote": "1900-12-24", } ] } } } } Each file consists of exactly one annotation. source can be only one of the following:
gcs_source

GcsSource

ImportAnnotationsResponse

This type has no fields.

Final response of importing Annotations in successful case. This structure is included in the response. It is only included when the operation finishes.

ListAnnotationStoresRequest

Lists the Annotation stores in the given dataset, for a given source store.

Fields
parent

string

Required. Name of the dataset.

Authorization requires the following IAM permission on the specified resource parent:

  • healthcare.annotationStores.list
page_size

int32

Limit on the number of Annotation stores to return in a single response. If not specified, 100 is used. May not be larger than 1000.
page_token

string

The next_page_token value returned from the previous List request, if any.
filter

string

Restricts stores returned to those matching a filter. The following syntax is available:

  • A string field value can be written as text inside quotation marks, for example "query text". The only valid relational operation for text fields is equality (=), where text is searched within the field, rather than having the field be equal to the text. For example, "Comment = great" returns messages with great in the comment field.
  • A number field value can be written as an integer, a decimal, or an exponential. The valid relational operators for number fields are the equality operator (=), along with the less than/greater than operators (<, <=, >, >=). Note that there is no inequality (!=) operator. You can prepend the NOT operator to an expression to negate it.
  • A date field value must be written in yyyy-mm-dd form. Fields with date and time use the RFC3339 time format. Leading zeros are required for one-digit months and days. The valid relational operators for date fields are the equality operator (=) , along with the less than/greater than operators (<, <=, >, >=). Note that there is no inequality (!=) operator. You can prepend the NOT operator to an expression to negate it.
  • Multiple field query expressions can be combined in one query by adding AND or OR operators between the expressions. If a boolean operator appears within a quoted string, it is not treated as special, it's just another part of the character string to be matched. You can prepend the NOT operator to an expression to negate it.

Only filtering on labels is supported, for example labels.key=value.

ListAnnotationStoresResponse

Lists the Annotation stores in the given dataset.

Fields
annotation_stores[]

AnnotationStore

The returned Annotation stores. Won't be more Annotation stores than the value of page_size in the request.
next_page_token

string

Token to retrieve the next page of results or empty if there are no more results in the list.

ListAnnotationsRequest

Lists the Annotations in the specified Annotation store.

Fields
parent

string

Required. Name of the Annotation store to retrieve Annotations from.

Authorization requires the following IAM permission on the specified resource parent:

  • healthcare.annotations.list
page_size

int32

Limit on the number of Annotations to return in a single response. If not specified, 100 is used. May not be larger than 1000.
page_token

string

The next_page_token value returned from the previous List request, if any.
filter

string

Restricts Annotations returned to those matching a filter. Functions available for filtering are:

  • matches("annotation_source.cloud_healthcare_source.name", substring). Filter on cloud_healthcare_source.name. For example: matches("annotation_source.cloud_healthcare_source.name", "some source").

  • matches("annotation", substring). Filter on all fields of annotation. For example: matches("annotation", "some-content").

  • type("text"), type("image"), type("resource"). Filter on the type of annotation data.
view

AnnotationView

Controls which fields are populated in the response.

ListAnnotationsResponse

Lists the Annotations in the specified Annotation store.

Fields
annotations[]

Annotation

The returned Annotations. Won't be more values than the value of page_size in the request. See AnnotationView in the request for populated fields.
next_page_token

string

Token to retrieve the next page of results or empty if there are no more results in the list.

ResourceAnnotation

Resource level annotation.

Fields
label

string

A description of the annotation record.

SensitiveTextAnnotation

A TextAnnotation specifies a text range that includes sensitive information.

Fields
details

map<string, Detail>

Maps from a resource slice. For example, FHIR resource field path to a set of sensitive text findings. For example, Appointment.Narrative text1 --> {findings_1, findings_2, findings_3}

Detail

Contains multiple sensitive information findings for each resource slice.

Fields
findings[]

Finding

Finding

Fields
info_type

string

The type of information stored in this text range. For example, HumanName, BirthDate, or Address.
start

int64

Zero-based starting index of the found text, inclusively.
end

int64

Zero-based ending index of the found text, exclusively.
quote

string

The snippet of the sensitive text. This field is only populated during deidentification if store_quote is set to true in DeidentifyConfig.

UpdateAnnotationRequest

Request to update the given Annotation.

Fields
annotation

Annotation

Required. The annotation resource which updates the resource on the server. Only fields listed in update_mask are applied.

Authorization requires the following IAM permission on the specified resource annotation:

  • healthcare.annotations.update
update_mask

FieldMask

Required. The update mask applies to the resource. For the FieldMask definition, see https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask

UpdateAnnotationStoreRequest

Updates an Annotation store.

Fields
annotation_store

AnnotationStore

Required. The Annotation store resource that updates the resource on the server. Only updating labels is supported.

Authorization requires the following IAM permission on the specified resource annotationStore:

  • healthcare.annotationStores.update
update_mask

FieldMask

Required. The update mask applies to the resource. For the FieldMask definition, see https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask