En esta página, se explica cómo administrar recursos de FHIR mediante la ejecución de paquetes de FHIR, que son una colección de recursos y operaciones de FHIR para realizar en esos recursos.
El método ExecuteBundle
implementa la interacción por lotes/transacción estándar de FHIR (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 realizan las operaciones dentro de él. Los siguientes tipos de paquetes están disponibles:
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 de paciente 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 historia
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 método Resource-purge
. El paquete history
se ejecuta como una sola transacción con un límite de 100 entradas por paquete. Si una versión de un recurso en el paquete history
tiene una marca de tiempo superior a la versión más reciente en la tienda de FHIR, la versión más reciente 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 del almacén de FHIR debe establecer enableHistoryModifications
en true
en la configuración del almacén de FHIR.
No puedes usar paquetes de historial si disableResourceVersioning
está configurado como true
en la configuración del almacén de FHIR.
Los paquetes de historial se proporcionan en el mismo formato en el que se muestran desde el método 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 ID de recurso se proporciona con el campo resource.id
o el campo request.url
. Si se proporcionan campos, el ID del recurso proporcionado debe ser el mismo. La marca de tiempo del recurso se proporciona con el campo meta.lastUpdated
en el recurso o el campo 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 JSON PATCH
en recursos de FHIR.
Consulta Cómo ejecutar 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" }