Esta página descreve como usar a recuperação pontual (PITR, na sigla em inglês) para recuperar recursos do 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ção avançada e são faturadas de acordo. Antes de usar a PITR, revise os preços das solicitações de operação avançada.
Histórico de versões de recursos FHIR e PITR
A PITR não depende do histórico de versões de recursos FHIR.
Ainda é possível 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 limpas.
Fluxo de trabalho de recuperação
Para garantir que a recuperação de produção seja executada conforme o esperado, faça primeiro uma simulação. O teste simulado 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 na produção.
Para recuperar recursos específicos ou de acordo com um critério de filtragem, especifique um filtro.
Fazer uma simulação
Antes de recuperar recursos FHIR em produção, faça um teste.
Os exemplos a seguir mostram como fazer um teste
usando o método
fhirStores.rollback
.
REST
Recuperar os recursos FHIR.
Para fazer uma simulação, verifique se o campo
force
estáfalse
.Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
PROJECT_ID
: o ID do seu projeto do Google Cloud;LOCATION
: o local do conjunto de dados;DATASET_ID
: o conjunto de dados pai do armazenamento de FHIRFHIR_STORE_ID
: o ID de armazenamento de FHIRRECOVERY_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
ou2017-01-01T00:00:00Z
.CLOUD_STORAGE_BUCKET
: o URI totalmente qualificado para 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 ContentAPIs 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.
OPERATION_ID
. Você vai precisar desse valor na próxima etapa.Use o método
projects.locations.datasets.operations.get
para conferir 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 projeto do Google Cloud;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 ContentAPIs 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.
"done": true
, a operação de longa duração foi concluída.
Conferir arquivos de saída de simulação
Cada simulação de teste gera um ou mais arquivos com os IDs e tipos dos recursos do FHIR
a serem recuperados. 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 do 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 de teste 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. |
Recuperação na produção
Antes de recuperar na produção, faça um ensaio e inspecione os arquivos de saída do ensaio para garantir que a recuperação de 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
Recuperar 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 projeto do Google Cloud;LOCATION
: o local do conjunto de dados;DATASET_ID
: o conjunto de dados pai do armazenamento de FHIRFHIR_STORE_ID
: o ID de armazenamento de FHIRRECOVERY_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
ou2017-01-01T00:00:00Z
.CLOUD_STORAGE_BUCKET
: o URI totalmente qualificado para 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 ContentAPIs 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.
OPERATION_ID
. Você vai precisar desse valor na próxima etapa.Use o método
projects.locations.datasets.operations.get
para conferir 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 projeto do Google Cloud;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 ContentAPIs 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.
"done": true
, a operação de longa duração foi concluída.
Conferir os arquivos de saída da 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 do LRO retornado na
resposta fhirStores.rollback
. Para conferir 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 foram recuperados. Um arquivo vazio é gerado mesmo que não haja falhas.
Nos nomes de arquivo, 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 esquema
abaixo. 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 começou. | 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 excluir o recurso, ROLLBACK_VERSION_ID e NEW_VERSION_ID vão estar vazios. |
Somente arquivos de erro. Descreve por que o recurso do FHIR foi arquivado para recuperação. |
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 filtros ou usá-los individualmente para vários casos de uso, incluindo os seguintes:
- Recuperar recursos FHIR específicos após a exclusão acidental, sem alterar os outros.
- Restaurar um armazenamento FHIR para um estado antes de uma operação de importação específica importar determinados recursos do 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 de recurso e os IDs deles em um arquivo e faça o upload para o Cloud Storage. Especifique o local do arquivo no campo
inputGcsObject
.
Para ler um arquivo de filtro do Cloud Storage, é necessário conceder 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 esquema abaixo, com um recurso FHIR por linha:
FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID
Por exemplo, para recuperar um recurso de paciente com o ID 8f25b0ac
e dois
recursos de observação 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 outro filtro.
tag
Detalhes Sintaxe da função tag("system") = "code"
Descrição Filtra os recursos FHIR com base no elementoMeta.tag
do recurso.Argumentos system
string
Um URL que faz referência a um sistema de código. 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ódigo. 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 os recursos FHIR com base no valorurl
em um elementoextension
, em queurl
é um carimbo de data/hora Unix. Oferece suporte aos seguintes operadores de comparação:=
!=
<
>
<=
>=
Argumentos url
string
O URL canônico de um recurso StructureDefinition que define uma extensão. Por exemplo, no elementoextension
a seguir, ourl
é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 os recursos do FHIR
de maneira mais ampla com base apenas no tipo de recurso, especifique os tipos de recurso na
matriz types[]
.
Filtrar por tipo de operação
Para filtrar recursos FHIR que foram modificados por uma transação CREATE
, UPDATE
ou
DELETE
,
especifique um valor no tipo enumerado
ChangeType
.
Por exemplo,
para recuperar apenas os recursos FHIR excluídos, especifique o valor
DELETE
.
Se você especificar CHANGE_TYPE_UNSPECIFIED
,
ALL
ou não especificar um valor, todos os recursos do 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
funcionarem corretamente e você não quiser substituir as mudanças.
Também é possível executar várias recuperações com carimbos de data/hora sobrepostos.
Pense no seguinte cenário:
- Em
1:00
, você inicia uma recuperação com o carimbo de data/hora definido como0:01
. Em2:00
, a operação de recuperação exclui os recursos de pacientePatient/1
ePatient/2
no armazenamento de FHIR. A operação de recuperação termina em3:00
. Vários dias depois, você executa uma operação de recuperação com o carimbo de data/hora de recuperação definido como
1:00
. Por padrão, a execução da operação resultaria no seguinte:- Recriando incorretamente os recursos de pacientes
Patient/1
ePatient/2
. - Recuperação correta dos recursos FHIR criados ou atualizados após
3:00
.
- Recriando incorretamente os recursos de pacientes
Para excluir a operação de recuperação inicial que excluiu
os recursos de paciente Patient/1
e Patient/2
e evitar a recriação deles,
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),
especifique os IDs de LRO no campo operationIds
para recuperar os recursos modificados.
Consulte Como listar LROs para informações sobre como listar e visualizar IDs de LRO em um conjunto de dados da API Cloud Healthcare.
Tentar novamente recursos do FHIR que não foram recuperados na produção
Se alguns recursos do FHIR falharem em uma recuperação de produção, tente novamente. 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ê usar a mesma configuração em cada solicitação e o carimbo de data/hora estiver nos últimos 21 dias.
Limitações
O 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.O PITR pula 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, o PITR poderá deixar o repositório FHIR em um estado que viola a validação do perfil.
Se o valor de
rollbackTime
for anterior ao momento em que um recurso FHIR foi excluído no armazenamento FHIR, o armazenamento precisa terenableUpdateCreate
ativado ou 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 do estágio da recuperação. Por exemplo, uma solicitação de leitura pode retornar uma combinação de recursos 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.