Package google.cloud.healthcare.v1.fhir

Index

FhirStoreService

A service for handling FHIR stores inside a healthcare dataset.

CreateFhirStore

rpc CreateFhirStore(CreateFhirStoreRequest) returns (FhirStore)

Creates a new FHIR 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.
DeleteFhirStore

rpc DeleteFhirStore(DeleteFhirStoreRequest) returns (Empty)

Deletes the specified FHIR store and removes all resources 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.
ExportResources

rpc ExportResources(ExportResourcesRequest) returns (Operation)

Export resources from the FHIR store to the specified destination.

This method returns an Operation that can be used to track the status of the export by calling GetOperation.

Immediate fatal errors appear in the error field, errors are also logged to Cloud Logging (see Viewing logs). Otherwise, when the operation finishes, a detailed response of type ExportResourcesResponse is returned in the response field. The metadata field type for this operation is OperationMetadata.

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.
GetFhirStore

rpc GetFhirStore(GetFhirStoreRequest) returns (FhirStore)

Gets the configuration of the specified FHIR 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.
ImportResources

rpc ImportResources(ImportResourcesRequest) returns (Operation)

Imports resources to the FHIR store by loading data from the specified sources. This method is optimized to load large quantities of data using import semantics that ignore some FHIR store configuration options and are not suitable for all use cases. It is primarily intended to load data into an empty FHIR store that is not being used by other clients. In cases where this method is not appropriate, consider using [ExecuteBundle][] to load data.

Every resource in the input must contain a client-supplied ID. Each resource is stored using the supplied ID regardless of the enable_update_create setting on the FHIR store. It is strongly advised not to include or encode any sensitive data such as patient identifiers in client-specified resource IDs. Those IDs are part of the FHIR resource path recorded in Cloud audit logs and Cloud Pub/Sub notifications. Those IDs can also be contained in reference fields within other resources.

The import process does not enforce referential integrity, regardless of the disable_referential_integrity setting on the FHIR store. This allows the import of resources with arbitrary interdependencies without considering grouping or ordering, but if the input data contains invalid references or if some resources fail to be imported, the FHIR store might be left in a state that violates referential integrity.

The import process does not trigger Pub/Sub notification or BigQuery streaming update, regardless of how those are configured on the FHIR store.

If a resource with the specified ID already exists, the most recent version of the resource is overwritten without creating a new historical version, regardless of the disable_resource_versioning setting on the FHIR store. If transient failures occur during the import, it's possible that successfully imported resources will be overwritten more than once.

The import operation is idempotent unless the input data contains multiple valid resources with the same ID but different contents. In that case, after the import completes, the store contains exactly one resource with that ID but there is no ordering guarantee on which version of the contents it will have. The operation result counters do not count duplicate IDs as an error and count one success for each resource in the input, which might result in a success count larger than the number of resources in the FHIR store. This often occurs when importing data organized in bundles produced by [Patient-everything][GetPatientEverything] where each bundle contains its own copy of a resource such as Practitioner that might be referred to by many patients.

If some resources fail to import, for example due to parsing errors, successfully imported resources are not rolled back.

The location and format of the input data is specified by the parameters in ImportResourcesRequest. Note that if no format is specified, this method assumes the BUNDLE format. When using the BUNDLE format this method ignores the Bundle.type field, except that history bundles are rejected, and does not apply any of the bundle processing semantics for batch or transaction bundles. Unlike in [ExecuteBundle][], transaction bundles are not executed as a single transaction and bundle-internal references are not rewritten. The bundle is treated as a collection of resources to be written as provided in Bundle.entry.resource, ignoring Bundle.entry.request. As an example, this allows the import of searchset bundles produced by a [FHIR search][SearchResources] or [Patient-everything][GetPatientEverything] operation.

This method returns an Operation that can be used to track the status of the import by calling GetOperation.

Immediate fatal errors appear in the error field, errors are also logged to Cloud Logging (see Viewing logs). Otherwise, when the operation finishes, a detailed response of type ImportResourcesResponse is returned in the response field. The metadata field type for this operation is OperationMetadata.

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.
ListFhirStores

rpc ListFhirStores(ListFhirStoresRequest) returns (ListFhirStoresResponse)

Lists the FHIR stores in the given 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.
UpdateFhirStore

rpc UpdateFhirStore(UpdateFhirStoreRequest) returns (FhirStore)

Updates the configuration of the specified FHIR 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.

BigQueryDestination

The configuration for exporting to BigQuery.

Fields
dataset_uri

string

BigQuery URI to an existing dataset, up to 2000 characters long, in the format bq://projectId.bqDatasetId.
schema_config

SchemaConfig

The configuration for the exported BigQuery schema.
force

bool

If this flag is TRUE, all tables are deleted from the dataset before the new exported tables are written. If the flag is not set and the destination dataset contains tables, the export call returns an error.

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.
write_disposition

WriteDisposition

Determines whether existing tables in the destination dataset are overwritten or appended to. If a write_disposition is specified, the force parameter is ignored.

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 tables are empty.
WRITE_TRUNCATE Erase all existing data in a tables before writing the instances.
WRITE_APPEND Append data to the existing tables.

