Recuperare le risorse FHIR con il recupero point-in-time (PITR)

Questa pagina descrive come utilizzare il recupero point-in-time (PITR) per recuperare le risorse FHIR in un FHIR store in uno stato entro gli ultimi 21 giorni. Puoi utilizzare il PITR per eseguire il ripristino da modifiche indesiderate, ad esempio l'eliminazione accidentale di risorse FHIR.

Prima di iniziare

Le richieste PITR sono classificate come richieste di operazioni avanzate e vengono fatturate di conseguenza. Prima di utilizzare PITR, esamina i prezzi per le richieste di operazioni avanzate.

PITR e cronologia delle versioni delle risorse FHIR

PITR non dipende dalla cronologia delle versioni delle risorse FHIR. Puoi comunque utilizzare il recupero point-in-time se il campo disableResourceVersioning in un archivio FHIR è true o se le versioni cronologiche di una risorsa FHIR sono state eliminate.

Flusso di lavoro di recupero

Per assicurarti che il recupero della produzione venga eseguito come previsto, esegui prima una prova. La simulazione genera uno o più file contenenti gli ID e i tipi di risorse FHIR da recuperare. Verifica la correttezza dei file di output prima di eseguire di nuovo il recupero in produzione.

Per recuperare risorse specifiche o in base a un criterio di filtro, specifica un filtro.

Esegui una prova

Prima di recuperare le risorse FHIR in produzione, esegui una prova.

Gli esempi riportati di seguito mostrano come eseguire una prova generale utilizzando il metodo fhirStores.rollback.

REST

  1. Recupera le risorse FHIR.

    Per eseguire una prova dry run, assicurati che il campo force sia false.

    Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

    • PROJECT_ID: l'ID del tuo Google Cloud progetto
    • LOCATION: la posizione del set di dati
    • DATASET_ID: il set di dati padre dell'archivio FHIR
    • FHIR_STORE_ID: l'ID datastore FHIR
    • RECOVERY_TIMESTAMP: un punto di ripristino negli ultimi 21 giorni. Utilizza il formato RFC 3339. Specifica l'ora al secondo e includi un fuso orario, ad esempio 2015-02-07T13:28:17.239+02:00 o 2017-01-01T00:00:00Z.
    • CLOUD_STORAGE_BUCKET: l'URI completo di una cartella o di un bucket Cloud Storage in cui vengono scritti i file di output

    Corpo JSON della richiesta: 

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

    Per inviare la richiesta, scegli una di queste opzioni:

    curl

    Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente: 

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

    Quindi, esegui questo comando per inviare la richiesta 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

    Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente: 

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

    Quindi, esegui questo comando per inviare la richiesta 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

    Explorer API

    Copia il corpo della richiesta e apri la pagina di riferimento del metodo. Sul lato destro della pagina si apre il riquadro Explorer API. Puoi interagire con questo strumento per inviare richieste. Incolla il corpo della richiesta in questo strumento, compila gli altri campi obbligatori e fai clic su Esegui.

    L'output è il seguente. La risposta contiene un identificatore per un'operazione a lunga esecuzione (LRO). Le operazioni a lunga esecuzione vengono restituite quando le chiamate ai metodi potrebbero richiedere più tempo per essere completate. Prendi nota del valore di OPERATION_ID. Ti servirà nel passaggio successivo.

  2. Utilizza il metodo projects.locations.datasets.operations.get per ottenere lo stato dell'operazione a lunga esecuzione.

    Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

    • PROJECT_ID: l'ID del tuo Google Cloud progetto
    • DATASET_ID: l'ID set di dati
    • LOCATION: la posizione del set di dati
    • OPERATION_ID: l'ID restituito dall'operazione a lunga esecuzione

    Per inviare la richiesta, scegli una di queste opzioni:

    curl

    Esegui questo 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

    Esegui questo 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

    Explorer API

    Apri la pagina di riferimento del metodo. Sul lato destro della pagina si apre il riquadro Explorer API. Puoi interagire con questo strumento per inviare richieste. Completa i campi obbligatori e fai clic su Esegui.

    L'output è il seguente. Quando la risposta contiene "done": true, l'operazione a lunga esecuzione è terminata.

Visualizzare i file di output dry run

