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

Questa pagina descrive come utilizzare il recupero point-in-time (PITR) per ripristinare le risorse FHIR in un datastore FHIR a uno stato all'interno di gli ultimi 21 giorni. Puoi usare PITR per recuperare le modifiche indesiderate, ad esempio per errore l'eliminazione delle risorse FHIR.

Prima di iniziare

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

Cronologia delle versioni delle risorse PITR e FHIR

Il PITR non dipende dalla cronologia delle versioni delle risorse FHIR. Puoi comunque utilizzare PITR se il campo disableResourceVersioning in un datastore FHIR è true o se la cronologia di una risorsa FHIR sono state eliminate.

Flusso di lavoro di recupero

Per assicurarti che un recupero in produzione venga eseguito come previsto, esegui prima una prova. La prova restituisce uno o più file contenenti gli ID e i tipi di Risorse FHIR da recuperare. Verifica la correttezza dei file di output prima eseguendo di nuovo il ripristino in production.

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

Esegui una prova

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

I seguenti esempi mostrano come eseguire una prova utilizzando fhirStores.rollback .

REST

  1. Recupera le risorse FHIR.

    Per eseguire una prova, assicurati che force è false.

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

    • PROJECT_ID: l'ID del tuo progetto Google Cloud
    • LOCATION: la posizione del set di dati
    • DATASET_ID: il set di dati padre del datastore FHIR
    • FHIR_STORE_ID: l'ID del datastore FHIR
    • RECOVERY_TIMESTAMP: un punto di recupero 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 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 delle seguenti 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 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 tutti gli altri campi obbligatori e fai clic su Esegui.

    L'output è il seguente. La risposta contiene un identificatore per un un'operazione a lunga esecuzione (LRO). Le operazioni a lunga esecuzione vengono restituite quando il completamento delle chiamate ai metodi può richiedere più tempo. Prendi nota del valore di OPERATION_ID. Questo valore 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, effettua le seguenti sostituzioni:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud
    • DATASET_ID: l'ID del 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 delle seguenti 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 l'app pagina di riferimento del metodo. Sul lato destro della pagina si apre il riquadro Explorer API. Puoi interagire con questo strumento per inviare richieste. Compila tutti i campi obbligatori e fai clic su Esegui.

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

Visualizza i file di output dry run

Ogni dry run produce uno o più file contenenti gli ID e i tipi di risorse da recuperare. I file vengono creati in una sottocartella della cartella rollback_resources nella destinazione nel bucket Cloud Storage. Il nome della sottocartella è l'ID LRO restituito nella Risposta fhirStores.rollback. Per visualizzare i file e assicurarti che il ripristino 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 ripristino di prova utilizzano lo schema mostrato nell' 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 nel datastore FHIR.

Recupera in produzione

Prima del ripristino in produzione, esegui una prova ed esamina il file di output dry run per garantire che il ripristino in produzione venga eseguito come previsto.

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

REST

  1. Recupera le risorse FHIR.

    Assicurati che la proprietà force è true.

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

    • PROJECT_ID: l'ID del tuo progetto Google Cloud
    • LOCATION: la posizione del set di dati
    • DATASET_ID: il set di dati padre del datastore FHIR
    • FHIR_STORE_ID: l'ID del datastore FHIR
    • RECOVERY_TIMESTAMP: un punto di recupero 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 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 delle seguenti 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 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 tutti gli altri campi obbligatori e fai clic su Esegui.

    L'output è il seguente. La risposta contiene un identificatore per un un'operazione a lunga esecuzione (LRO). Le operazioni a lunga esecuzione vengono restituite quando il completamento delle chiamate ai metodi può richiedere più tempo. Prendi nota del valore di OPERATION_ID. Questo valore 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, effettua le seguenti sostituzioni:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud
    • DATASET_ID: l'ID del 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 delle seguenti 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 l'app pagina di riferimento del metodo. Sul lato destro della pagina si apre il riquadro Explorer API. Puoi interagire con questo strumento per inviare richieste. Compila tutti i campi obbligatori e fai clic su Esegui.

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

Visualizza i file di output del ripristino di produzione

Un ripristino di produzione restituisce i file seguenti. I file vengono creati in un sottocartella nella cartella rollback_resources nella destinazione nel bucket Cloud Storage. Il nome della sottocartella è l'ID LRO restituito nella Risposta fhirStores.rollback. Per visualizzare i file, vedi 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 è stato possibile recuperare. viene generato un file vuoto anche non ci siano errori.

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

Schema del file di output di produzione

I file di operazione riuscita e di errore di un ripristino di produzione usano quanto segue: . I file di errore contengono un'ulteriore Colonna ERROR_MESSAGE.

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'avvio del ripristino. L'ID versione corrente della risorsa dopo il ripristino. Se il valore disableResourceVersioning è true o se il recupero di una risorsa ne comporta l'eliminazione, i valori ROLLBACK_VERSION_ID e NEW_VERSION_ID sono vuoti. Solo file di errore. Descrive perché è stata presentata la risorsa FHIR da recuperare.

Utilizza i filtri per recuperare risorse FHIR specifiche

