Recuperar recursos FHIR con la recuperación a un momento dado (PITR)

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

Antes de empezar

Las solicitudes de PITR se clasifican como solicitudes de operaciones avanzadas y se facturan en consecuencia. Antes de usar PITR, consulta los precios de las solicitudes de operaciones avanzadas.

PITR e historial de versiones de recursos FHIR

PITR no depende del historial de versiones de recursos FHIR. Puedes seguir usando PITR si el campo disableResourceVersioning de un almacén FHIR es true o si se han eliminado las versiones históricas de un recurso FHIR.

Flujo de trabajo de recuperación

Para asegurarte de que la recuperación de producción se realiza correctamente, primero haz una prueba de funcionamiento. La prueba genera uno o varios archivos que contienen los IDs y los tipos de los recursos de FHIR que se van a recuperar. Verifica que los archivos de salida sean correctos antes de volver a ejecutar la recuperación en producción.

Para recuperar recursos específicos o recursos según un criterio de filtrado, especifica un filtro.

Hacer una prueba

Antes de recuperar recursos FHIR en producción, haz una prueba de funcionamiento.

En los siguientes ejemplos se muestra cómo hacer una prueba sin ejecutar con el método fhirStores.rollback.

REST

  1. Recupera los recursos FHIR.

    Para hacer una prueba de funcionamiento, asegúrate de que el campo force esté false.

    Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

    • PROJECT_ID: el ID de tu Google Cloud proyecto
    • LOCATION: la ubicación del conjunto de datos
    • DATASET_ID: el conjunto de datos superior del almacén FHIR
    • FHIR_STORE_ID: el ID del almacén FHIR
    • RECOVERY_TIMESTAMP: un punto de recuperación de los últimos 21 días. Usa el formato RFC 3339. Especifica la hora 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: el URI completo de una carpeta o un segmento 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 siguiente comando en el terminal para crear o sobrescribir este archivo en el directorio actual: 

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

    A continuación, ejecuta el siguiente comando para enviar tu solicitud 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 siguiente comando en el terminal para crear o sobrescribir este archivo en el directorio actual: 

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

    A continuación, ejecuta el siguiente comando para enviar tu solicitud 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 Explorador de APIs 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, rellena los campos obligatorios y haz clic en Ejecutar.

    El resultado es el siguiente. La respuesta contiene un identificador de una operación de larga duración. Las operaciones de larga duración se devuelven cuando las llamadas a métodos pueden tardar más tiempo en completarse. Anota el valor de OPERATION_ID. Necesitarás este valor en el siguiente paso.

  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 los datos de la solicitud, haz las siguientes sustituciones:

    • PROJECT_ID: el ID de tu Google Cloud proyecto
    • DATASET_ID: el ID del conjunto de datos
    • LOCATION: la ubicación del conjunto de datos
    • OPERATION_ID: el ID devuelto por la operación de larga duración

    Para enviar tu solicitud, elige una de estas opciones:

    curl

    Ejecuta el comando siguiente: 

    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 comando siguiente: 

    $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 Explorador de APIs se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Rellena los campos obligatorios y haz clic en Ejecutar.

    El resultado es el siguiente. Cuando la respuesta contiene "done": true, la operación de larga duración ha finalizado.

Ver los archivos de salida de la prueba

Cada prueba genera uno o varios archivos que contienen los IDs y los tipos de los recursos de FHIR que se van a recuperar. Los archivos se crean en una subcarpeta de la carpeta rollback_resources del segmento de Cloud Storage de destino. El nombre de la subcarpeta es el ID de la operación de larga duración que se devuelve en la respuesta de fhirStores.rollback. Para ver los archivos y asegurarte de que la recuperación funciona como se espera, consulta Ver metadatos de objetos.

El número de archivos es proporcional al número de recursos FHIR recuperados.

Los nombres de los archivos siguen el formato trial-NUMBER-of-TOTAL_NUMBER.txt, donde NUMBER es el número del archivo y TOTAL_NUMBER es el número total de archivos.

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

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

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

