Recupere recursos FHIR com a recuperação pontual (PITR)

Esta página descreve como usar a recuperação num ponto específico no tempo (PITR) para recuperar recursos FHIR numa loja FHIR para um estado nos últimos 21 dias. Pode usar a PITR para recuperar de alterações indesejadas, como a eliminação acidental de recursos FHIR.

Antes de começar

Os pedidos PITR são categorizados como pedidos de operação avançados e são faturados em conformidade. Antes de usar a PITR, reveja os preços dos pedidos de operações avançadas.

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

A PITR não depende do histórico de versões de recursos FHIR. Pode continuar a usar o PITR se o campo disableResourceVersioning numa loja FHIR for true ou se as versões históricas de um recurso FHIR tiverem sido eliminadas.

Fluxo de trabalho de recuperação

Para garantir que uma recuperação de produção é executada conforme esperado, faça primeiro um teste. A execução de teste produz um ou mais ficheiros que contêm os IDs e os tipos dos recursos FHIR a recuperar. Valide a correção dos ficheiros de saída antes de executar novamente a recuperação em produção.

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

Faça uma execução de ensaio

Antes de recuperar recursos FHIR em produção, faça um teste.

Os exemplos seguintes mostram como fazer um teste de execução usando o método fhirStores.rollback.

Consola

Para reverter uma FHIR store para um estado anterior, siga estes passos:

  1. Na Google Cloud consola, aceda à página Conjuntos de dados.

    Aceda a Conjuntos de dados

  2. Selecione o conjunto de dados que contém o FHIR store ao qual quer reverter.
  3. Na lista Armazenamentos de dados, clique no menu pendente Ações do armazenamento de dados que quer reverter. No menu, clique em Reverter.
  4. No primeiro passo, pode parametrizar a reversão por âmbitos mais amplos, como um ponto no tempo para reverter a FHIR store e reverter todas as operações de um determinado tipo que tenham ocorrido numa FHIR store. Tenha em atenção que o parâmetro de momento específico é obrigatório.
  5. Clique em Continuar.
  6. No segundo passo, podem ser definidos parâmetros opcionais relacionados com recursos. Pode optar por reverter todos os recursos de um determinado tipo (por exemplo, Patient), fornecer uma lista de todos os recursos por identificador (por exemplo, Patient/123) a reverter (armazenados no Google Cloud Storage) ou especificar filtros nos valores dos campos resource.meta para os recursos a reverter.

    Para mais informações sobre os resource.metafiltros, consulte a documentação da API .
  7. Clique em Continuar.
  8. No passo final, pode configurar o comportamento da reversão. Selecione um destino de saída para os resultados da reversão no Google Cloud Storage (este é um campo obrigatório) e indique se quer iniciar um teste e ignorar reversões anteriores.
    • Uma execução de teste não afeta realmente os recursos na loja. O resultado gerado no destino do Cloud Storage selecionado indica o que aconteceria se a reversão entrasse em vigor. Ative esta opção.
    • Se a opção Ignorar reversões anteriores estiver selecionada, os efeitos das operações de reversão anteriores não são considerados quando esta reversão é realizada.
  9. Clique em Reverter. É inicializada uma operação.

