Recupera recursos FHIR con la recuperación de un momento determinado (PITR)

En esta página, se describe cómo usar la recuperación de un momento determinado (PITR) para recuperar los recursos de FHIR en un almacén de FHIR a un estado en los últimos 21 días. Puedes usar la PITR para recuperarte de cambios no deseados, como borrar recursos de FHIR de forma accidental.

Antes de comenzar

Las solicitudes de PITR se clasifican como solicitudes de operaciones avanzadas y se facturan según corresponda. Antes de usar la PITR, revisa los precios de las solicitudes de operaciones avanzadas.

Historial de versiones de recursos de FHIR y PITR

La PITR no depende del historial de versiones de recursos de FHIR. Puedes usar la PITR si el campo disableResourceVersioning de un almacén de FHIR es true o si las versiones históricas de un recurso de FHIR se borraron definitivamente.

Flujo de trabajo de recuperación

Para garantizar que una recuperación de producción se ejecute como se espera, primero haz una ejecución de prueba. La ejecución de prueba genera uno o más archivos que contienen los ID y los tipos de los recursos de FHIR que se recuperarán. Verifica que los archivos de salida sean correctos antes de volver a ejecutar la recuperación en production.

Para recuperar recursos específicos o recuperar recursos de acuerdo con un criterio de filtrado, especifica un filtro.

Haz una prueba de validación

Antes de recuperar los recursos de FHIR en producción, realiza una ejecución de prueba.

En los siguientes ejemplos, se muestra cómo realizar una ejecución de prueba con el método fhirStores.rollback.

REST

  1. Recupera los recursos de FHIR.

    Para realizar una ejecución de prueba, asegúrate de que el campo force sea false.

    Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

    • PROJECT_IDEl ID de tu proyecto de Google Cloud.
    • LOCATION: La ubicación del conjunto de datos
    • DATASET_ID es el conjunto de datos superior del almacén de FHIR
    • FHIR_STORE_ID: El ID del almacén de FHIR
    • RECOVERY_TIMESTAMP: Es un punto de recuperación en los últimos 21 días. Usa el formato RFC 3339. Especifica el tiempo hasta el segundo e incluye una zona horaria, por ejemplo, 2015-02-07T13:28:17.239+02:00 o 2017-01-01T00:00:00Z.
    • CLOUD_STORAGE_BUCKET: Es el URI completamente calificado de una carpeta o un bucket de Cloud Storage en el que se escriben los archivos de salida.

    Cuerpo JSON de la solicitud: 

    {
  "rollbackTime": "RECOVERY_TIMESTAMP",
  "resultGcsBucket": "gs://CLOUD_STORAGE_BUCKET",
  "force": "false"
}

    Para enviar tu solicitud, elige una de estas opciones:

    curl

    Guarda el cuerpo de la solicitud en un archivo llamado request.json. Ejecuta el comando siguiente en la terminal para crear o reemplazar este archivo en el directorio actual: 

    cat > request.json << 'EOF'
{
  "rollbackTime": "RECOVERY_TIMESTAMP",
  "resultGcsBucket": "gs://CLOUD_STORAGE_BUCKET",
  "force": "false"
}
EOF

    Luego, ejecuta el siguiente comando para enviar tu solicitud de REST: 

    curl -X POST \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json; charset=utf-8" \
         -d @request.json \
         "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:rollback"

    PowerShell

    Guarda el cuerpo de la solicitud en un archivo llamado request.json. Ejecuta el comando siguiente en la terminal para crear o reemplazar este archivo en el directorio actual: 

    @'
{
  "rollbackTime": "RECOVERY_TIMESTAMP",
  "resultGcsBucket": "gs://CLOUD_STORAGE_BUCKET",
  "force": "false"
}
'@  | Out-File -FilePath request.json -Encoding utf8

    Luego, ejecuta el siguiente comando para enviar tu solicitud de REST: 

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

    Invoke-WebRequest `
        -Method POST `
        -Headers $headers `
        -ContentType: "application/json; charset=utf-8" `
        -InFile request.json `
        -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:rollback" | Select-Object -Expand Content

    Explorador de APIs

    Copia el cuerpo de la solicitud y abre la página de referencia del método. El panel del Explorador de API se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Pega el cuerpo de la solicitud en esta herramienta, completa cualquier otro campo obligatorio y haz clic en Ejecutar.

    Este es el resultado. La respuesta contiene un identificador para una operación de larga duración (LRO). Las operaciones de larga duración se muestran cuando las llamadas de métodos pueden tardar más en completarse. Toma nota del valor de OPERATION_ID. Necesitarás este valor en el paso siguiente.

  2. Usa el método projects.locations.datasets.operations.get para obtener el estado de la operación de larga duración.

    Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

    • PROJECT_IDEl ID de tu proyecto de Google Cloud.
    • DATASET_ID: El ID del conjunto de datos
    • LOCATION: La ubicación del conjunto de datos
    • OPERATION_ID: Es el ID que muestra la operación de larga duración.

    Para enviar tu solicitud, elige una de estas opciones:

    curl

    Ejecuta el siguiente comando: 

    curl -X GET \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"

    PowerShell

    Ejecuta el siguiente comando: 

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

    Invoke-WebRequest `
        -Method GET `
        -Headers $headers `
        -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" | Select-Object -Expand Content

    Explorador de APIs

    Abre la página de referencia del método. El panel del Explorador de API se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Completa los campos obligatorios y haz clic en Ejecutar.

    Este es el resultado. Cuando la respuesta contiene "done": true, significa que la operación de larga duración finalizó.

