In questa pagina viene descritto come utilizzare il recupero point-in-time (PITR) per recuperare le risorse FHIR in un datastore FHIR allo stato degli ultimi 21 giorni. Puoi utilizzare PITR per ripristinare l'account in seguito a 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, consulta i prezzi delle richieste con operazioni avanzate.
Cronologia delle versioni delle risorse PITR e FHIR
Il PITR non dipende dalla cronologia delle versioni delle risorse FHIR.
Puoi comunque utilizzare il PITR se il campo disableResourceVersioning
in un datastore FHIR è true
o se le versioni storiche 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 di eseguire di nuovo il ripristino in production.
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.
I seguenti esempi mostrano come eseguire una prova utilizzando il metodo fhirStores.rollback
.
REST
Recupera le risorse FHIR.
Per eseguire una prova, assicurati che il campo
force
siafalse
.Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
PROJECT_ID
: l'ID del tuo progetto Google CloudLOCATION
: la posizione del set di datiDATASET_ID
: il set di dati padre del datastore FHIRFHIR_STORE_ID
: l'ID del datastore FHIRRECOVERY_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 esempio2015-02-07T13:28:17.239+02:00
o2017-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 attuale: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 attuale:@' { "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 ContentExplorer 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 tutti gli altri campi obbligatori e fai clic su Esegui.
OPERATION_ID
. Questo valore ti servirà nel passaggio successivo.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 CloudDATASET_ID
: l'ID del set di datiLOCATION
: la posizione del set di datiOPERATION_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 ContentExplorer 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. Compila tutti i campi obbligatori e fai clic su Esegui.
"done": true
, l'operazione a lunga esecuzione è terminata.
Visualizza i file di output dry run
Ogni dry run 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 ripristino funzioni come previsto, consulta Visualizzare 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 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 nel datastore FHIR. |
Recupera in produzione
Prima del ripristino in produzione, esegui una procedura di prova ed esamina i file di output del dry run per assicurarti che il ripristino in produzione venga eseguito come previsto.
Gli esempi riportati di seguito mostrano come ripristinare le risorse FHIR in produzione utilizzando il metodo fhirStores.rollback
.
REST
Recupera le risorse FHIR.
Assicurati che il campo
force
siatrue
.Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
PROJECT_ID
: l'ID del tuo progetto Google CloudLOCATION
: la posizione del set di datiDATASET_ID
: il set di dati padre del datastore FHIRFHIR_STORE_ID
: l'ID del datastore FHIRRECOVERY_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 esempio2015-02-07T13:28:17.239+02:00
o2017-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 attuale: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 attuale:@' { "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 ContentExplorer 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 tutti gli altri campi obbligatori e fai clic su Esegui.
OPERATION_ID
. Questo valore ti servirà nel passaggio successivo.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 CloudDATASET_ID
: l'ID del set di datiLOCATION
: la posizione del set di datiOPERATION_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 ContentExplorer 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. Compila tutti i campi obbligatori e fai clic su Esegui.
"done": true
, l'operazione a lunga esecuzione è terminata.
Visualizza i file di output del ripristino di produzione
Un ripristino di produzione restituisce i file seguenti. 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 Visualizzare 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 se non si verificano errori.
Nei nomi dei file, NUMBER
è il numero del file, mentre 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 utilizzano il seguente schema. 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'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 seguenti sezioni descrivono come utilizzare i filtri per recuperare le risorse FHIR in base a un criterio di filtro.
Puoi specificare 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:
- Il recupero di risorse FHIR specifiche dopo l'eliminazione accidentale lasciando invariati gli altri.
- Ripristinare uno stato di un datastore FHIR prima che una specifica operazione di importazione importasse determinate risorse FHIR.
Utilizzare un file filtro
Per impostazione predefinita, PITR recupera tutte le risorse FHIR in un datastore FHIR. Per recuperare risorse FHIR specifiche, specifica i tipi di risorsa e i relativi ID in un file, quindi carica il file in Cloud Storage. Specifica la posizione del file nel campo inputGcsObject
.
Per leggere un file filtro da Cloud Storage, devi concedere le autorizzazioni all'account di servizio dell'agente di servizio Cloud Healthcare. Per ulteriori informazioni, vedi Leggere i file di filtro da Cloud Storage.
Il file filtro può avere qualsiasi estensione. Deve utilizzare il seguente schema, con una risorsa FHIR per riga:
FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID
Ad esempio, per recuperare una risorsa Patient con ID 8f25b0ac
e due risorse di osservazione con gli ID d507417e90e
e e9950d90e
, specifica quanto segue 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 il campo rollbackTime
per applicare un filtro aggiuntivo.
tag
Dettagli Sintassi della funzione tag("system") = "code"
Descrizione Filtra le risorse FHIR in base all'elementoMeta.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 valoreurl
in un elementoextension
doveurl
è 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 elementoextension
,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 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'enum 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, tutte le risorse FHIR vengono recuperate.
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 i recuperi hanno funzionato correttamente e non vuoi sovrascrivere le modifiche.
Puoi anche eseguire più recuperi con timestamp sovrapposti.
Considera il seguente scenario:
- Alle ore
1:00
, avvii un recupero con il timestamp di recupero impostato su0:01
. In2:00
, l'operazione di ripristino elimina le risorse pazientePatient/1
ePatient/2
nel datastore FHIR. L'operazione di ripristino termina alle ore3:00
. Diversi giorni dopo, esegui un'operazione di recupero 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
ePatient/2
. - Recupero corretto delle risorse FHIR create o aggiornate dopo il giorno
3:00
.
- Ricreazione errata delle risorse Paziente
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
.
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 Elenco di 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 il ripristino in produzione di alcune risorse FHIR non è andato a buon fine, puoi riprovare. Usa il file di output di produzione generato per trovare le risorse FHIR in errore. 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, il recupero è idempotente se utilizzi la stessa configurazione in ogni richiesta e il timestamp è compreso negli ultimi 21 giorni.
Limitazioni
Il PITR non applica l'integrità referenziale, indipendentemente dall'impostazione
disableReferentialIntegrity
sul datastore FHIR. Il ripristino solo di alcune risorse FHIR potrebbe lasciare il datastore FHIR in uno stato che viola l'integrità referenziale.PITR 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
è precedente alla data in cui una risorsa FHIR è stata eliminata nel datastore FHIR, nel datastore FHIR deve essere abilitatoenableUpdateCreate
, altrimenti la risorsa non verrà recuperata.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 risorse FHIR recuperate e non recuperate. Se aggiorni una risorsa, il ripristino potrebbe sovrascrivere l'aggiornamento.
PITR conserva la cronologia delle risorse FHIR. Ogni risorsa ripristinata riceve una nuova versione attuale e la relativa cronologia viene conservata.