Recuperar recursos FHIR com recuperação pontual (PITR)

Nesta página, descrevemos como usar a recuperação pontual (PITR, na sigla em inglês) para recuperar recursos FHIR em um armazenamento FHIR para um estado nos últimos 21 dias. É possível usar a PITR para se recuperar de mudanças indesejadas, como a exclusão acidental de recursos do FHIR.

Antes de começar

As solicitações de PITR são categorizadas como solicitações de operações avançadas e são faturadas de acordo. Antes de usar a PITR, revise os preços dos pedidos de operação avançada.

PITR e histórico de versões de recursos FHIR

A PITR não depende do histórico de versões de recursos FHIR. Você ainda pode usar a PITR se o campo disableResourceVersioning em um armazenamento FHIR for true ou se as versões históricas de um recurso FHIR tiverem sido removidas.

Fluxo de trabalho de recuperação

Para garantir que uma recuperação de produção seja executada conforme o esperado, primeiro faça uma simulação. A simulação gera um ou mais arquivos com os IDs e tipos dos recursos do FHIR a serem recuperados. Verifique a correção dos arquivos de saída antes de executar a recuperação novamente em produção.

Para recuperar recursos específicos ou de acordo com um critério de filtragem, especifique um filtro.

Fazer um teste

Antes de recuperar recursos FHIR em produção, faça uma simulação.

Os exemplos a seguir mostram como fazer um teste a seco usando o método fhirStores.rollback.

REST

  1. Recupere os recursos FHIR.

    Para fazer uma simulação, verifique se o campo force é false.

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • PROJECT_ID: o ID do seu Google Cloud projeto
    • LOCATION: o local do conjunto de dados;
    • DATASET_ID: o conjunto de dados pai do armazenamento de FHIR
    • FHIR_STORE_ID: o ID de armazenamento de FHIR
    • RECOVERY_TIMESTAMP: um ponto de recuperação nos últimos 21 dias. Use o formato RFC 3339. Especifique a hora até o segundo e inclua um fuso horário, por exemplo, 2015-02-07T13:28:17.239+02:00 ou 2017-01-01T00:00:00Z.
    • CLOUD_STORAGE_BUCKET: o URI totalmente qualificado de uma pasta ou bucket do Cloud Storage em que os arquivos de saída são gravados

    Corpo JSON da solicitação:

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

    Para enviar a solicitação, escolha uma destas opções:

    curl

    Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual: 

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

    Depois execute o comando a seguir para enviar a solicitação 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

    Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual: 

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

    Depois execute o comando a seguir para enviar a solicitação 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

    APIs Explorer

    Copie o corpo da solicitação e abra a página de referência do método. O painel "APIs Explorer" é aberto no lado direito da página. Interaja com essa ferramenta para enviar solicitações. Cole o corpo da solicitação nessa ferramenta, preencha todos os outros campos obrigatórios e clique em Executar.

    A saída é esta: A resposta contém um identificador para uma operação de longa duração (LRO, na sigla em inglês). Operações de longa duração são retornadas quando as chamadas de método podem levar mais tempo para serem concluídas. Anote o valor de OPERATION_ID. Você vai precisar desse valor na próxima etapa.

  2. Use o método projects.locations.datasets.operations.get para receber o status da operação de longa duração.

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • PROJECT_ID: o ID do seu Google Cloud projeto
    • DATASET_ID: o ID do conjunto de dados;
    • LOCATION: o local do conjunto de dados;
    • OPERATION_ID: o ID retornado da operação de longa duração.

    Para enviar a solicitação, escolha uma destas opções:

    curl

    execute o seguinte 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

    Execute o seguinte 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

    APIs Explorer

    Abra a página de referência do método. O painel "APIs Explorer" é aberto no lado direito da página. Interaja com essa ferramenta para enviar solicitações. Preencha todos os campos obrigatórios e clique em Executar.

    A saída é esta: Quando a resposta contém "done": true, a operação de longa duração é concluída.

Ver arquivos de saída de simulação

