Definizione di parametri di ricerca personalizzati per l'API di Azure per FHIR
Importante
L'API di Azure per FHIR verrà ritirata il 30 settembre 2026. Seguire le strategie di migrazione per passare al servizio FHIR® di Servizi per i dati sanitari di Azure entro tale data. A causa del ritiro dell'API di Azure per FHIR, le nuove distribuzioni non saranno consentite a partire dal 1° aprile 2025. Il servizio FHIR di Servizi per i dati sanitari di Azure è la versione evoluta dell'API di Azure per FHIR che consente ai clienti di gestire i servizi FHIR, DICOM e MedTech con integrazioni in altri servizi di Azure.
La specifica FHIR® (Fast Healthcare Interoperability Resources) definisce un set di parametri di ricerca per tutte le risorse e i parametri di ricerca specifici di una risorsa. Esistono tuttavia scenari in cui è possibile cercare un elemento in una risorsa che non è definito come parametro di ricerca standard in base alla specifica FHIR. Questo articolo descrive come definire i propri parametri di ricerca da usare nell'API di Azure per FHIR.
Nota
Ogni volta che si crea, aggiorna o si elimina un parametro di ricerca, è necessario eseguire un processo di reindicizzazione per consentire l'uso del parametro di ricerca nell'ambiente di produzione. Questo articolo descrive come testare i parametri di ricerca prima di reindicizzare l'intero server FHIR.
Creare un nuovo parametro di ricerca
Per creare un nuovo parametro di ricerca, è necessario POST usare la SearchParameter risorsa per il database. L'esempio di codice seguente illustra come aggiungere US Core Race SearchParameter alla Patient risorsa.
POST {{FHIR_URL}}/SearchParameter
{
"resourceType" : "SearchParameter",
"id" : "us-core-race",
"url" : "http://hl7.org/fhir/us/core/SearchParameter/us-core-race",
"version" : "3.1.1",
"name" : "USCoreRace",
"status" : "active",
"date" : "2019-05-21",
"publisher" : "US Realm Steering Committee",
"contact" : [
{
"telecom" : [
{
"system" : "other",
"value" : "http://www.healthit.gov/"
}
]
}
],
"description" : "Returns patients with a race extension matching the specified code.",
"jurisdiction" : [
{
"coding" : [
{
"system" : "urn:iso:std:iso:3166",
"code" : "US",
"display" : "United States of America"
}
]
}
],
"code" : "race",
"base" : [
"Patient"
],
"type" : "token",
"expression" : "Patient.extension.where(url = 'http://hl7.org/fhir/us/core/StructureDefinition/us-core-race').extension.value.code"
}
Nota
Il nuovo parametro di ricerca verrà visualizzato nell'istruzione capability del server FHIR dopo aver POSTato il parametro di ricerca nel database e reindicizzare il database. La visualizzazione di SearchParameter nell'istruzione capability è l'unico modo per indicare se un parametro di ricerca è supportato nel server FHIR. Se è possibile trovare il parametro di ricerca, ma non può essere visualizzato nell'istruzione capability, è comunque necessario indicizzare il parametro di ricerca. È possibile pubblicare più parametri di ricerca prima di attivare un'operazione di reindicizzazione.
Gli elementi importanti di un SearchParameter includono quanto segue.
url: chiave univoca per descrivere il parametro di ricerca. Molte organizzazioni, ad esempio HL7, usano un formato URL standard per i parametri di ricerca definiti, come illustrato in precedenza nel parametro di ricerca di race search us Core.
code: il valore archiviato nel codice è ciò che si usa durante la ricerca. Per l'esempio precedente, è necessario cercare con
GET {FHIR_URL}/Patient?race=<code>per ottenere tutti i pazienti di una razza specifica. Il codice deve essere univoco per la risorsa a cui si applica il parametro di ricerca.base: descrive la risorsa a cui si applica il parametro di ricerca. Se il parametro di ricerca si applica a tutte le risorse, è possibile usare
Resource; in caso contrario, è possibile elencare tutte le risorse pertinenti.type: descrive il tipo di dati per il parametro di ricerca. Il tipo è limitato dal supporto per l'API di Azure per FHIR. Ciò significa che non è possibile definire un parametro di ricerca di tipo Special o definire un parametro di ricerca composito, a meno che non sia una combinazione supportata.
expression: descrive come calcolare il valore per la ricerca. Quando si descrive un parametro di ricerca, è necessario includere l'espressione, anche se non è richiesta dalla specifica. Ciò è dovuto al fatto che è necessaria l'espressione o la sintassi xpath e l'API di Azure per FHIR ignora la sintassi xpath.
Testare i parametri di ricerca
Anche se non è possibile usare i parametri di ricerca nell'ambiente di produzione fino a quando non si esegue un processo di reindicizzazione, è possibile testare i parametri di ricerca prima di reindicizzare l'intero database.
Prima di tutto, è possibile testare il nuovo parametro di ricerca per vedere quali valori vengono restituiti. Eseguendo il comando seguente su un'istanza di risorsa specifica (immettendo il relativo ID), si ottiene un elenco di coppie di valori con il nome del parametro di ricerca e il valore archiviato per il paziente specifico. Sono inclusi tutti i parametri di ricerca per la risorsa. È possibile scorrere l'elenco restituito per trovare il parametro di ricerca creato. L'esecuzione di questo comando non modifica alcun comportamento nel server FHIR.
GET https://{{FHIR_URL}}/{{RESOURCE}}/{{RESOUCE_ID}}/$reindex
Ad esempio, per trovare tutti i parametri di ricerca per un paziente, usare quanto segue.
GET https://{{FHIR_URL}}/Patient/{{PATIENT_ID}}/$reindex
Il risultato è simile al seguente.
{
"resourceType": "Parameters",
"id": "8be24e78-b333-49da-a861-523491c3437a",
"meta": {
"versionId": "1"
},
"parameter": [
{
"name": "deceased",
"valueString": "http://hl7.org/fhir/special-values|false"
},
{
"name": "language",
"valueString": "urn:ietf:bcp:47|en-US"
},
{
"name": "race",
"valueString": "2028-9"
},
...
Dopo aver visualizzato il parametro di ricerca come previsto, è possibile reindicizzare una singola risorsa per testare la ricerca con l'elemento . Prima di tutto, reindicizzare una singola risorsa:
POST https://{{FHIR_URL}/{{RESOURCE}}/{{RESOURCE_ID}}/$reindex
In questo modo vengono impostati gli indici per tutti i parametri di ricerca per la risorsa specifica definita per tale tipo di risorsa. In questo modo si esegue un aggiornamento al server FHIR. È ora possibile cercare e impostare l'intestazione usa indici parziali su true, ovvero restituisce i risultati in cui una qualsiasi delle risorse con il parametro di ricerca indicizzato, anche se non tutte le risorse di quel tipo lo hanno indicizzato.
Continuando con il nostro esempio, è possibile indicizzare un paziente per abilitare us Core Race SearchParameter come indicato di seguito.
POST https://{{FHIR_URL}/Patient/{{PATIENT_ID}}/$reindex
Quindi cercare i pazienti che hanno una razza specifica:
GET https://{{FHIR_URL}}/Patient?race=2028-9
x-ms-use-partial-indices: true
Dopo aver soddisfatto che il parametro di ricerca funzioni come previsto, eseguire o pianificare il processo di reindicizzazione in modo che i parametri di ricerca possano essere usati nel server FHIR per i casi d'uso di produzione.
Aggiornare un parametro di ricerca
Per aggiornare un parametro di ricerca, usare PUT per creare una nuova versione del parametro di ricerca. È necessario includere nell'elemento SearchParameter ID id del corpo della PUT richiesta e nella PUT chiamata.
Nota
Se non si conosce l'ID per il parametro di ricerca, è possibile cercarlo. L'uso GET {{FHIR_URL}}/SearchParameter restituirà tutti i parametri di ricerca personalizzati ed è possibile scorrere l'elenco per trovare il parametro di ricerca necessario. È anche possibile limitare la ricerca in base al nome. Con l'esempio seguente è possibile cercare il nome usando USCoreRace: GET {{FHIR_URL}}/SearchParameter?name=USCoreRace.
PUT {{FHIR_URL}}/SearchParameter/{SearchParameter ID}
{
"resourceType" : "SearchParameter",
"id" : "SearchParameter ID",
"url" : "http://hl7.org/fhir/us/core/SearchParameter/us-core-race",
"version" : "3.1.1",
"name" : "USCoreRace",
"status" : "active",
"date" : "2019-05-21",
"publisher" : "US Realm Steering Committee",
"contact" : [
{
"telecom" : [
{
"system" : "other",
"value" : "http://www.healthit.gov/"
}
]
}
],
"description" : "New Description!",
"jurisdiction" : [
{
"coding" : [
{
"system" : "urn:iso:std:iso:3166",
"code" : "US",
"display" : "United States of America"
}
]
}
],
"code" : "race",
"base" : [
"Patient"
],
"type" : "token",
"expression" : "Patient.extension.where(url = 'http://hl7.org/fhir/us/core/StructureDefinition/us-core-race').extension.value.code"
}
Il risultato è un aggiornamento SearchParameter e l'incremento della versione.
Avviso
Prestare attenzione durante l'aggiornamento di SearchParameters che sono già stati indicizzati nel database. La modifica del comportamento di un oggetto SearchParameter esistente potrebbe avere effetti sul comportamento previsto. È consigliabile eseguire immediatamente un processo di reindicizzazione.
Eliminare un parametro di ricerca
Se è necessario eliminare un parametro di ricerca, usare quanto segue.
Delete {{FHIR_URL}}/SearchParameter/{SearchParameter ID}
Avviso
Prestare attenzione durante l'eliminazione di SearchParameters che sono già stati indicizzati nel database. La modifica del comportamento di un oggetto SearchParameter esistente potrebbe avere effetti sul comportamento previsto. È consigliabile eseguire immediatamente un processo di reindicizzazione.
Passaggi successivi
In questo articolo si è appreso come creare un parametro di ricerca. Successivamente è possibile imparare a reindicizzare il server FHIR.
Nota
FHIR® è un marchio registrato di HL7 ed è usato con l'autorizzazione di HL7.