Visualiza los archivos de salida de la ejecución de prueba

Con cada ejecución de prueba, se generan uno o más archivos que contienen los ID y los tipos de los recursos de FHIR que se recuperarán. Los archivos se crean en una subcarpeta de la carpeta rollback_resources del bucket de destino de Cloud Storage. El nombre de la subcarpeta es el ID de LRO que se muestra en la respuesta fhirStores.rollback. Para ver los archivos y asegurarte de que la recuperación funciona como se espera, consulta Visualiza metadatos de objetos.

La cantidad de archivos es proporcional a la cantidad de recursos de FHIR recuperados.

Los nombres de los archivos usan el formato trial-NUMBER-of-TOTAL_NUMBER.txt, en el que NUMBER es el número de archivo y TOTAL_NUMBER es la cantidad total de archivos.

Esquema del archivo de salida de la ejecución de prueba

Los archivos de salida de una recuperación de ejecución de prueba usan el esquema que se muestra en la siguiente tabla:

RESOURCE_TYPE RESOURCE_ID TIMESTAMP
El tipo de recurso de FHIR. El ID del recurso de FHIR. La hora en la que se creó o actualizó el recurso de FHIR en el almacén de FHIR.

Recuperar en producción

Antes de realizar la recuperación en producción, haz una ejecución de prueba y, luego, inspecciona los archivos de salida de la ejecución de prueba para asegurarte de que la recuperación de la producción se ejecute como se espera.

En los siguientes ejemplos, se muestra cómo restablecer los recursos FHIR en producción con el método fhirStores.rollback.