Ogni prova generale genera uno o più file contenenti gli ID e i tipi di risorse FHIR da recuperare. I file vengono creati in una sottocartella della cartella rollback_resources nel bucket Cloud Storage di destinazione. Il nome della sottocartella è l'ID LRO restituito nella risposta fhirStores.rollback. Per visualizzare i file e assicurarti che il recupero funzioni come previsto, consulta Visualizza i metadati degli oggetti.

Il numero di file è proporzionale al numero di risorse FHIR recuperate.

I nomi dei file utilizzano il formato trial-NUMBER-of-TOTAL_NUMBER.txt, dove NUMBER è il numero del file e TOTAL_NUMBER è il numero totale di file.

Schema del file di output dry run

I file di output di un recupero di prova utilizzano lo schema mostrato nella tabella seguente:

RESOURCE_TYPE RESOURCE_ID TIMESTAMP
Il tipo di risorsa FHIR. L'ID risorsa FHIR. L'ora in cui la risorsa FHIR è stata creata o aggiornata nell'archivio FHIR.

Recupero in produzione

Prima del recupero in produzione, esegui una prova generale e ispeziona i file di output della prova generale per assicurarti che il recupero della produzione venga eseguito come previsto.

Gli esempi riportati di seguito mostrano come ripristinare le risorse FHIR in produzione utilizzando il metodo fhirStores.rollback.

REST

  1. Recupera le risorse FHIR.

    Assicurati che il campo force sia true.

    Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

    • PROJECT_ID: l'ID del tuo Google Cloud progetto
    • LOCATION: la posizione del set di dati
    • DATASET_ID: il set di dati padre dell'archivio FHIR
    • FHIR_STORE_ID: l'ID datastore FHIR
    • RECOVERY_TIMESTAMP: un punto di ripristino negli ultimi 21 giorni. Utilizza il formato RFC 3339. Specifica l'ora al secondo e includi un fuso orario, ad esempio 2015-02-07T13:28:17.239+02:00 o 2017-01-01T00:00:00Z.
    • CLOUD_STORAGE_BUCKET: l'URI completo di una cartella o di un bucket Cloud Storage in cui vengono scritti i file di output

    Corpo JSON della richiesta: 

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

    Per inviare la richiesta, scegli una di queste opzioni:

    curl

    Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente: 

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

    Quindi, esegui questo comando per inviare la richiesta 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

    Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente: 

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

    Quindi, esegui questo comando per inviare la richiesta 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

    Explorer API

    Copia il corpo della richiesta e apri la pagina di riferimento del metodo. Sul lato destro della pagina si apre il riquadro Explorer API. Puoi interagire con questo strumento per inviare richieste. Incolla il corpo della richiesta in questo strumento, compila gli altri campi obbligatori e fai clic su Esegui.

    L'output è il seguente. La risposta contiene un identificatore per un'operazione a lunga esecuzione (LRO). Le operazioni a lunga esecuzione vengono restituite quando le chiamate ai metodi potrebbero richiedere più tempo per essere completate. Prendi nota del valore di OPERATION_ID. Ti servirà nel passaggio successivo.

  2. Utilizza il metodo projects.locations.datasets.operations.get per ottenere lo stato dell'operazione a lunga esecuzione.

    Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

    • PROJECT_ID: l'ID del tuo Google Cloud progetto
    • DATASET_ID: l'ID set di dati
    • LOCATION: la posizione del set di dati
    • OPERATION_ID: l'ID restituito dall'operazione a lunga esecuzione

    Per inviare la richiesta, scegli una di queste opzioni:

    curl

    Esegui questo 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

    Esegui questo 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

    Explorer API

    Apri la pagina di riferimento del metodo. Sul lato destro della pagina si apre il riquadro Explorer API. Puoi interagire con questo strumento per inviare richieste. Completa i campi obbligatori e fai clic su Esegui.

    L'output è il seguente. Quando la risposta contiene "done": true, l'operazione a lunga esecuzione è terminata.

Visualizzare i file di output del recupero della produzione

Un recupero della produzione genera i seguenti file. I file vengono creati in una sottocartella della cartella rollback_resources nel bucket Cloud Storage di destinazione. Il nome della sottocartella è l'ID LRO restituito nella risposta fhirStores.rollback. Per visualizzare i file, consulta Visualizza i metadati degli oggetti.

  • success-NUMBER-of-TOTAL_NUMBER.txt: Contiene le risorse FHIR recuperate correttamente.
  • fail-NUMBER-of-TOTAL_NUMBER.txt: Contiene risorse FHIR che non sono state recuperate. Viene generato un file vuoto anche se non si verificano errori.