REST

  1. Recuperar os recursos FHIR.

    Para fazer um teste, certifique-se de que o campo force está false.

    Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

    • PROJECT_ID: o ID do seu Google Cloud projeto
    • LOCATION: a localização do conjunto de dados
    • DATASET_ID: o conjunto de dados principal do FHIR store
    • FHIR_STORE_ID: o ID da loja FHIR
    • RECOVERY_TIMESTAMP: um ponto de recuperação nos últimos 21 dias. Use o formato RFC 3339. Especifique a hora até ao 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 para uma pasta ou um contentor do Cloud Storage onde os ficheiros de saída são escritos

    Corpo JSON do pedido: 

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

    Para enviar o seu pedido, escolha uma destas opções:

    curl

    Guarde o corpo do pedido num ficheiro denominado request.json. Execute o seguinte comando no terminal para criar ou substituir este ficheiro no diretório atual: 

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

    Em seguida, execute o seguinte comando para enviar o seu pedido 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

    Guarde o corpo do pedido num ficheiro denominado request.json. Execute o seguinte comando no terminal para criar ou substituir este ficheiro no diretório atual: 

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

    Em seguida, execute o seguinte comando para enviar o seu pedido 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

    Copie o corpo do pedido e abra a página de referência do método. O painel do APIs Explorer é aberto no lado direito da página. Pode interagir com esta ferramenta para enviar pedidos. Cole o corpo do pedido nesta ferramenta, preencha todos os outros campos obrigatórios e clique em Executar.

    O resultado é o seguinte. A resposta contém um identificador para uma operação de longa duração (LRO). As operações de longa duração são devolvidas quando as chamadas de métodos podem demorar mais tempo a serem concluídas. Repare no valor de OPERATION_ID. Precisa deste valor no passo seguinte.

  2. Use o método projects.locations.datasets.operations.get para obter o estado da operação de execução longa.

    Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

    • PROJECT_ID: o ID do seu Google Cloud projeto
    • DATASET_ID: o ID do conjunto de dados
    • LOCATION: a localização do conjunto de dados
    • OPERATION_ID: o ID devolvido pela operação de longa duração

    Para enviar o seu pedido, 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

    Explorador de APIs

    Abra a página de referência do método. O painel do APIs Explorer é aberto no lado direito da página. Pode interagir com esta ferramenta para enviar pedidos. Preencha todos os campos obrigatórios e clique em Executar.

    O resultado é o seguinte. Quando a resposta contém "done": true, a operação de longa duração terminou.

Veja os ficheiros de saída da execução de teste

Cada teste de execução produz um ou mais ficheiros que contêm os IDs e os tipos de recursos FHIR a recuperar. Os ficheiros são criados numa subpasta na pasta rollback_resources no contentor do Cloud Storage de destino. O nome da subpasta é o ID da LRO devolvido na resposta fhirStores.rollback. Para ver os ficheiros e garantir que a recuperação funciona conforme esperado, consulte o artigo Ver metadados de objetos.

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

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

Esquema do ficheiro de saída da execução de ensaio

Os ficheiros de saída de uma recuperação de teste usam o esquema apresentado na tabela seguinte:

RESOURCE_TYPE RESOURCE_ID TIMESTAMP
O tipo de recurso FHIR. O ID do recurso FHIR. A hora em que o recurso FHIR foi criado ou atualizado na loja FHIR.

Recupere em produção

Antes de fazer a recuperação em produção, faça um teste de simulação e inspecione os ficheiros de saída do teste de simulação para garantir que a recuperação de produção é executada conforme esperado.

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

Consola

Para reverter uma FHIR store para um estado anterior, siga estes passos:

  1. Na Google Cloud consola, aceda à página Conjuntos de dados.

    Aceda a Conjuntos de dados

  2. Selecione o conjunto de dados que contém o FHIR store ao qual quer reverter.
  3. Na lista Armazenamentos de dados, clique no menu pendente Ações do armazenamento de dados que quer reverter. No menu, clique em Reverter.
  4. No primeiro passo, pode parametrizar a reversão por âmbitos mais amplos, como um ponto no tempo para reverter a FHIR store e reverter todas as operações de um determinado tipo que tenham ocorrido numa FHIR store. Tenha em atenção que o parâmetro de momento específico é obrigatório.
  5. Clique em Continuar.
  6. No segundo passo, podem ser definidos parâmetros opcionais relacionados com recursos. Pode optar por reverter todos os recursos de um determinado tipo (por exemplo, Patient), fornecer uma lista de todos os recursos por identificador (por exemplo, Patient/123) a reverter (armazenados no Google Cloud Storage) ou especificar filtros nos valores dos campos resource.meta para os recursos a reverter.

    Para mais informações sobre os resource.metafiltros, consulte a documentação da API .
  7. Clique em Continuar.
  8. No passo final, pode configurar o comportamento da reversão. Selecione um destino de saída para os resultados da reversão no Google Cloud Storage (este é um campo obrigatório) e indique se quer iniciar um teste e ignorar reversões anteriores.
    • Uma execução de teste não afeta realmente os recursos na loja. O resultado gerado no destino do Cloud Storage selecionado indica o que aconteceria se a reversão entrasse em vigor. Desative esta opção.
    • Se a opção Ignorar reversões anteriores estiver selecionada, os efeitos das operações de reversão anteriores não são considerados quando esta reversão é realizada.
  9. Clique em Reverter. É inicializada uma operação.