REST

  1. Recupera los recursos de FHIR.

    Asegúrate de que el campo force sea true.

    Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

    • PROJECT_IDEl ID de tu proyecto de Google Cloud.
    • LOCATION: La ubicación del conjunto de datos
    • DATASET_ID es el conjunto de datos superior del almacén de FHIR
    • FHIR_STORE_ID: El ID del almacén de FHIR
    • RECOVERY_TIMESTAMP: Es un punto de recuperación en los últimos 21 días. Usa el formato RFC 3339. Especifica el tiempo hasta el segundo e incluye una zona horaria, por ejemplo, 2015-02-07T13:28:17.239+02:00 o 2017-01-01T00:00:00Z.
    • CLOUD_STORAGE_BUCKET: Es el URI completamente calificado de una carpeta o un bucket de Cloud Storage en el que se escriben los archivos de salida.

    Cuerpo JSON de la solicitud: 

    {
  "rollbackTime": "RECOVERY_TIMESTAMP",
  "resultGcsBucket": "gs://CLOUD_STORAGE_BUCKET",
  "force": "true"
}

    Para enviar tu solicitud, elige una de estas opciones:

    curl

    Guarda el cuerpo de la solicitud en un archivo llamado request.json. Ejecuta el comando siguiente en la terminal para crear o reemplazar este archivo en el directorio actual: 

    cat > request.json << 'EOF'
{
  "rollbackTime": "RECOVERY_TIMESTAMP",
  "resultGcsBucket": "gs://CLOUD_STORAGE_BUCKET",
  "force": "true"
}
EOF

    Luego, ejecuta el siguiente comando para enviar tu solicitud de REST: 

    curl -X POST \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json; charset=utf-8" \
         -d @request.json \
         "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:rollback"

    PowerShell

    Guarda el cuerpo de la solicitud en un archivo llamado request.json. Ejecuta el comando siguiente en la terminal para crear o reemplazar este archivo en el directorio actual: 

    @'
{
  "rollbackTime": "RECOVERY_TIMESTAMP",
  "resultGcsBucket": "gs://CLOUD_STORAGE_BUCKET",
  "force": "true"
}
'@  | Out-File -FilePath request.json -Encoding utf8

    Luego, ejecuta el siguiente comando para enviar tu solicitud de REST: 

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

    Invoke-WebRequest `
        -Method POST `
        -Headers $headers `
        -ContentType: "application/json; charset=utf-8" `
        -InFile request.json `
        -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:rollback" | Select-Object -Expand Content

    Explorador de APIs

    Copia el cuerpo de la solicitud y abre la página de referencia del método. El panel del Explorador de API se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Pega el cuerpo de la solicitud en esta herramienta, completa cualquier otro campo obligatorio y haz clic en Ejecutar.

    Este es el resultado. La respuesta contiene un identificador para una operación de larga duración (LRO). Las operaciones de larga duración se muestran cuando las llamadas de métodos pueden tardar más en completarse. Toma nota del valor de OPERATION_ID. Necesitarás este valor en el paso siguiente.

  2. Usa el método projects.locations.datasets.operations.get para obtener el estado de la operación de larga duración.

    Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

    • PROJECT_IDEl ID de tu proyecto de Google Cloud.
    • DATASET_ID: El ID del conjunto de datos
    • LOCATION: La ubicación del conjunto de datos
    • OPERATION_ID: Es el ID que muestra la operación de larga duración.

    Para enviar tu solicitud, elige una de estas opciones:

    curl

    Ejecuta el siguiente comando: 

    curl -X GET \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"

    PowerShell

    Ejecuta el siguiente comando: 

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

    Invoke-WebRequest `
        -Method GET `
        -Headers $headers `
        -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" | Select-Object -Expand Content

    Explorador de APIs

    Abre la página de referencia del método. El panel del Explorador de API se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Completa los campos obligatorios y haz clic en Ejecutar.

    Este es el resultado. Cuando la respuesta contiene "done": true, significa que la operación de larga duración finalizó.

Visualiza los archivos de salida de recuperación de producción

Una recuperación de producción genera los siguientes archivos. Los archivos se crean en una subcarpeta en la carpeta rollback_resources del bucket de destino de Cloud Storage. El nombre de la subcarpeta es el ID de LRO que se muestra en la respuesta fhirStores.rollback. Para ver los archivos, consulta Visualiza metadatos de objetos.

  • success-NUMBER-of-TOTAL_NUMBER.txt: Contiene recursos de FHIR recuperados correctamente.
  • fail-NUMBER-of-TOTAL_NUMBER.txt: Contiene recursos de FHIR que no se pudieron recuperar. Se genera un archivo vacío incluso si no hay fallas.