Cada simulação gera um ou mais arquivos com os IDs e tipos dos recursos FHIR a serem recuperados. Os arquivos são criados em uma subpasta na pasta rollback_resources do bucket de destino do Cloud Storage. O nome da subpasta é o ID da LRO retornado na resposta fhirStores.rollback. Para conferir os arquivos e garantir que a recuperação funcione como esperado, consulte Visualizar metadados do objeto.

O número de arquivos é proporcional ao número de recursos FHIR recuperados.

Os nomes de arquivo usam o formato trial-NUMBER-of-TOTAL_NUMBER.txt, em que NUMBER é o número do arquivo e TOTAL_NUMBER é o número total de arquivos.

Esquema do arquivo de saída da simulação

Os arquivos de saída de uma recuperação de simulação usam o esquema mostrado na tabela a seguir:

RESOURCE_TYPE RESOURCE_ID TIMESTAMP
O tipo de recurso FHIR. O ID do recurso FHIR. O momento em que o recurso FHIR foi criado ou atualizado no armazenamento FHIR.

Recuperar na produção

Antes de fazer a recuperação na produção, faça um teste e inspecione os arquivos de saída do teste para garantir que a recuperação na produção seja executada conforme o esperado.

Os exemplos a seguir mostram como restaurar recursos FHIR em produção usando o método fhirStores.rollback.

REST

  1. Recupere os recursos FHIR.

    Verifique se o campo force é true.

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • PROJECT_ID: o ID do seu Google Cloud projeto
    • LOCATION: o local do conjunto de dados;
    • DATASET_ID: o conjunto de dados pai do armazenamento de FHIR
    • FHIR_STORE_ID: o ID de armazenamento de FHIR
    • RECOVERY_TIMESTAMP: um ponto de recuperação nos últimos 21 dias. Use o formato RFC 3339. Especifique a hora até o segundo e inclua um fuso horário, por exemplo, 2015-02-07T13:28:17.239+02:00 ou 2017-01-01T00:00:00Z.
    • CLOUD_STORAGE_BUCKET: o URI totalmente qualificado de uma pasta ou bucket do Cloud Storage em que os arquivos de saída são gravados

    Corpo JSON da solicitação:

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

    Para enviar a solicitação, escolha uma destas opções:

    curl

    Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual: 

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

    Depois execute o comando a seguir para enviar a solicitação 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

    Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual: 

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

    Depois execute o comando a seguir para enviar a solicitação 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

    APIs Explorer

    Copie o corpo da solicitação e abra a página de referência do método. O painel "APIs Explorer" é aberto no lado direito da página. Interaja com essa ferramenta para enviar solicitações. Cole o corpo da solicitação nessa ferramenta, preencha todos os outros campos obrigatórios e clique em Executar.

    A saída é esta: A resposta contém um identificador para uma operação de longa duração (LRO, na sigla em inglês). Operações de longa duração são retornadas quando as chamadas de método podem levar mais tempo para serem concluídas. Anote o valor de OPERATION_ID. Você vai precisar desse valor na próxima etapa.

  2. Use o método projects.locations.datasets.operations.get para receber o status da operação de longa duração.

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • PROJECT_ID: o ID do seu Google Cloud projeto
    • DATASET_ID: o ID do conjunto de dados;
    • LOCATION: o local do conjunto de dados;
    • OPERATION_ID: o ID retornado da operação de longa duração.

    Para enviar a solicitação, escolha uma destas opções:

    curl

    execute o seguinte 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

    Execute o seguinte 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

    APIs Explorer

    Abra a página de referência do método. O painel "APIs Explorer" é aberto no lado direito da página. Interaja com essa ferramenta para enviar solicitações. Preencha todos os campos obrigatórios e clique em Executar.

    A saída é esta: Quando a resposta contém "done": true, a operação de longa duração é concluída.

Ver arquivos de saída de recuperação de produção