Nei nomi dei file, NUMBER è il numero del file e TOTAL_NUMBER è il numero totale di file.

Schema del file di output di produzione

I file di esito positivo e negativo di un recupero della produzione utilizzano lo schema seguente. I file di errore contengono una colonna ERROR_MESSAGE aggiuntiva.

RESOURCE_TYPE RESOURCE_ID ROLLBACK_VERSION_ID NEW_VERSION_ID ERROR_MESSAGE (solo file di errore)
Il tipo di risorsa FHIR. L'ID risorsa FHIR. L'ID versione corrente della risorsa al momento dell'inizio del recupero. L'ID versione corrente della risorsa dopo il recupero. Se disableResourceVersioning è true o se il recupero di una risorsa comporterebbe l'eliminazione della risorsa, ROLLBACK_VERSION_ID e NEW_VERSION_ID sono vuoti. Solo file di errore. Descrive il motivo per cui il recupero della risorsa FHIR non è riuscito.

Utilizzare i filtri per recuperare risorse FHIR specifiche

Le sezioni seguenti descrivono come utilizzare i filtri per recuperare le risorse FHIR in base a un criterio di filtro. Specifichi i filtri nell'oggetto RollbackFhirResourceFilteringFields quando invii una richiesta fhirStores.rollback.

Puoi combinare i filtri o utilizzarli singolarmente per più casi d'uso, tra cui:

  • Recupero di risorse FHIR specifiche dopo l'eliminazione accidentale lasciando invariate le altre.
  • Ripristino di un datastore FHIR a uno stato precedente a un'operazione di importazione specifica che ha importato determinate risorse FHIR.

Utilizzare un file di filtri

Per impostazione predefinita, il PITR recupera tutte le risorse FHIR in un archivio FHIR. Per recuperare risorse FHIR specifiche, specifica i tipi di risorse e i relativi ID risorsa in un file, quindi carica il file in Cloud Storage. Specifica la posizione del file nel campo inputGcsObject.

Per leggere un file di filtri da Cloud Storage, devi concedere le autorizzazioni al account di servizio dell'agente di servizio Cloud Healthcare. Per maggiori informazioni, consulta Leggere i file di filtro da Cloud Storage.

Il file di filtro può avere qualsiasi estensione. Deve utilizzare lo schema seguente, con una risorsa FHIR per riga:

FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID

Ad esempio, per recuperare una risorsa Patient con l'ID 8f25b0ac e due risorse Observation con gli ID d507417e90e e e9950d90e, specifica quanto segue nel file di filtro:

Patient/8f25b0ac
Observation/d507417e90e
Observation/e9950d90e

Utilizzare le funzioni personalizzate

L'API Cloud Healthcare fornisce le seguenti funzioni di filtro personalizzato. Puoi combinare le funzioni personalizzate con il campo rollbackTime per applicare un filtro aggiuntivo.

tag
Dettagli
Sintassi della funzione
tag("system") = "code"
Descrizione
Filtra le risorse FHIR in base all'elemento Meta.tag della risorsa.
Argomenti
system
string
Un URL che fa riferimento a un sistema di codifica. Per saperne di più, consulta Utilizzo dei codici nelle risorse.
code
string
Un valore che identifica un concetto come definito dal sistema di codifica. Per saperne di più, consulta Utilizzo dei codici nelle risorse.
extension_value_ts
Dettagli
Sintassi della funzione
extension_value_ts("url")
Descrizione
Filtra le risorse FHIR in base al valore url in un elemento extension in cui url è un timestamp Unix. Supporta i seguenti operatori di confronto:
  • =
  • !=
  • <
  • >
  • <=
  • >=
Argomenti
url
string
L'URL canonico di una risorsa StructureDefinition che definisce un'estensione. Ad esempio, nel seguente elemento extension, il url è http://hl7.org/fhir/StructureDefinition/timezone: 
"extension" : [{
  "url" : "http://hl7.org/fhir/StructureDefinition/timezone",
  "valueCode" : "America/New_York"
}]
Per ulteriori informazioni, vedi Definizione delle estensioni.

