Definizione di parametri di ricerca personalizzati per l'API di Azure per FHIR
La specifica Fast Healthcare Interoperability Resources (FHIR®) definisce un set di parametri di ricerca per tutte le risorse e i parametri di ricerca specifici di una risorsa. Tuttavia, esistono scenari in cui è possibile cercare un elemento in una risorsa che non è definita dalla specifica FHIR come parametro di ricerca standard. Questo articolo descrive come definire i propri parametri di ricerca da usare nell'API di Azure per FHIR.
Nota
Ogni volta che si crea, si aggiorna o si elimina un parametro di ricerca, è necessario eseguire un processo di reindex per consentire l'uso del parametro di ricerca nell'ambiente di produzione. Di seguito verrà descritto come testare i parametri di ricerca prima di reinserire l'intero server FHIR.
Creare un nuovo parametro di ricerca
Per creare un nuovo parametro di ricerca, la POSTSearchParameter risorsa nel database. Nell'esempio di codice riportato di seguito viene illustrato 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 di funzionalità del server FHIR dopo aver pubblicato il parametro di ricerca nel database e reindex il database. La visualizzazione dell'istruzione nella funzionalità è l'unico SearchParameter modo per indicare se un parametro di ricerca è supportato nel server FHIR. Se è possibile trovare il parametro di ricerca cercando il parametro di ricerca, ma non è possibile visualizzarlo nell'istruzione funzionalità, è comunque necessario indicizzare il parametro di ricerca. È possibile POST più parametri di ricerca prima di attivare un'operazione di reindex.
Elementi importanti di un SearchParameteroggetto :
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 della gara us Core.
code: il valore archiviato nel codice è quello che si userà durante la ricerca. Per l'esempio precedente, si cerca con
GET {FHIR_URL}/Patient?race=<code>per ottenere tutti i pazienti di una razza specifica. Il codice deve essere univoco per le risorse a cui si applica il parametro di ricerca.base: descrive quali risorse si applicano ai parametri 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 Speciale o definire un parametro di ricerca composito a meno che non sia una combinazione supportata.
espressione: 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. Questo perché è 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 reindex, esistono alcuni modi per testare i parametri di ricerca prima di reindexing dell'intero database.
Prima di tutto, è possibile testare il nuovo parametro di ricerca per visualizzare i valori restituiti. Eseguendo il comando seguente su un'istanza di risorsa specifica (immettendo il relativo ID), verrà restituito un elenco di coppie di valori con il nome del parametro di ricerca e il valore archiviato per il paziente specifico. In questo modo verranno inclusi tutti i parametri di ricerca per la risorsa ed è possibile scorrere 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:
GET https://{{FHIR_URL}}/Patient/{{PATIENT_ID}}/$reindex
Il risultato avrà l'aspetto 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 reindexare una singola risorsa per testare la ricerca con l'elemento. Prima di tutto si ridexerà una singola risorsa:
POST https://{{FHIR_URL}/{{RESOURCE}}/{{RESOURCE_ID}}/$reindex
In questo modo, imposta gli indici per tutti i parametri di ricerca per la risorsa specifica definita per tale tipo di risorsa. In questo modo viene fatto un aggiornamento al server FHIR. È ora possibile eseguire ricerche e impostare l'intestazione usa indici parziali su true, il che significa che restituirà i risultati in cui una delle risorse ha il parametro di ricerca indicizzato, anche se non tutte le risorse di tale tipo sono indicizzate.
Continuando con il nostro esempio precedente, è possibile indicizzare un paziente per abilitare us Core Race SearchParameter:
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 testato e soddisfatto che il parametro di ricerca funzioni come previsto, eseguire o pianificare il processo di reindex 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 IDid 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 e sarà possibile scorrere il parametro di ricerca 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 sarà aggiornato e la versione verrà incrementata SearchParameter .
Avviso
Prestare attenzione quando si aggiornano i parametri searchParameter già indicizzati nel database. La modifica del comportamento di SearchParameter esistente potrebbe avere effetti sul comportamento previsto. È consigliabile eseguire immediatamente un processo di reindex.
Eliminare un parametro di ricerca
Se è necessario eliminare un parametro di ricerca, usare quanto segue:
Delete {{FHIR_URL}}/SearchParameter/{SearchParameter ID}
Avviso
Prestare attenzione quando si eliminano i parametri Di ricerca già indicizzati nel database. La modifica del comportamento di SearchParameter esistente potrebbe avere effetti sul comportamento previsto. È consigliabile eseguire immediatamente un processo di reindex.
Passaggi successivi
In questo articolo si è appreso come creare un parametro di ricerca. È quindi possibile imparare a reinserire il server FHIR.
FHIR® è un marchio registrato di HL7 e viene usato con l'autorizzazione HL7.