Uma recuperação de produção gera os seguintes arquivos: Os arquivos são criados em uma subpasta na pasta rollback_resources no bucket de destino do Cloud Storage. O nome da subpasta é o ID da LRO retornado na resposta fhirStores.rollback. Para ver os arquivos, consulte Visualizar metadados do objeto.

  • success-NUMBER-of-TOTAL_NUMBER.txt: contém recursos FHIR recuperados com sucesso.
  • fail-NUMBER-of-TOTAL_NUMBER.txt: contém recursos FHIR que não puderam ser recuperados. Um arquivo vazio é gerado mesmo que não haja falhas.

Nos nomes de arquivos, NUMBER é o número do arquivo e TOTAL_NUMBER é o número total de arquivos.

Esquema do arquivo de saída de Production

Os arquivos de sucesso e falha de uma recuperação de produção usam o seguinte esquema. Os arquivos de erro contêm uma coluna ERROR_MESSAGE adicional.

RESOURCE_TYPE RESOURCE_ID ROLLBACK_VERSION_ID NEW_VERSION_ID ERROR_MESSAGE (somente arquivos de erro)
O tipo de recurso FHIR. O ID do recurso FHIR. O ID da versão atual do recurso no momento em que a recuperação foi iniciada. O ID da versão atual do recurso após a recuperação. Se o disableResourceVersioning for true ou se a recuperação de um recurso o excluir, ROLLBACK_VERSION_ID e NEW_VERSION_ID vão estar vazios. Apenas arquivos de erro. Descreve por que o recurso FHIR não foi recuperado.

Usar filtros para recuperar recursos específicos do FHIR

As seções a seguir descrevem como usar filtros para recuperar recursos FHIR com base em um critério de filtro. Especifique os filtros no objeto RollbackFhirResourceFilteringFields ao enviar uma solicitação fhirStores.rollback.

É possível combinar ou usar filtros individualmente para vários casos de uso, incluindo os seguintes:

  • Recuperar recursos específicos do FHIR após exclusão acidental, deixando outros inalterados.
  • Restaurar um armazenamento de FHIR para um estado anterior a uma operação de importação específica que importou determinados recursos de FHIR.

Usar um arquivo de filtro

Por padrão, a PITR recupera todos os recursos FHIR em um armazenamento FHIR. Para recuperar recursos específicos do FHIR, especifique os tipos e IDs em um arquivo e faça upload dele para o Cloud Storage. Especifique o local do arquivo no campo inputGcsObject.

Para ler um arquivo de filtro do Cloud Storage, conceda permissões à conta de serviço do Agente de serviço do Cloud Healthcare. Para mais informações, consulte Ler arquivos de filtro do Cloud Storage.

O arquivo de filtro pode ter qualquer extensão. Ele precisa usar o seguinte esquema, com um recurso FHIR por linha:

FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID

Por exemplo, para recuperar um recurso Patient com o ID 8f25b0ac e dois recursos Observation com os IDs d507417e90e e e9950d90e, especifique o seguinte no arquivo de filtro:

Patient/8f25b0ac
Observation/d507417e90e
Observation/e9950d90e

Usar funções personalizadas

A API Cloud Healthcare oferece as seguintes funções de filtragem personalizada. É possível combinar as funções personalizadas com o campo rollbackTime para aplicar um filtro adicional.

tag
Detalhes
Sintaxe da função
tag("system") = "code"
Descrição
Filtra recursos FHIR com base no elemento Meta.tag do recurso.
Argumentos
system
string
Um URL que faz referência a um sistema de códigos. Para mais informações, consulte Como usar códigos em recursos.
code
string
Um valor que identifica um conceito conforme definido pelo sistema de códigos. Para mais informações, consulte Como usar códigos em recursos.
extension_value_ts
Detalhes
Sintaxe da função
extension_value_ts("url")
Descrição
Filtra recursos FHIR com base no valor url em um elemento extension em que url é um carimbo de data/hora Unix. Aceita os seguintes operadores de comparação:
  • =
  • !=
  • <
  • >
  • <=
  • >=
Argumentos
url
string
O URL canônico de um recurso StructureDefinition que define uma extensão. Por exemplo, no elemento extension a seguir, o url é http://hl7.org/fhir/StructureDefinition/timezone: 
"extension" : [{
  "url" : "http://hl7.org/fhir/StructureDefinition/timezone",
  "valueCode" : "America/New_York"
}]
Para mais informações, consulte Como definir extensões.