CreateFhirStoreRequest

Creates a new FHIR store.

Fields
parent

string

The name of the dataset this FHIR store belongs to.

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

  • healthcare.fhirStores.create
fhir_store_id

string

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

FhirStore

Configuration info for this FHIR store.

DeleteFhirStoreRequest

Deletes the specified FHIR store.

Fields
name

string

The resource name of the FHIR store to delete.

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

  • healthcare.fhirStores.delete

ExportResourcesRequest

Request to export resources.

Fields
name

string

The name of the FHIR store to export resource from, in the format of projects/{project_id}/locations/{location_id}/datasets/{dataset_id}/fhirStores/{fhir_store_id}.

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

  • healthcare.fhirStores.export

Union field destination. The output destination of the export.

To enable the Cloud Healthcare API to write to resources in your project such as Cloud Storage buckets, you must give the consumer Cloud Healthcare API service account the proper permissions. The service account is: service-{PROJECT_NUMBER}@gcp-sa-healthcare.iam.gserviceaccount.com. The PROJECT_NUMBER identifies the project that contains the source FHIR store. To get the project number, go to the GCP Console Dashboard. destination can be only one of the following:
gcs_destination

GcsDestination

The Cloud Storage output destination.

The Healthcare Service Agent account requires the roles/storage.objectAdmin role on the Cloud Storage location.

The exported outputs are organized by FHIR resource types. The server creates one object per resource type. Each object contains newline delimited JSON, and each line is a FHIR resource.
bigquery_destination

BigQueryDestination

The BigQuery output destination.

The Cloud Healthcare Service Agent requires two IAM roles on the BigQuery location: roles/bigquery.dataEditor and roles/bigquery.jobUser.

The output is one BigQuery table per resource type.

ExportResourcesResponse

Response when all resources export successfully. This structure is included in the response to describe the detailed outcome after the operation finishes successfully.

FhirStore

Represents a FHIR store.

Fields
name

string

Output only. Resource name of the FHIR store, of the form projects/{project_id}/datasets/{dataset_id}/fhirStores/{fhir_store_id}.
enable_update_create

bool

Whether this FHIR store has the updateCreate capability. This determines if the client can use an Update operation to create a new resource with a client-specified ID. If false, all IDs are server-assigned through the Create operation and attempts to update a non-existent resource return errors. It is strongly advised not to include or encode any sensitive data such as patient identifiers in client-specified resource IDs. Those IDs are part of the FHIR resource path recorded in Cloud audit logs and Cloud Pub/Sub notifications. Those IDs can also be contained in reference fields within other resources.
notification_config

NotificationConfig

If non-empty, publish all resource modifications of this FHIR store to this destination. The Cloud Pub/Sub message attributes contain a map with a string describing the action that has triggered the notification. For example, "action":"CreateResource".
disable_referential_integrity

bool

Immutable. Whether to disable referential integrity in this FHIR store. This field is immutable after FHIR store creation. The default value is false, meaning that the API enforces referential integrity and fails the requests that result in inconsistent state in the FHIR store. When this field is set to true, the API skips referential integrity checks. Consequently, operations that rely on references, such as GetPatientEverything, do not return all the results if broken references exist.
disable_resource_versioning

bool

Immutable. Whether to disable resource versioning for this FHIR store. This field can not be changed after the creation of FHIR store. If set to false, which is the default behavior, all write operations cause historical versions to be recorded automatically. The historical versions can be fetched through the history APIs, but cannot be updated. If set to true, no historical versions are kept. The server sends errors for attempts to read the historical versions.
labels

map<string, string>

User-supplied key-value pairs used to organize FHIR 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 are optional, 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.
version

Version

Immutable. The FHIR specification version that this FHIR store supports natively. This field is immutable after store creation. Requests are rejected if they contain FHIR resources of a different version. Version is required for every FHIR store.
stream_configs[]

StreamConfig

A list of streaming configs that configure the destinations of streaming export for every resource mutation in this FHIR store. Each store is allowed to have up to 10 streaming configs. After a new config is added, the next resource mutation is streamed to the new location in addition to the existing ones. When a location is removed from the list, the server stops streaming to that location. Before adding a new config, you must add the required bigquery.dataEditor role to your project's Cloud Healthcare Service Agent service account. Some lag (typically on the order of dozens of seconds) is expected before the results show up in the streaming destination.

StreamConfig

Contains configuration for streaming FHIR export.

Fields
resource_types[]

string

Supply a FHIR resource type (such as "Patient" or "Observation"). See https://www.hl7.org/fhir/valueset-resource-types.html for a list of all FHIR resource types. The server treats an empty list as an intent to stream all the supported resource types in this FHIR store.
bigquery_destination

BigQueryDestination

The destination BigQuery structure that contains both the dataset location and corresponding schema config.

The output is organized in one table per resource type. The server reuses the existing tables (if any) that are named after the resource types. For example, "Patient", "Observation". When there is no existing table for a given resource type, the server attempts to create one.

When a table schema doesn't align with the schema config, either because of existing incompatible schema or out of band incompatible modification, the server does not stream in new data.

