Questa pagina spiega come gestire le risorse FHIR mediante l'esecuzione di pacchetti FHIR. ovvero una raccolta di risorse e operazioni FHIR su questi FHIR.
La
ExecuteBundle
implementa l'interazione batch/transazione standard FHIR
(DSTU2,
STU3
e R4) e le operazioni relative alla 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 il modo in cui vengono eseguite le operazioni al suo interno. Sono disponibili i seguenti tipi di pacchetti:
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 pacchetto di transazioni includa la creazione di una risorsa Patient e di una risorsa Observation. Se la richiesta di creazione della risorsa Patient ha esito negativo, la risorsa Observation viene non è stato creato.
Se un'operazione non riesce 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 pacchetto è transaction
, l'API Cloud Healthcare interrompe l'esecuzione delle operazioni e esegue il rollback della transazione.
Cofanetti di film storici
I bundle di record storici sono estensioni personalizzate dello standard FHIR che supportano casi d'uso di backup e ripristino, come la sincronizzazione. Puoi utilizzare i bundle della 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 alla versione più recente nel datastore FHIR, la
versione più recente verrà aggiornata di conseguenza. Se il bundle history
è inserito
viene restituita una risposta vuota, altrimenti viene restituito un valore OperationOutcome
che descrive l'errore.
Il supporto dei pacchetti di cronologia non è abilitato per impostazione predefinita. L'amministratore del datastore FHIR deve
imposta enableHistoryModifications
su true
nella
Configurazione del datastore FHIR.
Non puoi utilizzare i pacchetti di cronologia se disableResourceVersioning
è
impostato su true
per la configurazione del datastore FHIR.
I pacchetti di cronologia vengono forniti nello stesso formato in cui vengono restituiti dal
fhir.history
. Per essere valida, ogni voce del pacchetto richiede un ID risorsa, un timestamp di modifica e un stato. Inoltre, tutte le voci devono avere lo stesso ID risorsa. L'ID risorsa viene fornito con il campo resource.id
o con il campo request.url
. Se vengono forniti campi, l'ID risorsa fornito sarà lo stesso. Il timestamp della risorsa è fornito
con il campo meta.lastUpdated
nella risorsa o
response.lastModified
.
Concessione delle autorizzazioni per l'esecuzione di bundle
È necessario il ruolo di autorizzazione datasets.fhirStores.fhir.executeBundle
per
e l'esecuzione dei bundle. Per concedere questa autorizzazione, utilizza il ruolo
healthcare.fhirResourceReader
. Per la procedura per concedere questa autorizzazione, consulta Modificare un criterio.
Per eseguire i bundle di cronologia, è necessario 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
Autorizzazione healthcare.fhirResources.update
, puoi eseguire solo bundle
contenente operazioni healthcare.fhirResources.create
.
Esecuzione di un bundle
Per eseguire un bundle FHIR, utilizza
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 per i pazienti:
{
"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 quanto segue
informazioni:
- Il nome e la posizione del set di dati padre e del datastore FHIR
- La posizione del file del bundle sulla macchina locale
- Un token di accesso
L'esempio seguente 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 dall'esito delle singole operazioni, dopo aver eseguito un batch
bundle, il server restituisce una rappresentazione codificata in 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
una combinazione di risultati positivi ed errori.
Se un bundle di transazioni ha esito positivo, il server restituisce un file con codifica JSON
rappresentazione di una risorsa Bundle
di tipo transaction-response
contenente
una voce per ciascuna voce della richiesta con l’esito positivo del
operativa.
Se si verifica un errore durante l'esecuzione di un bundle di transazioni, il corpo della risposta
non contengano un bundle. Al contrario, contiene un'immagine OperationOutcome
codificata in JSON
risorsa che descrive il motivo dell'errore. Operazioni riuscite che sono state
i rollback non vengono riportati nella risposta.
Il seguente bundle di esempio è l'output dell'esecuzione corretta dell'esempio precedente. La prima voce indica il buon esito dell'operazione di creazione di un paziente e include l'ID della nuova risorsa. La seconda voce indica il buon esito 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 quanto segue
informazioni:
- Il nome e la posizione del set di dati padre e del datastore FHIR
- La posizione del file del bundle sulla 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 batch
di un bundle, 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 può essere un insieme di risultati di successo ed errore.
Se un bundle di transazioni ha esito positivo, il server restituisce un file con codifica JSON
rappresentazione di una risorsa Bundle
di tipo transaction-response
contenente
una voce per ciascuna voce della richiesta con l’esito positivo del
operativa.
Se si verifica un errore durante l'esecuzione di un bundle di transazioni, il corpo della risposta
non contengano un bundle. Al contrario, contiene un'immagine OperationOutcome
codificata in JSON
risorsa che descrive il motivo dell'errore. Operazioni riuscite che sono state
i rollback non vengono riportati nella risposta.
Il seguente bundle di esempio è l'output dell'esecuzione corretta dell'esempio precedente. La prima voce indica l'esito positivo dell'operazione per creare un Paziente e include l'ID della nuova risorsa. La seconda voce indica il buon esito 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 del bundle di esempio è disponibile nel repository GitHub dell'esempio di codice.
Python
Un file del bundle di esempio è disponibile nel repository GitHub del codice di esempio.
Fai una richiesta PATCH
Puoi utilizzare i bundle FHIR per effettuare richieste JSON PATCH
alle risorse FHIR.
Per ulteriori informazioni, consulta Eseguire una richiesta PATCH
in un bundle FHIR.
Risolvere i riferimenti alle risorse create in un pacchetto
Le risorse in un pacchetto di transazioni possono contenere riferimenti a risorse che non esistono nel sistema di destinazione, ma che vengono create durante l'esecuzione del pacchetto. La
L'API Cloud Healthcare risolve l'associazione tra le risorse utilizzando
il campo entry.fullUrl
. Riferimenti che corrispondono al valore entry.fullUrl
di
le risorse del bundle vengano riscritte nell'ID dell'istanza
risorsa nello store. L'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 della risorsa nel formato
RESOURCE_TYPE/RESOURCE_ID
, ad esempioPatient/123
. L'utilizzo di questo formato non è consigliato perchéfullUrl
è un segnaposto locale del bundle. Questo può creare confusione se una risorsa il datastore ha lo stesso nome, ma la risorsa nel bundle si risolve in 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 del 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 dell'archivio FHIR
- La posizione del file del bundle in Cloud Storage
- Un token di accesso
L'esempio seguente 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 di quanto sopra esempio. La prima voce indica l'esito positivo dell'operazione per creare un Paziente e include l'ID della nuova risorsa. La seconda voce indica il buon esito 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 codice di esempio.
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 del bundle in Cloud Storage
- Un token di accesso
L'esempio seguente 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 l'esito positivo dell'operazione per creare un Paziente e include l'ID della nuova risorsa. La seconda voce indica il buon esito 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" }