Filtra per tipo di risorsa FHIR

Per filtrare le risorse FHIR in modo più ampio in base solo al tipo di risorsa, specifica i tipi di risorse nell'array types[].

Filtra per tipo di operazione

Per filtrare le risorse FHIR modificate da una transazione CREATE, UPDATE o DELETE, specifica un valore nell'enumerazione ChangeType.

Ad esempio, per recuperare solo le risorse FHIR eliminate, specifica il valore DELETE.

Se specifichi CHANGE_TYPE_UNSPECIFIED, ALL o non specifichi un valore, vengono recuperate tutte le risorse FHIR.

Escludi recuperi precedenti

Per escludere i recuperi precedenti durante il recupero delle risorse FHIR, imposta il campo excludeRollbacks su true. Puoi escludere i recuperi precedenti se hanno funzionato correttamente e non vuoi sovrascrivere le modifiche. Puoi anche eseguire più recuperi con timestamp sovrapposti.

Considera il seguente scenario:

  1. Alle ore 1:00, avvii un ripristino con il timestamp di ripristino impostato su 0:01. Alle ore 2:00, l'operazione di ripristino elimina le risorse paziente Patient/1 e Patient/2 nell'archivio FHIR. L'operazione di recupero termina alle ore 3:00.

  2. Diversi giorni dopo, esegui un'operazione di ripristino con il timestamp di ripristino impostato su 1:00. Per impostazione predefinita, l'esecuzione dell'operazione comporterebbe quanto segue:

    • Ricreazione errata delle risorse paziente Patient/1 e Patient/2.
    • Recupero corretto delle risorse FHIR create o aggiornate dopo il giorno 3:00.

Per escludere l'operazione di recupero iniziale che ha eliminato le risorse paziente Patient/1 e Patient/2 ed evitare di ricrearle, imposta excludeRollbacks su true.

Filtrare utilizzando gli ID operazione a lunga esecuzione (LRO)

Se le risorse FHIR sono state modificate da una o più operazioni a lunga esecuzione (LRO), puoi specificare gli ID LRO nel campo operationIds per recuperare le risorse modificate.

Consulta Elenco delle operazioni LRO per informazioni su come elencare e visualizzare gli ID LRO in un set di dati dell'API Cloud Healthcare.

Riprova a recuperare le risorse FHIR che non sono state recuperate in produzione

Se il recupero della produzione non è riuscito per alcune risorse FHIR, puoi riprovare a eseguire il recupero. Utilizza il file di output di produzione generato per trovare le risorse FHIR non riuscite. Specifica i tipi di queste risorse FHIR e i relativi ID in un file di filtri ed esegui di nuovo il recupero.

Ogni volta che esegui un ripristino, questo è idempotente se utilizzi la stessa configurazione in ogni richiesta e il timestamp rientra negli ultimi 21 giorni.

Limitazioni

  • Il ripristino temporizzato non applica l'integrità referenziale, indipendentemente dall'impostazione disableReferentialIntegrity nell'archivio FHIR. Il ripristino solo di alcune risorse FHIR potrebbe lasciare il datastore FHIR in uno stato che viola l'integrità referenziale.

  • Il ripristino temporaneo ignora la convalida del profilo FHIR perché le risorse FHIR ripristinate sono state convalidate al momento della creazione o dell'aggiornamento. Se la configurazione del profilo del datastore FHIR è cambiata, PITR potrebbe lasciare il datastore FHIR in uno stato che viola la convalida del profilo.

  • Se il valore di rollbackTime precede il momento in cui una risorsa FHIR è stata eliminata nell'archivio FHIR, l'archivio FHIR deve avere enableUpdateCreate abilitato o la risorsa non verrà recuperata.

  • Puoi aggiornare un archivio FHIR o leggere e scrivere dati durante un ripristino, ma potresti visualizzare risultati imprevisti a seconda della fase di ripristino. Ad esempio, una richiesta di lettura potrebbe restituire una combinazione di risorse FHIR recuperate e non recuperate. Se aggiorni una risorsa, il recupero potrebbe sovrascrivere l'aggiornamento.

  • PITR conserva la cronologia delle risorse FHIR. A ogni risorsa ripristinata viene assegnata una nuova versione corrente e la relativa cronologia viene conservata.