En los nombres de los archivos, NUMBER es el número de archivo y TOTAL_NUMBER es la cantidad total de archivos.

Esquema del archivo de salida de producción

Los archivos de éxito y fracaso de una recuperación de producción usan el siguiente esquema. Los archivos de error contienen una columna ERROR_MESSAGE adicional.

RESOURCE_TYPE RESOURCE_ID ROLLBACK_VERSION_ID NEW_VERSION_ID ERROR_MESSAGE (solo archivos con error)
El tipo de recurso de FHIR. El ID del recurso de FHIR. El ID de la versión actual del recurso en el momento en que comenzó la recuperación. ID de la versión actual del recurso después de la recuperación. Si disableResourceVersioning es true, o si la recuperación de un recurso hace que se borre, ROLLBACK_VERSION_ID y NEW_VERSION_ID están vacíos. Solo archivos con errores. Describe por qué se archivó el recurso de FHIR que se recuperará.

Usa filtros para recuperar recursos de FHIR específicos

En las siguientes secciones, se describe cómo usar filtros para recuperar recursos de FHIR según un criterio de filtro. Debes especificar los filtros en el objeto RollbackFhirResourceFilteringFields cuando envías una solicitud fhirStores.rollback.

Puedes combinar filtros o usarlos de manera individual para varios casos de uso, incluidos los siguientes:

  • Recuperar recursos FHIR específicos después de una eliminación accidental y dejar los demás sin cambios
  • Restablecer un almacén de FHIR a un estado antes de que una operación de importación específica haya importado ciertos recursos de FHIR.

Usa un archivo de filtro

De forma predeterminada, la PITR recupera todos los recursos de FHIR de un almacén de FHIR. Para recuperar recursos de FHIR específicos, especifica los tipos de recursos y sus IDs de recurso en un archivo y, luego, sube el archivo a Cloud Storage. Especifica la ubicación del archivo en el campo inputGcsObject.

Para leer un archivo de filtro desde Cloud Storage, debes otorgar permisos a la cuenta de servicio del agente de servicio de Cloud Healthcare. Para obtener más información, consulta Lee archivos de filtros de Cloud Storage.

El archivo de filtro puede tener cualquier extensión. Debe usar el siguiente esquema, con un recurso de FHIR por línea:

FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID

Por ejemplo, para recuperar un recurso Patient con el ID 8f25b0ac y dos recursos de observación con los IDs d507417e90e y e9950d90e, especifica lo siguiente en el archivo de filtro:

Patient/8f25b0ac
Observation/d507417e90e
Observation/e9950d90e

Usa funciones personalizadas

La API de Cloud Healthcare proporciona las siguientes funciones de filtrado personalizado. Puedes combinar las funciones personalizadas con el campo rollbackTime para aplicar un filtro adicional.

tag
Detalles
Sintaxis de la función
tag("system") = "code"
Descripción
Filtra los recursos de FHIR según el elemento Meta.tag del recurso.
Argumentos
system
string
Una URL que hace referencia a un sistema de código. Para obtener más información, consulta Cómo usar códigos en Recursos.
code
string
Es un valor que identifica un concepto según lo define el sistema de código. Para obtener más información, consulta Cómo usar códigos en Recursos.
extension_value_ts
Detalles
Sintaxis de la función
extension_value_ts("url")
Descripción
Filtra los recursos de FHIR según el valor url en un elemento extension en el que url es una marca de tiempo de Unix. Admite los siguientes operadores de comparación:
  • =
  • !=
  • <
  • >
  • <=
  • >=
Argumentos
url
string
Es la URL canónica de un recurso StructureDefinition que define una extensión. Por ejemplo, en el siguiente elemento extension, el url es http://hl7.org/fhir/StructureDefinition/timezone:
"extension" : [{
  "url" : "http://hl7.org/fhir/StructureDefinition/timezone",
  "valueCode" : "America/New_York"
}]
Para obtener más información, consulta Cómo definir extensiones.

Filtrar por tipo de recurso de FHIR

