En esta página, se explica cómo administrar los recursos de FHIR mediante la ejecución de paquetes de FHIR que es una colección de recursos y operaciones de FHIR para realizar en aquellos recursos de FHIR.
El
ExecuteBundle
implementa el estándar FHIR de interacción de transacción/lote
(DSTU2,
STU3
y R4) y las operaciones de historial.
Paquetes de FHIR
Un paquete de FHIR contiene un arreglo de entradas, cada una de las cuales representa una operación, como crear, actualizar o borrar dentro de un recurso, como una observación o un paciente. Consulta las descripciones detalladas de los elementos en el recurso Bundle.
Cuando ejecutas un paquete de FHIR, el tipo de paquete determina cómo se ejecutan las operaciones se realizan los paquetes. Están disponibles los siguientes tipos de paquetes:
batch
: Ejecuta las operaciones como varias solicitudes independientes.transaction
: Ejecuta las operaciones como varias solicitudes que dependen unas de otras.history
: Inserta las entradas en el historial de un recurso.
Por ejemplo, supongamos que un paquete de transacciones incluye la creación de un recurso Patient y un recurso de observación. Si la solicitud de creación del recurso de paciente falla, no se crea el recurso de observación.
Si una operación falla cuando el tipo de paquete es batch
, la API de Cloud Healthcare ejecuta las operaciones restantes en el paquete. Si una operación falla cuando el tipo de paquete es transaction
, la API de Cloud Healthcare deja de ejecutar las operaciones y revierte la transacción.
Paquetes de historial
Los paquetes de historial son extensiones personalizadas del estándar FHIR que admiten casos de uso de copia de seguridad y restablecimiento, como la sincronización. Puedes usar paquetes de historial para insertar o reemplazar versiones de recursos en el historial de un recurso de FHIR. Solo puedes quitar versiones de recursos con el
Resource-purge
. El paquete history
se ejecuta como una sola transacción con límite.
de 100 entradas por paquete. Si la versión de un recurso del paquete history
tiene
una marca de tiempo mayor que la versión más reciente en el almacén de FHIR,
la última versión se actualizará según corresponda. Si el paquete history
se inserta correctamente, se muestra una respuesta vacía. De lo contrario, se muestra un OperationOutcome
que describe la falla.
La compatibilidad con los paquetes de historial no está habilitada de forma predeterminada. Un administrador de almacenes de FHIR
establece enableHistoryModifications
en true
en el
Configuración del almacén de FHIR.
No puedes usar paquetes del historial si disableResourceVersioning
es
establecida en true
en la configuración del almacén de FHIR.
Los paquetes de historial se proporcionan en el mismo formato en el que se devuelven del
fhir.history
. Para ser válida, cada entrada de paquete requiere un ID de recurso, una marca de tiempo de modificación y un estado. Además, todas las entradas deben tener el mismo ID de recurso. El
el ID de recurso se proporciona con el campo resource.id
o request.url
. Si se proporcionan campos, el ID de recurso proporcionado será el mismo. Se proporciona la marca de tiempo del recurso
con el campo meta.lastUpdated
en el recurso o el
response.lastModified
.
Otorga permisos para ejecutar paquetes
Se requiere la función de permiso datasets.fhirStores.fhir.executeBundle
para ejecutar paquetes. Para otorgar este permiso, usa la función healthcare.fhirResourceReader
. Si deseas conocer los pasos para otorgar este permiso, consulta Modifica una política.
Para ejecutar paquetes de historial, también se requiere el rol de permiso datasets.fhirStores.fhir.import
.
La API de Cloud Healthcare verifica los permisos para cada operación del paquete.
Si tienes el permiso healthcare.fhirResources.create
, pero no el permiso healthcare.fhirResources.update
, solo puedes ejecutar paquetes que contengan operaciones healthcare.fhirResources.create
.
Ejecuta un paquete
Para ejecutar un paquete de FHIR, usa el método projects.locations.datasets.fhirStores.fhir.executeBundle
.
En las siguientes muestras, BUNDLE.json es la ruta y el nombre de archivo de un paquete de FHIR con codificación JSON. También puedes incluir el paquete en el cuerpo de la solicitud.
En el siguiente paquete de muestra, se crea un recurso paciente y se borra otro recurso paciente:
{
"resourceType": "Bundle",
"id": "bundle-transaction",
"meta": {
"lastUpdated": "2018-03-11T11:22:16Z"
},
"type": "transaction",
"entry": [
{
"resource": {
"resourceType": "Patient",
"name": [
{
"family": "Smith",
"given": [
"Darcy"
]
}
],
"gender": "female",
"address": [
{
"line": [
"123 Main St."
],
"city": "Anycity",
"state": "CA",
"postalCode": "12345"
}
]
},
"request": {
"method": "POST",
"url": "Patient"
}
},
{
"request": {
"method": "DELETE",
"url": "Patient/1234567890"
}
}
]
}
En los siguientes ejemplos, se muestra cómo ejecutar un paquete.
curl
Para ejecutar un paquete, realiza una solicitud POST
y especifica la siguiente información:
- El nombre y la ubicación del conjunto de datos superior y el almacén de FHIR
- La ubicación del archivo de paquete en tu máquina local
- Un token de acceso
En el siguiente ejemplo, se muestra una solicitud POST
mediante curl.
curl -X POST \ -H "Content-Type: application/fhir+json; charset=utf-8" \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ --data @BUNDLE_FILE.json \ "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir"
Sin importar el resultado de las operaciones individuales, después de ejecutar un paquete de lotes, el servidor muestra una representación codificada en JSON de un recurso Bundle
de tipo batch-response
. El recurso Bundle
contiene una entrada para cada entrada en la solicitud con el resultado del procesamiento de la entrada, que puede ser una combinación de resultados de éxito y error.
Si un paquete de transacciones es exitoso, el servidor muestra una representación codificada en JSON de un recurso Bundle
de tipo transaction-response
que contiene una entrada por cada entrada en la solicitud con el resultado correcto de la operación.
Si se produce un error mientras se ejecuta un paquete de transacciones, el cuerpo de la respuesta no contiene un paquete. En su lugar, contiene un recurso OperationOutcome
codificado en JSON que describe el motivo del error. Las operaciones exitosas que se revirtieron no se informan en la respuesta.
El siguiente paquete de muestra es el resultado de la ejecución correcta del ejemplo anterior. La primera entrada indica el éxito de la operación para crear un Paciente e incluye el ID del nuevo recurso. La segunda entrada indica el éxito de la operación de eliminación.
{ "entry": [ { "response": { "location": projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE/RESOURCE_ID, "status": "201 Created" } }, { "response": { "status": "200 OK" } } ], "resourceType": "Bundle", "type": "transaction-response" }
PowerShell
Para ejecutar un paquete, realiza una solicitud POST
y especifica la siguiente información:
- El nombre y la ubicación del conjunto de datos superior y el almacén de FHIR
- La ubicación del archivo de paquete en tu máquina local
- Un token de acceso
En el siguiente ejemplo, se muestra una solicitud POST
mediante Windows PowerShell.
$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } Invoke-RestMethod ` -Method Post ` -Headers $headers ` -ContentType: "application/fhir+json" ` -InFile BUNDLE_FILE.json ` -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir" | ConvertTo-Json
Sin importar el resultado de las operaciones individuales, después de ejecutar un paquete de lotes, el servidor muestra una representación codificada en JSON de un recurso Bundle
de tipo batch-response
. El recurso Bundle
contiene una entrada para cada entrada en la solicitud con el resultado del procesamiento de la entrada, que puede ser una combinación de resultados de éxito y error.
Si un paquete de transacciones es exitoso, el servidor muestra una representación codificada en JSON de un recurso Bundle
de tipo transaction-response
que contiene una entrada por cada entrada en la solicitud con el resultado correcto de la operación.
Si se produce un error mientras se ejecuta un paquete de transacciones, el cuerpo de la respuesta no contiene un paquete. En su lugar, contiene un recurso OperationOutcome
codificado en JSON que describe el motivo del error. Las operaciones exitosas que se revirtieron no se informan en la respuesta.
El siguiente paquete de muestra es el resultado de la ejecución correcta del ejemplo anterior. La primera entrada indica el éxito de la operación para crear un Paciente e incluye el ID del nuevo recurso. La segunda entrada indica el éxito de la operación de eliminación.
{ "entry": [ { "response": { "etag": "ETAG", "lastModified": "2020-08-03T04:12:47.312669+00:00", "location": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE/RESOURCE_ID", "status": "201 Created" } }, { "response": { "etag": "ETAG", "lastModified": "2020-08-03T04:12:47.312669+00:00", "status": "200 OK" } } ], "resourceType": "Bundle", "type": "transaction-response" }
Go
Java
Node.js
Hay un archivo de paquete de muestra disponible en el repositorio de GitHub de muestra de código.
Python
Hay un archivo de paquete de muestra disponible en el repositorio de GitHub de muestra de código.
Haz una solicitud PATCH
Puedes usar paquetes de FHIR para realizar solicitudes PATCH
de JSON en los recursos de FHIR.
Consulta Ejecuta una solicitud PATCH
en un paquete de FHIR.
para obtener más información.
Resuelve referencias a recursos creados en un paquete
Los recursos de un paquete de transacciones pueden contener referencias a recursos que no existen en el sistema de destino, pero que se crean durante la ejecución del paquete. La API de Cloud Healthcare resuelve la asociación entre los recursos mediante el campo entry.fullUrl
. Las referencias que coinciden con el valor entry.fullUrl
de otro recurso del paquete se vuelven a escribir con el ID del recurso correspondiente en el almacén. Esto tiene éxito sin importar el orden de las operaciones en el paquete.
La API de Cloud Healthcare acepta la fullUrl
en los siguientes formatos:
urn:uuid:UUID
urn:oid:OID
- cualquier URL
- un nombre de recurso en el formato
RESOURCE_TYPE/RESOURCE_ID
, comoPatient/123
No se recomienda usar este formato porque elfullUrl
es un marcador de posición local del paquete. Esto puede crear confusión si un recurso del almacén tiene el mismo nombre, pero el recurso del paquete obtiene un nombre diferente como resultado de una operación de creación.
En el siguiente conjunto de muestras, se crea un recurso de paciente y un recurso de observación que hace referencia al recurso de paciente.
{
"resourceType": "Bundle",
"type": "transaction",
"entry":[
{
"request": {
"method":"POST",
"url":"Patient"
},
"fullUrl": "urn:uuid:05efabf0-4be2-4561-91ce-51548425acb9",
"resource": {
"resourceType":"Patient",
"gender":"male"
}
},
{
"request": {
"method":"POST",
"url":"Observation"
},
"resource": {
"resourceType":"Observation",
"subject": {
"reference": "urn:uuid:05efabf0-4be2-4561-91ce-51548425acb9"
},
"status":"preliminary",
"code": {
"text":"heart rate"
}
}
}
]
}
En los siguientes ejemplos, se muestra cómo ejecutar un paquete.
curl
Hay un archivo de paquete de muestra disponible en el repositorio de GitHub de muestra de código.
Para ejecutar un paquete, realiza una solicitud POST y especifica la siguiente información:
- El nombre y la ubicación del conjunto de datos superior y el almacén de FHIR
- La ubicación del archivo Paquete en Cloud Storage
- Un token de acceso
En el siguiente ejemplo, se muestra una solicitud POST
mediante curl.
curl -X POST \ -H "Content-Type: application/fhir+json; charset=utf-8" \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ --data @BUNDLE_FILE.json \ "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir"
El siguiente paquete de muestra es el resultado de la ejecución correcta del ejemplo anterior. La primera entrada indica el éxito de la operación para crear un Paciente e incluye el ID del nuevo recurso. La segunda entrada indica el éxito de la operación para crear la observación y, además, incluye el ID del recurso nuevo.
{ "entry": [ { "response": { "etag": "ETAG1", "lastModified": "2020-08-04T16:14:14.273976+00:00", "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/datasets/REGION/fhirStores/FHIR_STORE_ID/fhir/Patient/PATIENT_ID/_history/HISTORY_ID", "status": "201 Created" } }, { "response": { "etag": "ETAG", "lastModified": "2020-08-04T16:14:14.273976+00:00", "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/datasets/REGION/fhirStores/FHIR_STORE_ID/fhir/Observation/OBSERVATION_ID/_history/HISTORY_ID", "status": "201 Created" } } ], "resourceType": "Bundle", "type": "transaction-response" }
PowerShell
Hay un archivo de paquete de muestra disponible en el repositorio de GitHub de muestra de código.
Para ejecutar un paquete, realiza una solicitud POST y especifica la siguiente información:
- El nombre y la ubicación del conjunto de datos superior y el almacén de FHIR
- La ubicación del archivo Paquete en Cloud Storage
- Un token de acceso
En el siguiente ejemplo, se muestra una solicitud POST
mediante Windows PowerShell.
$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } Invoke-RestMethod ` -Method Post ` -Headers $headers ` -ContentType: "application/fhir+json" ` -InFile BUNDLE_FILE.json ` -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir" | ConvertTo-Json
El siguiente paquete de muestra es el resultado de la ejecución correcta del ejemplo anterior. La primera entrada indica el éxito de la operación para crear un Paciente e incluye el ID del nuevo recurso. La segunda entrada indica el éxito de la operación para crear la observación y, además, incluye el ID del recurso nuevo.
{ "entry": [ { "response": { "etag": "ETAG1", "lastModified": "2020-08-04T16:14:14.273976+00:00", "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/datasets/REGION/fhirStores/FHIR_STORE_ID/fhir/Patient/PATIENT_ID/_history/HISTORY_ID", "status": "201 Created" } }, { "response": { "etag": "ETAG", "lastModified": "2020-08-04T16:14:14.273976+00:00", "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/datasets/REGION/fhirStores/FHIR_STORE_ID/fhir/Observation/OBSERVATION_ID/_history/HISTORY_ID", "status": "201 Created" } } ], "resourceType": "Bundle", "type": "transaction-response" }