Filtrar por tipo de recurso FHIR

Para filtrar recursos do FHIR de maneira mais ampla com base apenas no tipo de recurso, especifique os tipos de recursos na matriz types[].

Filtrar por tipo de operação

Para filtrar recursos FHIR modificados por uma transação CREATE, UPDATE ou DELETE, especifique um valor na enumeração ChangeType.

Por exemplo, para recuperar apenas recursos FHIR que foram excluídos, especifique o valor DELETE.

Se você especificar CHANGE_TYPE_UNSPECIFIED, ALL ou não especificar um valor, todos os recursos FHIR serão recuperados.

Excluir recuperações anteriores

Para excluir recuperações anteriores ao recuperar recursos FHIR, defina o campo excludeRollbacks como true. É possível excluir recuperações anteriores se elas funcionaram corretamente e você não quer substituir as mudanças. Também é possível executar várias recuperações com carimbos de data/hora sobrepostos.

Pense no seguinte cenário:

  1. Em 1:00, você inicia uma recuperação com o carimbo de data/hora definido como 0:01. Em 2:00, a operação de recuperação exclui os recursos de paciente Patient/1 e Patient/2 no armazenamento de FHIR. A operação de recuperação termina em 3:00.

  2. Vários dias depois, você executa uma operação de recuperação com o carimbo de data/hora definido como 1:00. Por padrão, a execução da operação resultaria no seguinte:

    • Recriar incorretamente os recursos de paciente Patient/1 e Patient/2.
    • Recuperar corretamente os recursos FHIR criados ou atualizados após 3:00.

Para excluir a operação de recuperação inicial que excluiu os recursos de paciente Patient/1 e Patient/2 e evitar recriá-los, defina excludeRollbacks como true.

Filtrar usando IDs de operação de longa duração (LRO)

Se os recursos do FHIR foram modificados por uma ou mais operações de longa duração (LROs), é possível especificar os IDs das LROs no campo operationIds para recuperar os recursos modificados.

Consulte Listar LROs para informações sobre como listar e visualizar IDs de LROs em um conjunto de dados da API Cloud Healthcare.

Tentar novamente recursos FHIR que não foram recuperados na produção

Se alguns recursos do FHIR não forem recuperados na produção, tente de novo. Use o arquivo de saída de produção gerado para encontrar os recursos FHIR com falha. Especifique os tipos desses recursos FHIR e os IDs deles em um arquivo de filtro e execute a recuperação novamente.

Cada vez que você executa uma recuperação, ela é idempotente se você usa a mesma configuração em cada solicitação e o carimbo de data/hora está nos últimos 21 dias.

Limitações

  • A PITR não impõe integridade referencial, independentemente da configuração disableReferentialIntegrity no armazenamento FHIR. Restaurar apenas alguns recursos FHIR pode deixar o armazenamento FHIR em um estado que viola a integridade referencial.

  • A PITR ignora a validação do perfil FHIR porque os recursos FHIR restaurados foram validados quando foram criados ou atualizados. Se a configuração do perfil do repositório FHIR mudar, a PiTR poderá deixar o repositório em um estado que viola a validação do perfil.

  • Se o valor de rollbackTime preceder o momento em que um recurso FHIR foi excluído no armazenamento FHIR, o armazenamento FHIR precisará ter enableUpdateCreate ativado. Caso contrário, o recurso não será recuperado.

  • É possível atualizar um armazenamento FHIR ou ler e gravar dados durante uma recuperação, mas talvez você veja resultados inesperados dependendo da etapa de recuperação. Por exemplo, uma solicitação de leitura pode retornar uma combinação de recursos do FHIR recuperados e não recuperados. Se você atualizar um recurso, a recuperação poderá substituir a atualização.

  • A PITR mantém o histórico de recursos FHIR. Cada recurso restaurado recebe uma nova versão atual, e o histórico é mantido.