REST

  1. Recuperar os recursos FHIR.

    Certifique-se de que o campo force está true.

    Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

    • PROJECT_ID: o ID do seu Google Cloud projeto
    • LOCATION: a localização do conjunto de dados
    • DATASET_ID: o conjunto de dados principal do FHIR store
    • FHIR_STORE_ID: o ID da loja FHIR
    • RECOVERY_TIMESTAMP: um ponto de recuperação nos últimos 21 dias. Use o formato RFC 3339. Especifique a hora até ao 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 para uma pasta ou um contentor do Cloud Storage onde os ficheiros de saída são escritos

    Corpo JSON do pedido: 

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

    Para enviar o seu pedido, escolha uma destas opções:

    curl

    Guarde o corpo do pedido num ficheiro denominado request.json. Execute o seguinte comando no terminal para criar ou substituir este ficheiro no diretório atual: 

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

    Em seguida, execute o seguinte comando para enviar o seu pedido 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

    Guarde o corpo do pedido num ficheiro denominado request.json. Execute o seguinte comando no terminal para criar ou substituir este ficheiro no diretório atual: 

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

    Em seguida, execute o seguinte comando para enviar o seu pedido 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

    Copie o corpo do pedido e abra a página de referência do método. O painel do APIs Explorer é aberto no lado direito da página. Pode interagir com esta ferramenta para enviar pedidos. Cole o corpo do pedido nesta ferramenta, preencha todos os outros campos obrigatórios e clique em Executar.

    O resultado é o seguinte. A resposta contém um identificador para uma operação de longa duração (LRO). As operações de longa duração são devolvidas quando as chamadas de métodos podem demorar mais tempo a serem concluídas. Repare no valor de OPERATION_ID. Precisa deste valor no passo seguinte.

  2. Use o método projects.locations.datasets.operations.get para obter o estado da operação de execução longa.

    Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

    • PROJECT_ID: o ID do seu Google Cloud projeto
    • DATASET_ID: o ID do conjunto de dados
    • LOCATION: a localização do conjunto de dados
    • OPERATION_ID: o ID devolvido pela operação de longa duração

    Para enviar o seu pedido, 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

    Explorador de APIs

    Abra a página de referência do método. O painel do APIs Explorer é aberto no lado direito da página. Pode interagir com esta ferramenta para enviar pedidos. Preencha todos os campos obrigatórios e clique em Executar.

    O resultado é o seguinte. Quando a resposta contém "done": true, a operação de longa duração terminou.

Veja os ficheiros de saída da recuperação de produção

Uma recuperação de produção gera os seguintes ficheiros. Os ficheiros são criados numa subpasta na pasta rollback_resources no contentor do Cloud Storage de destino. O nome da subpasta é o ID da LRO devolvido na resposta fhirStores.rollback. Para ver os ficheiros, consulte o artigo Ver metadados de objetos.

  • success-NUMBER-of-TOTAL_NUMBER.txt: contém recursos FHIR recuperados com êxito.
  • fail-NUMBER-of-TOTAL_NUMBER.txt: contém recursos FHIR que não foram recuperados. É gerado um ficheiro vazio mesmo que não existam falhas.

Nos nomes dos ficheiros, NUMBER é o número do ficheiro e TOTAL_NUMBER é o número total de ficheiros.

Esquema do ficheiro de saída de produção

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

RESOURCE_TYPE RESOURCE_ID ROLLBACK_VERSION_ID NEW_VERSION_ID ERROR_MESSAGE (apenas ficheiros com erros)
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 disableResourceVersioning for true ou se a recuperação de um recurso eliminar o recurso, ROLLBACK_VERSION_ID e NEW_VERSION_ID estão vazios. Apenas ficheiros de erro. Descreve o motivo pelo qual o recurso FHIR foi apresentado para recuperação.