Recuperación en producción

Antes de realizar la recuperación en producción, haz una prueba de funcionamiento e inspecciona los archivos de salida de la prueba para asegurarte de que la recuperación en producción se ejecuta correctamente.

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

REST

  1. Recupera los recursos FHIR.

    Asegúrate de que el campo force sea true.

    Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

    • PROJECT_ID: el ID de tu Google Cloud proyecto
    • LOCATION: la ubicación del conjunto de datos
    • DATASET_ID: el conjunto de datos superior del almacén FHIR
    • FHIR_STORE_ID: el ID del almacén FHIR
    • RECOVERY_TIMESTAMP: un punto de recuperación de los últimos 21 días. Usa el formato RFC 3339. Especifica la hora 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: el URI completo de una carpeta o un segmento 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 siguiente comando en el terminal para crear o sobrescribir este archivo en el directorio actual: 

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

    A continuación, ejecuta el siguiente comando para enviar tu solicitud 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 siguiente comando en el terminal para crear o sobrescribir este archivo en el directorio actual: 

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

    A continuación, ejecuta el siguiente comando para enviar tu solicitud 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 Explorador de APIs 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, rellena los campos obligatorios y haz clic en Ejecutar.

    El resultado es el siguiente. La respuesta contiene un identificador de una operación de larga duración. Las operaciones de larga duración se devuelven cuando las llamadas a métodos pueden tardar más tiempo en completarse. Anota el valor de OPERATION_ID. Necesitarás este valor en el siguiente paso.

  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 los datos de la solicitud, haz las siguientes sustituciones:

    • PROJECT_ID: el ID de tu Google Cloud proyecto
    • DATASET_ID: el ID del conjunto de datos
    • LOCATION: la ubicación del conjunto de datos
    • OPERATION_ID: el ID devuelto por la operación de larga duración

    Para enviar tu solicitud, elige una de estas opciones:

    curl

    Ejecuta el comando siguiente: 

    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 comando siguiente: 

    $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 Explorador de APIs se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Rellena los campos obligatorios y haz clic en Ejecutar.

    El resultado es el siguiente. Cuando la respuesta contiene "done": true, la operación de larga duración ha finalizado.

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

La recuperación de una producción genera los siguientes archivos. Los archivos se crean en una subcarpeta de la carpeta rollback_resources del segmento de Cloud Storage de destino. El nombre de la subcarpeta es el ID de la operación de larga duración que se devuelve en la respuesta de fhirStores.rollback. Para ver los archivos, consulta Ver metadatos de objetos.

  • success-NUMBER-of-TOTAL_NUMBER.txt: contiene los recursos FHIR recuperados correctamente.
  • fail-NUMBER-of-TOTAL_NUMBER.txt: contiene recursos FHIR que no se han podido recuperar. Se genera un archivo vacío aunque no haya fallos.

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

Esquema del archivo de salida de producción

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

RESOURCE_TYPE RESOURCE_ID ROLLBACK_VERSION_ID NEW_VERSION_ID ERROR_MESSAGE (solo archivos de error)
El tipo de recurso FHIR. El ID del recurso FHIR. El ID de la versión actual del recurso en el momento en que se inició la recuperación. El ID de la versión actual del recurso después de la recuperación. Si disableResourceVersioning es true o si al recuperar un recurso se eliminaría, ROLLBACK_VERSION_ID y NEW_VERSION_ID estarán vacíos. Solo archivos de error. Describe por qué no se ha podido recuperar el recurso FHIR.

Usar filtros para recuperar recursos FHIR específicos

En las siguientes secciones se describe cómo usar filtros para recuperar recursos FHIR en función de un criterio de filtro. Los filtros se especifican en el objeto RollbackFhirResourceFilteringFields al enviar una solicitud fhirStores.rollback.

Puedes combinar filtros o usarlos por separado en varios casos prácticos, como los siguientes:

  • Recuperar recursos FHIR específicos después de una eliminación accidental sin modificar el resto.
  • Restaurar un almacén FHIR a un estado anterior a una operación de importación específica en la que se importaron determinados recursos FHIR.

