Questa pagina spiega come gestire le risorse FHIR eseguendo pacchetti FHIR, ovvero una raccolta di operazioni e risorse FHIR da eseguire su quelle risorse FHIR.
Il metodo ExecuteBundle
implementa l'interazione batch/transazione standard FHIR (DSTU2, STU3 e R4) e le operazioni di cronologia.
Bundle FHIR
Un bundle FHIR contiene un array di voci, ciascuna delle quali rappresenta un'operazione, come creazione, aggiornamento o eliminazione, su una risorsa, ad esempio un'osservazione o un paziente. Consulta le descrizioni dettagliate degli elementi nella risorsa bundle.
Quando esegui un bundle FHIR, il tipo di pacchetto determina il modo in cui vengono eseguite le operazioni nel bundle. Sono disponibili i seguenti tipi di bundle:
batch
: esegue le operazioni come più richieste indipendenti.transaction
: esegue le operazioni come richieste multiple che dipendono l'una dall'altra.history
: inserisce le voci nella cronologia di una risorsa.
Ad esempio, supponi che un pacchetto di transazioni includa la creazione di una risorsa Paziente e di una risorsa Osservazione. Se la richiesta di creazione della risorsa Paziente non va a buon fine, la risorsa di osservazione non viene creata.
Se un'operazione non va a buon fine quando il tipo di bundle è batch
, l'API Cloud Healthcare esegue le operazioni rimanenti nel bundle. Se un'operazione non va a buon fine quando il tipo di bundle è transaction
, l'API Cloud Healthcare interrompe l'esecuzione delle operazioni ed esegue il rollback della transazione.
Pacchetti di cronologia
I bundle di cronologia sono estensioni personalizzate dello standard FHIR che supportano i casi d'uso di backup e ripristino, come la sincronizzazione. Puoi utilizzare i bundle di cronologia per inserire o sostituire le versioni delle risorse nella cronologia di una risorsa FHIR. Puoi rimuovere le versioni delle risorse solo utilizzando il metodo Resource-purge
. Il bundle history
viene eseguito come singola transazione con un limite
di 100 voci per bundle. Se una versione della risorsa nel bundle history
ha un timestamp maggiore rispetto all'ultima versione nel datastore FHIR, la versione più recente verrà aggiornata di conseguenza. Se il bundle history
viene inserito correttamente, viene restituita una risposta vuota, altrimenti viene restituita un OperationOutcome
che descrive l'errore.
Il supporto per i bundle della cronologia non è attivato per impostazione predefinita. Un amministratore di datastore FHIR deve
impostare enableHistoryModifications
su true
sulla
configurazione del datastore FHIR.
Non puoi utilizzare i bundle della cronologia se disableResourceVersioning
è impostato su true
nella configurazione dell'archivio FHIR.
I bundle della cronologia vengono forniti nello stesso formato in cui vengono restituiti dal metodo fhir.history
. Per essere valida, ogni voce del bundle richiede un ID risorsa, un timestamp della modifica e uno stato. Inoltre, tutte le voci devono avere lo stesso ID risorsa. L'ID risorsa viene fornito con il campo resource.id
o request.url
. Se i campi vengono forniti, l'ID risorsa fornito sarà lo stesso. Il timestamp della risorsa viene fornito con il campo meta.lastUpdated
nella risorsa o nel campo response.lastModified
.
Concessione delle autorizzazioni per l'esecuzione di bundle
Per eseguire i bundle è necessario il ruolo di autorizzazione datasets.fhirStores.fhir.executeBundle
. Per concedere questa autorizzazione, utilizza il ruolo healthcare.fhirResourceReader
. Per la procedura per concedere questa autorizzazione, consulta Modifica di un criterio.
Per eseguire i bundle della cronologia, è richiesto anche il ruolo di autorizzazione datasets.fhirStores.fhir.import
.
L'API Cloud Healthcare controlla le autorizzazioni per ogni operazione nel bundle.
Se hai l'autorizzazione healthcare.fhirResources.create
ma non l'autorizzazione healthcare.fhirResources.update
, puoi eseguire solo bundle contenenti operazioni healthcare.fhirResources.create
.
Esecuzione di un bundle
Per eseguire un bundle FHIR, utilizza il metodo projects.locations.datasets.fhirStores.fhir.executeBundle
.
Nei seguenti esempi, BUNDLE.json è il percorso e il nome file di un bundle FHIR con codifica JSON. Puoi anche includere il bundle nel corpo della richiesta.
Il seguente bundle di esempio crea una risorsa Patient ed elimina un'altra risorsa:
{
"resourceType": "Bundle",
"id": "bundle-transaction",
"meta": {
"lastUpdated": "2018-03-11T11:22:16Z"
},
"type": "transaction",
"entry": [
{
"resource": {
"resourceType": "Patient",
"name": [
{
"family": "Smith",
"given": [
"Darcy"
]
}
],
"gender": "female",
"address": [
{
"line": [
"123 Main St."
],
"city": "Anycity",
"state": "CA",
"postalCode": "12345"
}
]
},
"request": {
"method": "POST",
"url": "Patient"
}
},
{
"request": {
"method": "DELETE",
"url": "Patient/1234567890"
}
}
]
}
I seguenti esempi mostrano come eseguire un bundle.
curl
Per eseguire un bundle, effettua una richiesta POST
e specifica le seguenti informazioni:
- Il nome e la posizione del set di dati padre e del datastore FHIR
- Il percorso del file del bundle sulla tua macchina locale
- Un token di accesso
Il seguente esempio mostra una richiesta POST
mediante curl:
curl -X POST \ -H "Content-Type: application/fhir+json; charset=utf-8" \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ --data @BUNDLE_FILE.json \ "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir"
Indipendentemente dal risultato delle singole operazioni, dopo l'esecuzione di un bundle batch, il server restituisce una rappresentazione con codifica JSON di una risorsa Bundle
di tipo batch-response
. La risorsa Bundle
contiene una voce per ogni voce nella richiesta con il risultato dell'elaborazione della voce, che potrebbe essere un mix di risultati di operazione riuscita.
Se un bundle di transazioni ha esito positivo, il server restituisce una rappresentazione con codifica JSON di una risorsa Bundle
di tipo transaction-response
contenente una voce per ogni voce della richiesta con il risultato dell'operazione riuscita.
Se si verifica un errore durante l'esecuzione di un bundle di transazioni, il corpo della risposta non contiene un bundle. Contiene invece una risorsa OperationOutcome
con codifica JSON che descrive il motivo dell'errore. Le operazioni riuscite che sono state sottoposte a rollback non vengono riportate nella risposta.
Il seguente bundle di esempio è l'output dell'esecuzione dell'esempio riportato sopra. La prima voce indica il successo dell'operazione di creazione di un paziente e include l'ID della nuova risorsa. La seconda voce indica l'esito positivo dell'operazione di eliminazione.
{ "entry": [ { "response": { "location": projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE/RESOURCE_ID, "status": "201 Created" } }, { "response": { "status": "200 OK" } } ], "resourceType": "Bundle", "type": "transaction-response" }
PowerShell
Per eseguire un bundle, effettua una richiesta POST
e specifica le seguenti informazioni:
- Il nome e la posizione del set di dati padre e del datastore FHIR
- Il percorso del file del bundle sulla tua macchina locale
- Un token di accesso
Il seguente esempio mostra una richiesta POST
mediante Windows PowerShell:
$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } Invoke-RestMethod ` -Method Post ` -Headers $headers ` -ContentType: "application/fhir+json" ` -InFile BUNDLE_FILE.json ` -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir" | ConvertTo-Json
Indipendentemente dal risultato delle singole operazioni, dopo l'esecuzione di un bundle batch, il server restituisce una rappresentazione con codifica JSON di una risorsa Bundle
di tipo batch-response
. La risorsa Bundle
contiene una voce per ogni voce nella richiesta con il risultato dell'elaborazione della voce, che potrebbe essere un mix di risultati di operazione riuscita.
Se un bundle di transazioni ha esito positivo, il server restituisce una rappresentazione con codifica JSON di una risorsa Bundle
di tipo transaction-response
contenente una voce per ogni voce della richiesta con il risultato dell'operazione riuscita.
Se si verifica un errore durante l'esecuzione di un bundle di transazioni, il corpo della risposta non contiene un bundle. Contiene invece una risorsa OperationOutcome
con codifica JSON che descrive il motivo dell'errore. Le operazioni riuscite che sono state sottoposte a rollback non vengono riportate nella risposta.
Il seguente bundle di esempio è l'output dell'esecuzione dell'esempio riportato sopra. La prima voce indica il successo dell'operazione di creazione di un paziente e include l'ID della nuova risorsa. La seconda voce indica l'esito positivo dell'operazione di eliminazione.
{ "entry": [ { "response": { "etag": "ETAG", "lastModified": "2020-08-03T04:12:47.312669+00:00", "location": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE/RESOURCE_ID", "status": "201 Created" } }, { "response": { "etag": "ETAG", "lastModified": "2020-08-03T04:12:47.312669+00:00", "status": "200 OK" } } ], "resourceType": "Bundle", "type": "transaction-response" }
Go
Java
Node.js
Un file bundle di esempio è disponibile nel repository GitHub dell'esempio di codice.
Python
Un file bundle di esempio è disponibile nel repository GitHub dell'esempio di codice.
Effettua una richiesta di PATCH
Puoi utilizzare i bundle FHIR per effettuare richieste JSON PATCH
sulle risorse FHIR.
Per ulteriori informazioni, consulta Esecuzione di una richiesta PATCH
in un bundle FHIR.
Risoluzione dei riferimenti alle risorse create in un bundle
Le risorse in un pacchetto di transazioni possono contenere riferimenti a risorse che non esistono nel sistema di destinazione, ma vengono create durante l'esecuzione del bundle. L'API Cloud Healthcare risolve l'associazione tra le risorse utilizzando il campo entry.fullUrl
. I riferimenti che corrispondono al valore entry.fullUrl
di un'altra risorsa del bundle vengono riscritti nell'ID della risorsa corrispondente nell'archivio. L'operazione riesce indipendentemente
dall'ordine delle operazioni nel bundle.
L'API Cloud Healthcare accetta fullUrl
nei seguenti formati:
urn:uuid:UUID
urn:oid:OID
- qualsiasi URL
- un nome di risorsa nel formato
RESOURCE_TYPE/RESOURCE_ID
, ad esempioPatient/123
. Non è consigliabile utilizzare questo formato perchéfullUrl
è un segnaposto locale del bundle. Questo può creare confusione se una risorsa nell'archivio ha lo stesso nome, ma la risorsa nel bundle ha un nome diverso a seguito di un'operazione di creazione.
Il seguente bundle di esempio crea una risorsa Patient e una risorsa Osservazione che fa riferimento alla risorsa Paziente.
{
"resourceType": "Bundle",
"type": "transaction",
"entry":[
{
"request": {
"method":"POST",
"url":"Patient"
},
"fullUrl": "urn:uuid:05efabf0-4be2-4561-91ce-51548425acb9",
"resource": {
"resourceType":"Patient",
"gender":"male"
}
},
{
"request": {
"method":"POST",
"url":"Observation"
},
"resource": {
"resourceType":"Observation",
"subject": {
"reference": "urn:uuid:05efabf0-4be2-4561-91ce-51548425acb9"
},
"status":"preliminary",
"code": {
"text":"heart rate"
}
}
}
]
}
I seguenti esempi mostrano come eseguire un bundle.
curl
Un file bundle di esempio è disponibile nel repository GitHub dell'esempio di codice.
Per eseguire un bundle, effettua una richiesta POST e specifica le seguenti informazioni:
- Il nome e la posizione del set di dati padre e del datastore FHIR
- La posizione del file del bundle in Cloud Storage
- Un token di accesso
Il seguente esempio mostra una richiesta POST
mediante curl:
curl -X POST \ -H "Content-Type: application/fhir+json; charset=utf-8" \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ --data @BUNDLE_FILE.json \ "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir"
Il seguente bundle di esempio è l'output dell'esecuzione dell'esempio riportato sopra. La prima voce indica il successo dell'operazione di creazione di un paziente e include l'ID della nuova risorsa. La seconda voce indica l'esito positivo dell'operazione di creazione dell'osservazione e include l'ID della nuova risorsa.
{ "entry": [ { "response": { "etag": "ETAG1", "lastModified": "2020-08-04T16:14:14.273976+00:00", "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/datasets/REGION/fhirStores/FHIR_STORE_ID/fhir/Patient/PATIENT_ID/_history/HISTORY_ID", "status": "201 Created" } }, { "response": { "etag": "ETAG", "lastModified": "2020-08-04T16:14:14.273976+00:00", "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/datasets/REGION/fhirStores/FHIR_STORE_ID/fhir/Observation/OBSERVATION_ID/_history/HISTORY_ID", "status": "201 Created" } } ], "resourceType": "Bundle", "type": "transaction-response" }
PowerShell
Un file bundle di esempio è disponibile nel repository GitHub dell'esempio di codice.
Per eseguire un bundle, effettua una richiesta POST e specifica le seguenti informazioni:
- Il nome e la posizione del set di dati padre e del datastore FHIR
- La posizione del file del bundle in Cloud Storage
- Un token di accesso
Il seguente esempio mostra una richiesta POST
mediante Windows PowerShell:
$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } Invoke-RestMethod ` -Method Post ` -Headers $headers ` -ContentType: "application/fhir+json" ` -InFile BUNDLE_FILE.json ` -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir" | ConvertTo-Json
Il seguente bundle di esempio è l'output dell'esecuzione dell'esempio riportato sopra. La prima voce indica il successo dell'operazione di creazione di un paziente e include l'ID della nuova risorsa. La seconda voce indica l'esito positivo dell'operazione di creazione dell'osservazione e include l'ID della nuova risorsa.
{ "entry": [ { "response": { "etag": "ETAG1", "lastModified": "2020-08-04T16:14:14.273976+00:00", "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/datasets/REGION/fhirStores/FHIR_STORE_ID/fhir/Patient/PATIENT_ID/_history/HISTORY_ID", "status": "201 Created" } }, { "response": { "etag": "ETAG", "lastModified": "2020-08-04T16:14:14.273976+00:00", "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/datasets/REGION/fhirStores/FHIR_STORE_ID/fhir/Observation/OBSERVATION_ID/_history/HISTORY_ID", "status": "201 Created" } } ], "resourceType": "Bundle", "type": "transaction-response" }