Questa pagina spiega come gestire le risorse FHIR eseguendo bundle FHIR, che sono una raccolta di risorse FHIR e operazioni da eseguire su queste risorse FHIR.
Il metodo
ExecuteBundle
implementa le operazioni batch/transazione standard FHIR
(DSTU2,
STU3,
R4
e R5) e cronologia.
Bundle FHIR
Un bundle FHIR contiene un array di voci, ognuna delle quali rappresenta un'operazione, ad esempio 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 bundle determina la modalità di esecuzione delle operazioni nel bundle. Sono disponibili i seguenti tipi di bundle:
batch
: esegue le operazioni come più richieste indipendenti.transaction
: esegue le operazioni come più richieste che dipendono l'una dall'altra.history
: inserisce le voci nella cronologia di una risorsa.
Ad esempio, supponiamo che un bundle di transazioni includa la creazione di una risorsa Patient e di una risorsa Observation. Se la richiesta di creazione della risorsa Patient non va a buon fine, la risorsa Observation 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 e ripristina la transazione.
Pacchetti di storia
I bundle della cronologia sono estensioni personalizzate dello standard FHIR che supportano casi d'uso di backup e ripristino, come la sincronizzazione. Puoi utilizzare i pacchetti 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 una singola transazione con un limite
di 100 voci per bundle. Se una versione della risorsa nel bundle history
ha un
timestamp successivo all'ultima versione nel datastore FHIR, l'ultima versione verrà aggiornata di conseguenza. Se il bundle history
viene inserito
correttamente, viene restituita una risposta vuota, altrimenti viene restituito un OperationOutcome
che
descrive l'errore.
Il supporto dei bundle della cronologia non è abilitato per impostazione predefinita. Un amministratore del datastore FHIR deve
impostare enableHistoryModifications
su true
nella
configurazione del datastore FHIR.
Non puoi utilizzare i pacchetti di cronologia se disableResourceVersioning
è
impostato su true
nella configurazione del datastore 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 di 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 il campo request.url
. Se vengono forniti campi, l'ID risorsa fornito deve essere lo stesso. Il timestamp della risorsa viene fornito
con il campo meta.lastUpdated
nella risorsa o il
campo response.lastModified
.
Concessione delle autorizzazioni per l'esecuzione dei bundle
Il ruolo di autorizzazione datasets.fhirStores.fhir.executeBundle
è necessario per
eseguire i bundle. Per concedere questa autorizzazione, utilizza il ruolo
healthcare.fhirResourceReader
. Per i passaggi per concedere questa autorizzazione,
consulta Modifica di una norma.
Per eseguire i bundle della cronologia, è necessario anche il ruolo di autorizzazione datasets.fhirStores.fhir.import
.
L'API Cloud Healthcare controlla le autorizzazioni per ogni operazione nel bundle.
Se disponi dell'autorizzazione healthcare.fhirResources.create
, ma non dell'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 codificato in JSON. Puoi anche includere il bundle nel corpo della richiesta.
Il seguente bundle di esempio crea una risorsa Patient ed elimina un'altra risorsa Patient:
{
"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"
}
}
]
}
Gli esempi riportati di seguito 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 dell'archivio FHIR
- La posizione del file 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 della richiesta con il risultato dell'elaborazione della voce, che potrebbe essere un
mix di risultati positivi e di errore.
Se un bundle di transazioni va a buon fine, 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 l'esito positivo dell'operazione.
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 di cui è stato
eseguito il rollback non vengono segnalate nella risposta.
Il seguente bundle di esempio è l'output dell'esecuzione corretta dell'esempio precedente. La prima voce indica la riuscita 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 dell'archivio FHIR
- La posizione del file 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 della richiesta con il risultato dell'elaborazione della voce, che potrebbe essere un
mix di risultati positivi e di errore.
Se un bundle di transazioni va a buon fine, 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 l'esito positivo dell'operazione.
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 di cui è stato
eseguito il rollback non vengono segnalate nella risposta.
Il seguente bundle di esempio è l'output dell'esecuzione corretta dell'esempio precedente. La prima voce indica la riuscita 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 del esempio di codice.
Python
Un file bundle di esempio è disponibile nel repository GitHub del esempio di codice.
Fai una richiesta PATCH
Puoi utilizzare i bundle FHIR per effettuare richieste PATCH
JSON sulle risorse FHIR.
Per saperne di più, consulta la sezione 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 pacchetto. 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 nel bundle vengono riscritti con l'ID della risorsa corrispondente nello store. Questa operazione va a buon fine 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 risorsa nel formato
RESOURCE_TYPE/RESOURCE_ID
, ad esempioPatient/123
. L'utilizzo di questo formato non è consigliato perchéfullUrl
è un segnaposto locale per il bundle. Ciò può creare confusione se una risorsa nello store ha lo stesso nome, ma la risorsa nel bundle viene risolta con un nome diverso a seguito di un'operazione di creazione.
Il seguente bundle di esempio crea una risorsa Patient e una risorsa Observation che fa riferimento alla risorsa Patient.
{
"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"
}
}
}
]
}
Gli esempi riportati di seguito mostrano come eseguire un bundle.
curl
Un file bundle di esempio è disponibile nel repository GitHub del 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 dell'archivio FHIR
- La posizione del file 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 corretta dell'esempio precedente. La prima voce indica la riuscita 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 del 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 dell'archivio FHIR
- La posizione del file 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 corretta dell'esempio precedente. La prima voce indica la riuscita 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" }