Usar un archivo de filtro

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

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

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

FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID

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

Patient/8f25b0ac
Observation/d507417e90e
Observation/e9950d90e

Usar funciones personalizadas

La API Cloud Healthcare proporciona las siguientes funciones de filtrado personalizadas. 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 FHIR en función del elemento Meta.tag del recurso.
Argumentos
system
string
URL que hace referencia a un sistema de códigos. Para obtener más información, consulta Usar códigos en recursos.
code
string
Valor que identifica un concepto tal como lo define el sistema de códigos. Para obtener más información, consulta Usar códigos en recursos.
extension_value_ts
Detalles
Sintaxis de la función
extension_value_ts("url")
Descripción
Filtra los recursos FHIR en función del valor url de un elemento extension, donde url es una marca de tiempo de Unix. Admite los siguientes operadores de comparación:
  • =
  • !=
  • <
  • >
  • <=
  • >=
Argumentos
url
string
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 Definir extensiones.

Filtrar por tipo de recurso FHIR

Para filtrar recursos FHIR de forma más generalizada basándose únicamente en el tipo de recurso, especifica los tipos de recursos en la matriz types[].

Filtrar por tipo de operación

Para filtrar los recursos FHIR que se han modificado 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 hayan eliminado, especifica el valor DELETE.

Si especificas CHANGE_TYPE_UNSPECIFIED, ALL, o no especificas ningún valor, se recuperarán todos los recursos FHIR.

Excluir recuperaciones anteriores

Para excluir las recuperaciones anteriores al recuperar recursos FHIR, asigna el valor true al campo excludeRollbacks. Puedes excluir las recuperaciones anteriores si han funcionado correctamente y no quieres sobrescribir sus cambios. También puedes ejecutar varias recuperaciones con marcas de tiempo superpuestas.

Veamos la siguiente situación:

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

  2. Varios días después, ejecutas una operación de recuperación con la marca de tiempo de recuperación definida en 1:00. De forma predeterminada, al ejecutar la operación se obtendría lo siguiente:

    • Recrear incorrectamente los recursos de paciente Patient/1 y Patient/2.
    • Recuperar correctamente los recursos FHIR creados o actualizados después del 3:00.

Para excluir la operación de recuperación inicial que eliminó los recursos de paciente Patient/1 y Patient/2, y evitar que se vuelvan a crear, asigna el valor true a excludeRollbacks.

Filtrar por IDs de operaciones de larga duración

Si uno o varios operaciones de larga duración (OLDs) han modificado los recursos FHIR, puede especificar los IDs de las OLDs en el campo operationIds para recuperar los recursos modificados.

Consulta Listar operaciones LRO para obtener información sobre cómo listar y ver los IDs de las operaciones LRO en un conjunto de datos de la API Cloud Healthcare.

Reintentar recuperar recursos FHIR que no se han podido recuperar en producción

Si no se ha podido recuperar algún recurso FHIR de producción, puede volver a intentarlo. Usa el archivo de salida de producción generado para encontrar los recursos FHIR que han fallado. Especifique los tipos de estos recursos FHIR y sus IDs en un archivo de filtro y vuelva a ejecutar la recuperación.

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

Limitaciones

  • La restauración a un momento dado no aplica la integridad referencial, independientemente del ajuste disableReferentialIntegrity del almacén FHIR. Si solo restauras algunos recursos FHIR, es posible que el almacén FHIR quede en un estado que infrinja la integridad referencial.

  • La restauración a un momento dado omite la validación del perfil FHIR porque los recursos FHIR restaurados se validaron cuando se crearon o actualizaron. Si la configuración del perfil del almacén FHIR ha cambiado, es posible que PITR deje el almacén FHIR en un estado que no cumpla la validación del perfil.

  • Si el valor de rollbackTime es anterior al momento en el que se eliminó un recurso FHIR del almacén FHIR, el almacén FHIR debe tener habilitada la opción enableUpdateCreate para que se pueda recuperar el recurso.

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

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