Para filtrar los recursos de FHIR de manera más amplia según el tipo de recurso, especifica los tipos de recursos en el arreglo types[].

Filtrar por tipo de operación

Para filtrar los recursos FHIR que se modificaron mediante una transacción CREATE, UPDATE o DELETE, especifica un valor en la enumeración ChangeType.

Por ejemplo, para recuperar solo los recursos FHIR que se borraron, especifica el valor DELETE.

Si especificas CHANGE_TYPE_UNSPECIFIED, ALL, o no especificas un valor, se recuperan todos los recursos de FHIR.

Excluir recuperaciones anteriores

Para excluir recuperaciones anteriores durante la recuperación de recursos de FHIR, establece el campo excludeRollbacks en true. Puedes excluir recuperaciones anteriores si estas funcionaron de forma correcta y no deseas reemplazar sus cambios. También puedes ejecutar varias recuperaciones con marcas de tiempo superpuestas.

Considera la siguiente situación:

  1. En 1:00, inicias una recuperación con la marca de tiempo de recuperación establecida en 0:01. En 2:00, la operación de recuperación borra los recursos del paciente Patient/1 y Patient/2 en el almacén de FHIR. La operación de recuperación finaliza a las 3:00.

  2. Varios días después, ejecutas una operación de recuperación con la marca de tiempo de recuperación establecida en 1:00. De forma predeterminada, la ejecución de la operación daría como resultado lo siguiente:

    • Se volvieron a crear de forma incorrecta los recursos de paciente Patient/1 y Patient/2.
    • Recuperando correctamente los recursos FHIR creados o actualizados después del 3:00.

Para excluir la operación de recuperación inicial que borró los recursos del paciente Patient/1 y Patient/2 y evitar volver a crearlos, configura excludeRollbacks como true.

Filtra con IDs de operaciones de larga duración (LRO)

Si una o más operaciones de larga duración (LRO) modificaron los recursos de FHIR, puedes especificar los IDs de LRO en el campo operationIds para recuperar los recursos modificados.

Consulta Crea una lista de LRO para obtener información sobre cómo enumerar y ver los ID de LRO en un conjunto de datos de la API de Cloud Healthcare.

Reintentar los recursos de FHIR que no se pudieron recuperar en producción

Si algunos recursos de FHIR no lograron una recuperación de producción, puedes reintentar la recuperación. Usa el archivo de salida de producción generado para encontrar los recursos de FHIR que fallaron. Especifica los tipos de estos recursos de FHIR y sus IDs en un archivo de filtro y vuelve a ejecutar la recuperación.

Cada vez que ejecutes una recuperación, esta será idempotente si usas la misma configuración en cada solicitud y la marca de tiempo se encuentra dentro de los últimos 21 días.

Limitaciones

  • La PITR no aplica la integridad referencial, sin importar la configuración de disableReferentialIntegrity en el almacén de FHIR. Restablecer solo algunos recursos de FHIR puede salir del almacén de FHIR en un estado que infringe la integridad referencial.

  • PITR omite la validación del perfil de FHIR porque los recursos de FHIR restablecidos se validaron cuando se crearon o actualizaron. Si la configuración del perfil de almacén de FHIR cambia, la PITR puede dejar el almacén de FHIR en un estado que infrinja la validación del perfil.

  • Si el valor de rollbackTime precede al momento en que se borró un recurso de FHIR del almacén de FHIR, el almacén de FHIR debe tener enableUpdateCreate habilitado; de lo contrario, el recurso no se recuperará.

  • Puedes actualizar un almacén de FHIR o leer y escribir datos durante una recuperación, pero es posible que veas resultados inesperados según la etapa de recuperación. Por ejemplo, una solicitud de lectura puede mostrar una combinación de recursos de FHIR recuperados y no recuperados. Si actualizas un recurso, la recuperación puede reemplazar la actualización.

  • La PITR mantiene el historial de recursos de FHIR. Cada recurso restablecido obtiene una versión actual nueva y se conserva su historial.