Funzionalità dell'API REST FHIR per il servizio FHIR di Servizi di integrità di Azure
In questo articolo verranno illustrate alcune delle sfumature delle interazioni RESTful del servizio FHIR di Servizi di integrità di Azure (denominato servizio FHIR).
Creazione/aggiornamento condizionale
Il servizio FHIR supporta la creazione, la creazione condizionale, l'aggiornamento e l'aggiornamento condizionale come definito dalla specifica FHIR. Un'intestazione utile in questi scenari è l'intestazione If-Match . L'intestazione If-Match viene usata e convalida la versione da aggiornare prima di eseguire l'aggiornamento. Se non ETag corrisponde all'oggetto previsto ETag, verrà generato il messaggio di errore 412 Precondizione non riuscita.
Eliminazione e eliminazione condizionale
Il servizio FHIR offre due tipi di eliminazione. C'è Delete, che è noto anche come Hard + Soft Delete e Conditional Delete.
Delete (Hard + Soft Delete)
L'eliminazione definita dalla specifica FHIR richiede che dopo l'eliminazione di una risorsa, le letture non specifiche della versione successive di una risorsa restituisce un codice di stato HTTP 410. Pertanto, la risorsa non viene più trovata tramite la ricerca. Inoltre, il servizio FHIR consente di eliminare completamente (inclusa tutta la cronologia) la risorsa. Per eliminare completamente la risorsa, è possibile passare le impostazioni hardDelete di un parametro a true (DELETE {{FHIR_URL}}/{resource}/{id}?hardDelete=true). Se questo parametro non viene passato o impostato su hardDelete false, le versioni storiche della risorsa saranno comunque disponibili.
Nota
Se si vuole eliminare solo la cronologia, il servizio FHIR supporta un'operazione personalizzata denominata $purge-history. Questa operazione consente di eliminare la cronologia da una risorsa.
Eliminazione condizionale
L'eliminazione condizionale consente di passare criteri di ricerca per eliminare una risorsa. Per impostazione predefinita, l'eliminazione condizionale consente di eliminare un elemento alla volta. È anche possibile specificare il _count parametro per eliminare fino a 100 elementi alla volta. Di seguito sono riportati alcuni esempi di utilizzo dell'eliminazione condizionale.
Per eliminare un singolo elemento usando l'eliminazione condizionale, è necessario specificare i criteri di ricerca che restituiscono un singolo elemento.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704
È possibile eseguire la stessa ricerca, ma includere hardDelete=true anche per eliminare tutta la cronologia.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&hardDelete=true
Per eliminare più risorse, includere _count=100 il parametro . Questo parametro eliminerà fino a 100 risorse che soddisfano i criteri di ricerca.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&_count=100
Ripristino dei file eliminati
Se non si usa il parametro hard delete, i record nel servizio FHIR dovrebbero essere ancora presenti. È possibile trovare i record eseguendo una ricerca della cronologia sulla risorsa e cercando l'ultima versione con i dati.
Se l'ID della risorsa eliminata è noto, usare il modello di URL seguente:
<FHIR_URL>/<resource-type>/<resource-id>/_history
ad esempio https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/123456789/_history
Se l'ID della risorsa non è noto, eseguire una ricerca nella cronologia sull'intero tipo di risorsa:
<FHIR_URL>/<resource-type>/_history
ad esempio https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/_history
Dopo aver trovato il record da ripristinare, usare l'operazione PUT per ricreare la risorsa con lo stesso ID o usare l'operazione POST per creare una nuova risorsa con le stesse informazioni.
Nota
Non è prevista alcuna scadenza basata sul tempo per i dati di cronologia/eliminazione temporanea. L'unico modo per rimuovere i dati di cronologia/eliminazione temporanea consiste nell'eliminare definitivamente o nell'operazione di eliminazione della cronologia.
Aggregazioni batch e transazioni
In FHIR i bundle possono essere considerati come un contenitore che contiene più risorse. I bundle batch e transazioni consentono agli utenti di inviare un set di azioni da eseguire su un server in una singola richiesta/risposta HTTP. Le azioni possono essere eseguite in modo indipendente come "batch" o come singola "transazione atomica" in cui l'intero set di modifiche ha esito positivo o negativo come singola entità. È possibile inviare azioni su più risorse dello stesso tipo o di tipi diversi, ad esempio creare, aggiornare o eliminare. Per altre informazioni, visitare i bundle FHIR.
Un'interazione batch o bundle di transazioni con il servizio FHIR viene eseguita con il comando HTTP POST all'URL di base.
POST {{fhir_url}}
{
"resourceType": "Bundle",
"type": "batch",
"entry": [
{
"resource": {
"resourceType": "Patient",
"id": "patient-1",
"name": [
{
"given": ["Alice"],
"family": "Smith"
}
],
"gender": "female",
"birthDate": "1990-05-15"
},
"request": {
"method": "POST",
"url": "Patient"
}
},
{
"resource": {
"resourceType": "Patient",
"id": "patient-2",
"name": [
{
"given": ["Bob"],
"family": "Johnson"
}
],
"gender": "male",
"birthDate": "1985-08-23"
},
"request": {
"method": "POST",
"url": "Patient"
}
}
}
]
}
Nel caso di un batch, ogni voce viene considerata come una singola interazione o operazione. Nel caso di un bundle di transazioni, tutte le interazioni o le operazioni hanno esito positivo o negativo insieme. Per un batch o un bundle di transazioni riuscito, la risposta contiene una voce per ogni voce nella richiesta. Per il bundle di transazioni non riuscito, il servizio FHIR restituisce un singolo OperationOutcome.
Nota
Per i bundle batch non devono esistere interdipendenze tra voci diverse nel bundle FHIR. L'esito positivo o negativo di una voce non deve influire sull'esito positivo o negativo di un'altra voce.
Elaborazione parallela del bundle batch nell'anteprima pubblica
Attualmente i bundle batch e transazioni vengono eseguiti in modo seriale nel servizio FHIR. Per migliorare le prestazioni e la velocità effettiva, si abilita l'elaborazione parallela dei bundle batch nell'anteprima pubblica.
Per usare la funzionalità di elaborazione di aggregazioni batch parallele:
- Impostare il valore "x-bundle-processing-logic" su "parallel".
- Assicurarsi che non siano presenti ID risorsa sovrapposti in esecuzione nelle operazioni DELETE, POST, PUT o PATCH nello stesso bundle.
Importante
L'elaborazione parallela del bundle è attualmente disponibile in anteprima pubblica. Le API e gli SDK di anteprima vengono forniti senza un contratto di servizio. È consigliabile non usarli per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero avere funzionalità limitate. Per altre informazioni, vedere Condizioni supplementari per l'utilizzo per le anteprime di Microsoft Azure
Patch e patch condizionale
Patch è un'operazione RESTful utile quando è necessario aggiornare solo una parte della risorsa FHIR. L'uso di patch consente di specificare gli elementi da aggiornare nella risorsa senza dover aggiornare l'intero record. FHIR definisce tre modi per applicare patch alle risorse: patch JSON, patch XML e patch FHIRPath. Il servizio FHIR supporta sia patch JSON che patch FHIRPath insieme a patch JSON condizionale e patch FHIRPath condizionale (che consente di applicare patch a una risorsa in base a criteri di ricerca anziché a un ID risorsa). Per esaminare alcuni esempi, vedere il file REST patch FHIRPath di esempio e il file REST patch JSON per ogni approccio. Per altri dettagli, leggere la documentazione di HL7 per le operazioni di patch con FHIR.
Nota
Quando si usa PATCH in STU3 e se si richiede un bundle cronologia, viene eseguito il mapping della Bundle.entry.request.method risorsa con patch a PUT. Questo perché STU3 non contiene una definizione per il PATCH verbo nel set di valori HTTPVerb.
Patch con patch FHIRPath
Questo metodo di patch è il più potente in quanto sfrutta FHIRPath per selezionare l'elemento di destinazione. Uno scenario comune consiste nell'usare FHIRPath Patch per aggiornare un elemento in un elenco senza conoscere l'ordine dell'elenco. Ad esempio, se si vogliono eliminare le informazioni di telecomunicazione domestica di un paziente senza conoscere l'indice, è possibile usare l'esempio seguente.
PATCH http://{FHIR-SERVICE-HOST-NAME}/Patient/{PatientID}
Tipo di contenuto: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [
{
"name": "operation",
"part": [
{
"name": "type",
"valueCode": "delete"
},
{
"name": "path",
"valueString": "Patient.telecom.where(use = 'home')"
}
]
}
]
}
Qualsiasi operazione FHIRPath Patch deve avere l'intestazione application/fhir+json Content-Type impostata. FHIRPatch Patch supporta operazioni di aggiunta, inserimento, eliminazione, rimozione e spostamento. Le operazioni patch FHIRPatch possono anche essere facilmente integrate in bundle. Per altri esempi, vedere il file REST patch FHIRPath di esempio.
Patch con patch JSON
Patch JSON nel servizio FHIR è conforme alla specifica ben usata definita dalla Internet Engineering Task Force. Il formato del payload non usa le risorse FHIR e usa invece un documento JSON sfruttando JSON-Pointers per la selezione degli elementi. La patch JSON è più compatta e ha un'operazione di test che consente di verificare che una condizione sia vera prima di eseguire la patch. Ad esempio, se si vuole impostare un paziente come defunto solo se non sono già contrassegnati come defunti, è possibile usare l'esempio seguente.
PATCH http://{FHIR-SERVICE-HOST-NAME}/Patient/{PatientID}
Tipo di contenuto: application/json-patch+json
[
{
"op": "test",
"path": "/deceasedBoolean",
"value": false
},
{
"op": "replace",
"path": "/deceasedBoolean",
"value": true
}
]
Tutte le operazioni di patch JSON devono avere il application/json-patch+json set di intestazioni Content-Type. Json Patch supporta operazioni di aggiunta, rimozione, sostituzione, copia, spostamento e test. Per altri esempi, vedere il file REST patch JSON di esempio.
Patch JSON nei bundle
Per impostazione predefinita, la patch JSON non è supportata nelle risorse bundle. Questo avviene perché un bundle supporta solo le risorse FHIR e il payload della patch JSON non è una risorsa FHIR. Per risolvere questo problema, si useranno le risorse binarie con un tipo di contenuto di "application/json-patch+json" e la codifica base64 del payload JSON all'interno di un bundle. Per informazioni su questa soluzione alternativa, vedere questo argomento in FHIR Chat Zulip.
Nell'esempio seguente si vuole modificare il sesso del paziente in femminile. La patch [{"op":"replace","path":"/gender","value":"female"}] JSON è stata acquisita e codificata in base64.
POST https://{FHIR-SERVICE-HOST-NAME}/
Tipo di contenuto: application/json
{
"resourceType": "Bundle",
"id": "bundle-batch",
"type": "batch",
"entry": [
{
"fullUrl": "Patient/{PatientID}",
"resource": {
"resourceType": "Binary",
"contentType": "application/json-patch+json",
"data": "W3sib3AiOiJyZXBsYWNlIiwicGF0aCI6Ii9nZW5kZXIiLCJ2YWx1ZSI6ImZlbWFsZSJ9XQ=="
},
"request": {
"method": "PATCH",
"url": "Patient/{PatientID}"
}
}
]
}
Passaggi successivi
In questo articolo sono state illustrate alcune delle funzionalità REST del servizio FHIR. Successivamente, è possibile ottenere altre informazioni sugli aspetti chiave per la ricerca delle risorse nel servizio FHIR.
(FHIR®) è un marchio registrato di HL7 e viene usato con l'autorizzazione di HL7.