Funzionalità dell'API REST FHIR per l'API di Azure per FHIR
In questo articolo verranno illustrate alcune delle sfumature delle interazioni RESTful dell'API di Azure per FHIR.
Creazione/aggiornamento condizionale
L'API di Azure per 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 l'oggetto ETag non corrisponde al previsto ETag, genera il messaggio di errore 412 Precondizione non riuscita.
Eliminazione e eliminazione condizionale
L'API di Azure per FHIR offre due tipi di eliminazione. C'è Delete, che è noto anche come Hard + Soft Delete e Condizional Delete.
Elimina (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 restituiscono un codice di stato HTTP 410. Pertanto, la risorsa non viene più trovata tramite la ricerca. Inoltre, l'API di Azure per FHIR consente di eliminare completamente (inclusa tutta la cronologia) la risorsa. Per eliminare completamente la risorsa, è possibile passare le impostazioni hardDelete dei parametri a true (DELETE {{FHIR_URL}}/{resource}/{id}?hardDelete=true). Se non si passa questo parametro o si imposta hardDelete su false, le versioni storiche della risorsa saranno comunque disponibili.
Nota
Se si vuole eliminare solo la cronologia, l'API di Azure per FHIR supporta un'operazione personalizzata denominata $purge-history. Questa operazione consente di eliminare la cronologia di 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 uso 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 tutte le cronologie.
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 corrispondenti ai criteri di ricerca.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&_count=100
Recupero di file eliminati
Se non si usa il parametro di eliminazione complessa, i record nell'API di Azure per FHIR devono comunque esistere. I record sono disponibili eseguendo una ricerca cronologia nella risorsa e cercando l'ultima versione con i dati.
Se l'ID della risorsa eliminata è noto, usare il modello 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 è nota, eseguire una ricerca della 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 oppure usare l'operazione POST per creare una nuova risorsa con le stesse informazioni.
Nota
Non esiste una scadenza basata su tempo per i dati di eliminazione temporanea o cronologia. L'unico modo per rimuovere i dati di cronologia/eliminazione temporanea è costituito da un'eliminazione definitiva o dall'operazione di eliminazione della cronologia.
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 informazioni dettagliate su alcuni esempi, vedere il file REST di patch FHIRPath di esempio e il file REST patch JSON per ogni approccio. Per altre informazioni, leggere la documentazione di HL7 per le operazioni di patch con FHIR.
Nota
Quando si usa PATCH con STU3 e se si richiede un bundle cronologia, la risorsa Bundle.entry.request.method con patch viene mappata a PUT. Questo perché STU3 non contiene una definizione per il PATCH verbo nel set di valori HTTPVerb.
Patch con FHIRPath Patch
Questo metodo di patch è il più potente perché sfrutta FHIRPath per selezionare l'elemento di destinazione. Uno scenario comune usa FHIRPath Patch per aggiornare un elemento in un elenco senza conoscere l'ordine dell'elenco. Ad esempio, se si desidera eliminare le informazioni di telecomunicazione domestico 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')"
}
]
}
]
}
Tutte le operazioni di patch FHIRPath devono avere il application/fhir+json set di intestazioni Content-Type. FHIRPatch Patch supporta operazioni di aggiunta, inserimento, eliminazione, rimozione e spostamento. Le operazioni di patch FHIRPatch possono essere facilmente integrate in bundle. Per altri esempi, vedere il file REST di 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. Patch JSON è più compatta e dispone di un'operazione di test che consente di verificare che una condizione sia true prima di eseguire la patch. Ad esempio, se si vuole impostare un paziente come deceduto solo se non sono già contrassegnati come morti, è 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. Patch JSON 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 perché un bundle supporta solo le risorse FHIR e il payload della patch JSON non è una risorsa FHIR. Per risolvere questo problema, verranno usate 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, visualizzare questo argomento su FHIR Chat Zulip.
Nell'esempio seguente si vuole modificare il sesso sul paziente a femmina. La patch [{"op":"replace","path":"/gender","value":"female"}] JSON è stata eseguita 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 dell'API di Azure per FHIR. Altre informazioni sugli aspetti principali per la ricerca delle risorse in FHIR.
(FHIR®) è un marchio registrato di HL7 e viene usato con l'autorizzazione HL7.