Informazioni generali sulla ricerca FHIR
La specifica FHIR® (Fast Healthcare Interoperability Resources) definisce un'API per l'esecuzione di query sulle risorse in un database server FHIR. Questo articolo illustra gli aspetti principali dell'esecuzione di query sui dati in FHIR. Per informazioni complete sull'API di ricerca FHIR, vedere la documentazione di ricerca di HL7 FHIR.
In questo articolo viene illustrata la sintassi di ricerca FHIR nelle chiamate API di esempio con il {{FHIR_URL}} segnaposto per rappresentare l'URL del server FHIR. Se il servizio FHIR si trova in Servizi dati di integrità di Azure, questo URL sarà https://<WORKSPACE-NAME>-<FHIR-SERVICE-NAME>.fhir.azurehealthcareapis.com.
Le ricerche FHIR possono essere eseguite in base a un tipo di risorsa specifico, a un raggruppamento specificato o a tutte le risorse nel database del server FHIR. Il modo più semplice per eseguire una ricerca in FHIR consiste nell'usare una GET richiesta. Ad esempio, se si desidera eseguire il pull di tutte le Patient risorse nel database, è possibile usare la richiesta seguente.
GET {{FHIR_URL}}/Patient
È anche possibile eseguire ricerche usando POST. Per eseguire ricerche usando POST, i parametri di ricerca vengono recapitati nel corpo della richiesta. In questo modo è più semplice inviare query con serie di parametri più lunghe e complesse.
POST Con o GET, se la richiesta di ricerca ha esito positivo, si riceve un bundle FHIR searchset contenente le istanze di risorse restituite dalla ricerca. Se la ricerca non riesce, i dettagli dell'errore verranno visualizzati in una OperationOutcome risposta.
Nelle sezioni seguenti vengono illustrati i vari aspetti dell'esecuzione di query sulle risorse in FHIR. Dopo aver esaminato questi argomenti, fare riferimento alla pagina degli esempi di ricerca FHIR, che include esempi di metodi di ricerca FHIR diversi.
Parametri di ricerca
Quando si esegue una ricerca in FHIR, si cerca nel database le risorse che soddisfano determinati criteri. L'API FHIR specifica un set completo di parametri di ricerca per ottimizzare i criteri di ricerca. Ogni risorsa in FHIR contiene informazioni come set di elementi e i parametri di ricerca funzionano per eseguire query sulle informazioni in questi elementi. In una chiamata API di ricerca FHIR, se viene trovata una corrispondenza positiva tra i parametri di ricerca della richiesta e i valori degli elementi corrispondenti archiviati in un'istanza di risorsa, il server FHIR restituisce un bundle contenente le istanze di risorsa i cui elementi soddisfano i criteri di ricerca.
Per ogni parametro di ricerca, la specifica FHIR definisce il tipo di dati che può essere usato. Il supporto nel servizio FHIR per i vari tipi di dati è descritto di seguito.
| Tipo di parametro di ricerca | Servizio FHIR in Servizi dati di integrità di Azure | API di Azure per FHIR | Commento |
|---|---|---|---|
| number | Sì | Sì | |
| data | Sì | Sì | |
| string | Sì | Sì | |
| token | Sì | Sì | |
| reference | Sì | Sì | |
| composito | Parziale | Parziale | L'elenco dei tipi compositi supportati è riportato in questo articolo. |
| quantity | Sì | Sì | |
| uri | Sì | Sì | |
| special | No | No |
Parametri di ricerca comuni
Esistono parametri di ricerca comuni che si applicano a tutte le risorse in FHIR. Questi sono elencati di seguito, insieme al loro supporto nel servizio FHIR.
| Parametro di ricerca comune | Servizio FHIR in Servizi dati di integrità di Azure | API di Azure per FHIR | Commento |
|---|---|---|---|
_id |
Sì | Sì | |
_lastUpdated |
Sì | Sì | |
_tag |
Sì | Sì | |
_type |
Sì | Sì | |
_security |
Sì | Sì | |
_profile |
Sì | Sì | |
_has |
Sì | Sì | |
_query |
No | No | |
_filter |
No | No | |
_list |
No | No | |
_text |
No | No | |
_content |
No | No |
Parametri specifici delle risorse
Il servizio FHIR in Azure Health Data Services supporta quasi tutti i parametri di ricerca specifici delle risorse definiti nella specifica FHIR. I parametri di ricerca non supportati sono elencati nei collegamenti seguenti:
È anche possibile visualizzare il supporto corrente per i parametri di ricerca nell'istruzione della funzionalità FHIR con la richiesta seguente:
GET {{FHIR_URL}}/metadata
Per visualizzare i parametri di ricerca supportati nell'istruzione capability, passare a CapabilityStatement.rest.resource.searchParam per i parametri di ricerca specifici della risorsa e CapabilityStatement.rest.searchParam per i parametri di ricerca applicabili a tutte le risorse.
Nota
Il servizio FHIR in Azure Health Data Services non indicizza automaticamente i parametri di ricerca non definiti nella specifica FHIR di base. Il servizio FHIR supporta i parametri di ricerca personalizzati.
Parametri di ricerca compositi
Le ricerche composite in FHIR consentono di eseguire ricerche in coppie di elementi come unità connesse logicamente. Ad esempio, se si cercavano osservazioni in cui l'altezza del paziente era superiore a 60 pollici, è consigliabile assicurarsi che una singola proprietà dell'osservazione contenga il codice di altezza e un valore maggiore di 60 pollici (il valore dovrebbe riguardare solo l'altezza). Ad esempio, non si vuole una corrispondenza positiva su un'osservazione con il codice di altezza e un codice di lunghezza arm superiore a 60 pollici. I parametri di ricerca compositi impediscono questo problema eseguendo una ricerca su coppie pre-specificate di elementi i cui valori devono soddisfare entrambi i criteri di ricerca per verificare una corrispondenza positiva.
Il servizio FHIR in Azure Health Data Services supporta le associazioni di tipi di parametro di ricerca seguenti per le ricerche composite.
- Riferimento, Token
- Token, Data
- Token, Number, Number
- Token, Quantità
- Token, String
- Token, Token
Per altre informazioni, vedere la documentazione relativa ai parametri di ricerca compositi HL7.
Nota
I parametri di ricerca compositi non supportano i modificatori, in base alla specifica FHIR.
Modificatori e prefissi
I modificatori consentono di qualificare i parametri di ricerca con condizioni aggiuntive. Di seguito è riportata una tabella dei modificatori FHIR e del relativo supporto nel servizio FHIR.
| Modificatori | Servizio FHIR in Servizi dati di integrità di Azure | API di Azure per FHIR | Commento |
|---|---|---|---|
:missing |
Sì | Sì | |
:exact |
Sì | Sì | |
:contains |
Sì | Sì | |
:text |
Sì | Sì | |
:type (riferimento) |
Sì | Sì | |
:not |
Sì | Sì | |
:below (uri) |
Sì | Sì | |
:above (uri) |
Sì | Sì | |
:in (token) |
No | No | |
:below (token) |
No | No | |
:above (token) |
No | No | |
:not-in (token) |
No | No | |
:identifier |
No | No |
Per i parametri di ricerca con un ordine specifico (numeri, date e quantità), è possibile usare un prefisso prima del valore del parametro per perfezionare i criteri di ricerca, ad esempio dove Patient?_lastUpdated=gt2022-08-01 il prefisso gt significa "maggiore di"). Il servizio FHIR in Azure Health Data Services supporta tutti i prefissi definiti nello standard FHIR.
Parametri dei risultati della ricerca
FHIR specifica un set di parametri dei risultati di ricerca che consentono di gestire le informazioni restituite da una ricerca. Per informazioni dettagliate su come usare i parametri dei risultati di ricerca in FHIR, vedere il sito Web HL7 . Di seguito è riportata una tabella dei parametri dei risultati della ricerca FHIR e del relativo supporto nel servizio FHIR.
| Parametri dei risultati della ricerca | Servizio FHIR in Servizi dati di integrità di Azure | API di Azure per FHIR | Commento |
|---|---|---|---|
_elements |
Sì | Sì | |
_count |
Sì | Sì | _count è limitato a 1000 risorse. Se è impostato su un valore superiore a 1000, vengono restituiti solo 1000 e nel bundle verrà incluso un avviso. |
_include |
Sì | Sì | Gli elementi recuperati con _include sono limitati a 100. _include In PaaS e OSS in Azure Cosmos DB non è supportato (#2137).On PaaS and OSS on Azure Cosmos DB doesn't support :iterate (#2137). |
_revinclude |
Sì | Sì | Gli elementi recuperati con _revinclude sono limitati a 100. _revinclude In PaaS e OSS in Azure Cosmos DB non è supportato (#2137).On PaaS and OSS on Azure Cosmos DB doesn't support :iterate (#2137). Esiste anche un codice di stato errato per una richiesta non valida: #1319. |
_summary |
Sì | Sì | |
_total |
Parziale | Parziale | _total=none e _total=accurate |
_sort |
Parziale | Parziale | sort=_lastUpdated è supportato nel servizio FHIR. Per il servizio FHIR e i server FHIR del database SQL OSS, sono supportati l'ordinamento in base a stringhe e campi dateTime. Per l'API di Azure per FHIR e i database Azure Cosmos DB di Azure Cosmos DB creati dopo il 20 aprile 2021, l'ordinamento è supportato in base al nome, al cognome, alla data di nascita e alla data clinica. |
_contained |
No | No | |
_containedType |
No | No | |
_score |
No | No |
Nota:
- Per impostazione predefinita,
_sortdispone i record in ordine crescente. È anche possibile usare il prefisso-per ordinare in ordine decrescente. Il servizio FHIR consente solo di ordinare in un singolo campo alla volta. - Il servizio FHIR supporta le ricerche con caratteri jolly con revinclude. L'aggiunta di un parametro di query "." in una query revinclude indirizza il servizio FHIR a fare riferimento a tutte le risorse mappate alla risorsa di origine.
Per impostazione predefinita, il servizio FHIR in Servizi dati di integrità di Azure è impostato sulla gestione delle prestazioni. Ciò significa che il server ignora tutti i parametri sconosciuti o non supportati. Se si vuole usare una gestione rigorosa, è possibile includere l'intestazione Prefer e impostare handling=strict.
Ricerca concatenata e concatenata inversa
Una ricerca concatenata consente di eseguire query con destinazione fine per le risorse che hanno un riferimento a un'altra risorsa. Ad esempio, se si desidera trovare incontri in cui il nome del paziente è Jane, usare:
GET {{FHIR_URL}}/Encounter?subject:Patient.name=Jane
. nella richiesta precedente indica il percorso della ricerca concatenato al parametro di destinazione (name in questo caso).
Analogamente, è possibile eseguire una ricerca concatenata inversa con il _has parametro . In questo modo è possibile recuperare le istanze delle risorse specificando criteri per altre risorse che fanno riferimento alle risorse di interesse. Per esempi di ricerca concatenati e concatenati inversa, vedere la pagina degli esempi di ricerca FHIR.
Impaginazione
Come accennato in precedenza, i risultati di una ricerca FHIR sono disponibili in formato impaginato in un collegamento fornito nel searchset bundle. Per impostazione predefinita, il servizio FHIR visualizza 10 risultati di ricerca per pagina, ma può essere aumentato (o ridotto) impostando il _count parametro . Se sono presenti più corrispondenze che adattarsi a una pagina, il bundle include un next collegamento. Il recupero ripetuto dal next collegamento restituisce le pagine successive dei risultati. Si noti che il valore del _count parametro non può superare 1000.
Attualmente, il servizio FHIR in Azure Health Data Services supporta solo il next collegamento e non supporta firsti collegamenti , lasto previous nei bundle restituiti da una ricerca.
Passaggi successivi
Dopo aver appreso le nozioni di base della ricerca FHIR, vedere la pagina degli esempi di ricerca per informazioni dettagliate su come eseguire ricerche usando parametri di ricerca, modificatori e altri metodi di ricerca FHIR.
Nota
FHIR® è un marchio registrato di HL7 ed è usato con l'autorizzazione di HL7.