Le sezioni seguenti descrivono come utilizzare i filtri per il ripristino Risorse FHIR in base a un criterio di filtro. Puoi specificare i filtri nell'oggetto RollbackFhirResourceFilteringFields durante l'invio una richiesta fhirStores.rollback.

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

  • Recupero di risorse FHIR specifiche dopo l'eliminazione accidentale lasciando invariati gli altri.
  • Ripristino di uno stato di un datastore FHIR prima di un'operazione di importazione specifica importato alcune risorse FHIR.

Utilizzare un file filtro

Per impostazione predefinita, PITR recupera tutte le risorse FHIR in un datastore FHIR. Per recuperare risorse FHIR specifiche, specificare i tipi di risorse e i relativi ID in un file. e poi caricare il file di archiviazione ideale in Cloud Storage. Specifica la posizione del file nel inputGcsObject.

Per leggere un file filtro da Cloud Storage, devi concedere le autorizzazioni all'agente di servizio Cloud Healthcare. l'account di servizio. Per ulteriori informazioni, vedi Leggere i file di filtro da Cloud Storage.

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

FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID

Ad esempio, per recuperare una risorsa Patient con ID 8f25b0ac e due Per le risorse di osservazione con ID d507417e90e e e9950d90e, specifica nel file dei filtri:

Patient/8f25b0ac
Observation/d507417e90e
Observation/e9950d90e

Utilizzare funzioni personalizzate

L'API Cloud Healthcare fornisce le seguenti funzioni di filtro personalizzate. Puoi combinare le funzioni personalizzate con rollbackTime campo 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 codici. Per ulteriori informazioni, consulta la sezione Utilizzo dei codici nelle risorse.
code
string
Un valore che identifica un concetto come definito dal sistema di codici. Per ulteriori informazioni, consulta la sezione 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 dove 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, la proprietà url è http://hl7.org/fhir/StructureDefinition/timezone: 
"extension" : [{
  "url" : "http://hl7.org/fhir/StructureDefinition/timezone",
  "valueCode" : "America/New_York"
}]
Per ulteriori informazioni, consulta la sezione Definire le estensioni.

Filtra per tipo di risorsa FHIR

per filtrare le risorse FHIR. in base solo al tipo di risorsa, specifica i tipi nel types[] un array di dati.

Filtra per tipo di operazione

Per filtrare le risorse FHIR modificate da CREATE, UPDATE o DELETE transazione, specifica un valore nel campo ChangeType enum.

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

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

Escludi recuperi precedenti

Per escludere i recuperi precedenti durante il recupero delle risorse FHIR, imposta il valore excludeRollbacks su true. Puoi escludere i recuperi precedenti se i ripristini 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 recupero con il timestamp di recupero impostato su 0:01. Alle ore 2:00, l'operazione di recupero elimina le risorse paziente Patient/1 e Patient/2 nel datastore FHIR. L'operazione di ripristino termina alle ore 3:00.

  2. Diversi giorni dopo, eseguirai un'operazione di ripristino con il timestamp di recupero impostato su 1:00. Per impostazione predefinita, l'esecuzione dell'operazione genera 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 Pazienti Patient/1 e Patient/2 ed evita di ricrearle, imposta excludeRollbacks su true.

Filtra 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 la sezione Elenco degli LRO per informazioni su come elencare e visualizzare gli ID LRO in un set di dati dell'API Cloud Healthcare.

Riprova le risorse FHIR che non sono state recuperate in produzione

Se alcune risorse FHIR non hanno superato il ripristino in produzione, puoi riprovare e il ripristino di emergenza. Usa 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 filtro ed esegui di nuovo il ripristino.

Ogni volta che esegui un ripristino, quest'ultimo è idempotente se utilizzi il comando la stessa configurazione in ogni richiesta il timestamp è compreso negli ultimi 21 giorni.

Limitazioni

  • Il PITR non applica l'integrità referenziale, indipendentemente dal disableReferentialIntegrity sul datastore FHIR. Ripristino solo di alcuni FHIR potrebbero lasciare il datastore FHIR in uno stato che viola le dei dati.

  • Il PITR ignora la convalida del profilo FHIR perché le risorse FHIR ripristinate e sono stati convalidati al momento della creazione o dell'aggiornamento. Se il profilo del datastore FHIR modificata, il PITR potrebbe lasciare il datastore FHIR in uno stato viola la convalida del profilo.

  • Se il valore di rollbackTime è precedente alla data in cui è stata eliminata una risorsa FHIR nel datastore FHIR, nel datastore FHIR deve essere abilitato enableUpdateCreate o la risorsa che non verranno recuperate.

  • Puoi aggiornare un datastore FHIR o leggere e scrivere dati durante un ripristino, ma potresti vedere risultati imprevisti, a seconda della fase di ripristino. Ad esempio: una richiesta di lettura potrebbe restituire una combinazione di risposte recuperate e non recuperate FHIR. Se aggiorni una risorsa, il ripristino potrebbe sovrascrivere aggiornamento.

  • PITR conserva la cronologia delle risorse FHIR. Ogni risorsa ripristinata riceve una nuova versione corrente e la relativa cronologia viene mantenuta.