BigQuery imposes a 1 MB limit on streaming insert row size, therefore any resource mutation that generates more than 1 MB of BigQuery data is not streamed.

One resolution in this case is to delete the incompatible table and let the server recreate one, though the newly created table only contains data after the table recreation.

Results are appended to the corresponding BigQuery tables. Different versions of the same resource are distinguishable by the meta.versionId and meta.lastUpdated columns. The operation (CREATE/UPDATE/DELETE) that results in the new version is recorded in the meta.tag.

The tables contain all historical resource versions since streaming was enabled. For query convenience, the server also creates one view per table of the same name containing only the current resource version.

The streamed data in the BigQuery dataset is not guaranteed to be completely unique. The combination of the id and meta.versionId columns should ideally identify a single unique row. But in rare cases, duplicates may exist. At query time, users may use the SQL select statement to keep only one of the duplicate rows given an id and meta.versionId pair. Alternatively, the server created view mentioned above also filters out duplicates.

If a resource mutation cannot be streamed to BigQuery, errors are logged to Cloud Logging. For more information, see Viewing error logs in Cloud Logging).

Version

The FHIR specification version.

Enums
VERSION_UNSPECIFIED Users must specify a version on store creation or an error is returned.
DSTU2 Draft Standard for Trial Use, Release 2
STU3 Standard for Trial Use, Release 3
R4 Release 4

GcsDestination

The configuration for exporting to Cloud Storage.

Fields
uri_prefix

string

URI for a Cloud Storage directory where result files should be written, in the format of 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) to import.

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 .ndjson), which imports all files with the extension in the specified directory and its sub-directories. For example, gs://my-bucket/my-directory/**.ndjson imports all files with .ndjson extensions in my-directory/ and its sub-directories.
  • ? to match 1 character

Files matching the wildcard are expected to contain content only, no metadata.

GetFhirStoreRequest

Gets a FHIR store.

Fields
name

string

The resource name of the FHIR store to get.

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

  • healthcare.fhirStores.get

ImportResourcesRequest

Request to import resources.

Fields
name

string

The name of the FHIR store to import FHIR resources to, in the format of projects/{project_id}/locations/{location_id}/datasets/{dataset_id}/fhirStores/{fhir_store_id}.

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

  • healthcare.fhirStores.import
content_structure

ContentStructure

The content structure in the source location. If not specified, the server treats the input source files as BUNDLE.
gcs_source

GcsSource

Cloud Storage source data location and import configuration.

The Healthcare Service Agent account requires the roles/storage.objectAdmin role on the Cloud Storage location.

Each Cloud Storage object should be a text file that contains the format specified in ContentStructure.

ContentStructure

The content structure of the input source files.

Enums
CONTENT_STRUCTURE_UNSPECIFIED If the content structure is not specified, the default value BUNDLE is used.
BUNDLE The source file contains one or more lines of newline-delimited JSON (ndjson). Each line is a bundle that contains one or more resources.
RESOURCE The source file contains one or more lines of newline-delimited JSON (ndjson). Each line is a single resource.
BUNDLE_PRETTY The entire file is one JSON bundle. The JSON can span multiple lines.
RESOURCE_PRETTY The entire file is one JSON resource. The JSON can span multiple lines.

ImportResourcesResponse

Final response of importing resources. This structure is included in the response to describe the detailed outcome after the operation finishes successfully.

ListFhirStoresRequest

Lists the FHIR stores in the given dataset.

Fields
parent

string

Name of the dataset.

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

  • healthcare.fhirStores.list
page_size

int32

Limit on the number of FHIR 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.

ListFhirStoresResponse

Lists the FHIR stores in the given dataset.

Fields
fhir_stores[]

FhirStore

The returned FHIR stores. Won't be more FHIR 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.

SchemaConfig

Configuration for the FHIR BigQuery schema. Determines how the server generates the schema.

Fields
schema_type

SchemaType

Specifies the output schema type. Schema type is required.
recursive_structure_depth

int64

The depth for all recursive structures in the output analytics schema. For example, concept in the CodeSystem resource is a recursive structure; when the depth is 2, the CodeSystem table will have a column called concept.concept but not concept.concept.concept. If not specified or set to 0, the server will use the default value 2. The maximum depth allowed is 5.

SchemaType

An enum consisting of the supported output schema types.

Enums
SCHEMA_TYPE_UNSPECIFIED No schema type specified. This type is unsupported.
ANALYTICS

Analytics schema defined by the FHIR community. See https://github.com/FHIR/sql-on-fhir/blob/master/sql-on-fhir.md.

BigQuery only allows a maximum of 10,000 columns per table. Due to this limitation, the server will not generate schemas for fields of type Resource, which can hold any resource type. The affected fields are Parameters.parameter.resource, Bundle.entry.resource, and Bundle.entry.response.outcome.

UpdateFhirStoreRequest

Updates a FHIR store.

Fields
fhir_store

FhirStore

The FHIR store that updates the resource in the server. Only fields listed in the update_mask are applied.

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

  • healthcare.fhirStores.update
update_mask

FieldMask

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