Use filtros para recuperar recursos FHIR específicos

As secções seguintes descrevem como usar filtros para recuperar recursos FHIR com base num critério de filtro. Especifica os filtros no objeto RollbackFhirResourceFilteringFields quando envia um pedido fhirStores.rollback.

Pode combinar filtros ou usá-los individualmente para vários exemplos de utilização, incluindo o seguinte:

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

Use um ficheiro de filtro

Por predefinição, a PITR recupera todos os recursos FHIR numa loja FHIR. Para recuperar recursos FHIR específicos, especifique os tipos de recursos e os respetivos IDs de recursos num ficheiro e, em seguida, carregue o ficheiro para o Cloud Storage. Especifique a localização do ficheiro no campo inputGcsObject.

Para ler um ficheiro de filtro do Cloud Storage, tem de conceder autorizações à conta de serviço do agente do Cloud Healthcare Service. Para mais informações, consulte o artigo Leia ficheiros de filtro do Cloud Storage.

O ficheiro de filtro pode ter qualquer extensão. Tem de 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 ficheiro de filtro:

Patient/8f25b0ac
Observation/d507417e90e
Observation/e9950d90e

Use funções personalizadas

A API Cloud Healthcare oferece as seguintes funções de filtragem personalizadas. Pode 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 o artigo 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 o artigo 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 num elemento extension em que url é uma indicação de tempo Unix. Suporta 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 seguinte, 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 o artigo Definir extensões.

Filtre por tipo de recurso FHIR

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

Filtre por tipo de operação

Para filtrar recursos FHIR que foram 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 eliminados, especifique o valor DELETE.

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

Exclua recuperações anteriores

Para excluir recuperações anteriores ao recuperar recursos FHIR, defina o campo excludeRollbacks como true. Pode excluir recuperações anteriores se as recuperações funcionaram corretamente e não quiser substituir as respetivas alterações. Também pode executar várias recuperações com datas/horas sobrepostas.

Considere o seguinte cenário:

  1. Em 1:00, inicia uma recuperação com a indicação de tempo de recuperação definida como 0:01. Em 2:00, a operação de recuperação elimina os recursos de pacientes Patient/1 e Patient/2 na loja FHIR. A operação de recuperação termina a 3:00.

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

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

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

Filtre através de IDs de operações de longa duração (LRO)

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

Consulte o artigo Apresentar LROs em lista para obter informações sobre como apresentar em lista e ver IDs de LROs num conjunto de dados da Cloud Healthcare API.

Repita os recursos FHIR que não foram recuperados em produção

Se alguns recursos FHIR falharem uma recuperação de produção, pode tentar a recuperação novamente. Use o ficheiro de saída de produção gerado para encontrar os recursos FHIR com falhas. Especifique os tipos destes recursos FHIR e os respetivos IDs num ficheiro de filtro e execute novamente a recuperação.

Cada vez que executa uma recuperação, a recuperação é idempotente se usar a mesma configuração em cada pedido e a data/hora estiver nos últimos 21 dias.

Limitações

  • A PITR não aplica a integridade referencial, independentemente da definição disableReferentialIntegrity na loja FHIR. O restauro de apenas alguns recursos FHIR pode deixar o arquivo FHIR num 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 da loja FHIR tiver sido alterada, a PITR pode deixar a loja FHIR num estado que viole a validação do perfil.

  • Se o valor de rollbackTime preceder a hora em que um recurso FHIR foi eliminado na loja FHIR, a loja FHIR tem de ter a opção enableUpdateCreate ativada ou o recurso não é recuperado.

  • Pode atualizar uma loja FHIR ou ler e escrever dados durante uma recuperação, mas pode ver resultados inesperados consoante a fase de recuperação. Por exemplo, um pedido de leitura pode devolver uma combinação de recursos FHIR recuperados e não recuperados. Se atualizar um recurso, a recuperação pode substituir a atualização.

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