Panoramica della ricerca nell'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 dati di integrità 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 dati di Integrità 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 i concetti fondamentali della ricerca delle risorse FHIR. Questo articolo illustra alcuni aspetti chiave per la ricerca di risorse in FHIR. Per informazioni dettagliate sulla ricerca delle risorse FHIR, vedere Ricerca nella specifica FHIR HL7. In questo articolo verranno forniti esempi di sintassi di ricerca. Ogni ricerca verrà eseguita sul server FHIR, che in genere ha un URL di https://<FHIRSERVERNAME>.azurewebsites.net. Negli esempi si userà il segnaposto {{FHIR_URL}} per questo URL.
Le ricerche FHIR possono essere eseguite in base a un tipo di risorsa specifico, a un raggruppamento specificato o a tutte le risorse. 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 tutti i pazienti nel database, è possibile usare la richiesta seguente:
GET {{FHIR_URL}}/Patient
È anche possibile eseguire ricerche usando POST, utile se la stringa di query è troppo lunga. Per eseguire ricerche tramite POST, i parametri di ricerca possono essere inviati come corpo del modulo. Ciò consente una serie più lunga e complessa di parametri di query che potrebbero essere difficili da visualizzare e comprendere in una stringa di query.
Se la richiesta di ricerca ha esito positivo, si riceverà una risposta bundle FHIR con il tipo searchset. Se la ricerca non riesce, sono disponibili i dettagli dell'errore in OperationOutcome per comprendere il motivo per cui la ricerca non è riuscita.
Nelle sezioni seguenti verranno illustrati i vari aspetti coinvolti nella ricerca. Dopo aver esaminato questi dettagli, fare riferimento alla pagina degli esempi con esempi di ricerche che è possibile eseguire nell'API di Azure per FHIR.
Parametri di ricerca
Quando si esegue una ricerca, si eseguirà una ricerca in base a vari attributi della risorsa. Questi attributi sono denominati parametri di ricerca. Ogni risorsa ha un set di parametri di ricerca definiti. Il parametro di ricerca deve essere definito e indicizzato nel database per eseguire correttamente la ricerca.
Ogni parametro di ricerca ha tipi di dati definiti. Di seguito è descritto il supporto per i vari tipi di dati:
Avviso
Attualmente si verifica un problema quando si usa _sort nell'API di Azure per FHIR con la ricerca concatenata. Per altre informazioni, vedere problema open source n. 2344. Questo problema verrà risolto durante una versione di dicembre 2021.
| Tipo di parametro di ricerca | API di Azure per FHIR | Servizio FHIR in Servizi dati di integrità di Azure | 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 è descritto più avanti 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. Questi sono elencati di seguito, insieme al supporto all'interno dell'API di Azure per FHIR:
| Parametro di ricerca comune | API di Azure per FHIR | Servizio FHIR in Servizi dati di integrità di Azure | Commento |
|---|---|---|---|
| _id | Sì | Sì | |
| _Lastupdated | Sì | Sì | |
| _tag | Sì | Sì | |
| _type | Sì | Sì | |
| _Sicurezza | Sì | Sì | |
| _Profilo | Sì | Sì | |
| _ha | Parziale | Sì | Il supporto per _has è in MVP nell'API di Azure per FHIR e nella versione del sistema operativo supportata da Azure Cosmos DB. Altri dettagli sono inclusi nella sezione concatenamento riportata di seguito. |
| _Query | No | No | |
| _Filtro | No | No | |
| _Elenco | No | No | |
| _Testo | No | No | |
| _Contenuto | No | No |
Parametri specifici delle risorse
Con l'API di Azure per FHIR, sono supportati quasi tutti i parametri di ricerca specifici delle risorse definiti dalla specifica FHIR. Gli unici parametri di ricerca non supportati sono disponibili 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 nell'istruzione capability, passare a CapabilityStatement.rest.resource.searchParam per visualizzare i parametri di ricerca per ogni risorsa e CapabilityStatement.rest.searchParam trovare i parametri di ricerca per tutte le risorse.
Nota
L'API di Azure per FHIR non crea o indicizza automaticamente i parametri di ricerca non definiti dalla specifica FHIR. Tuttavia, viene fornito il supporto per definire i propri parametri di ricerca.
Parametri di ricerca compositi
La ricerca composita consente di cercare coppie di valori. Ad esempio, se si cerca un'osservazione dell'altezza in cui la persona era di 60 pollici, è consigliabile assicurarsi che un singolo componente dell'osservazione contenga il codice di altezza e il valore di 60. Non si vuole ottenere un'osservazione in cui è stato archiviato un peso pari a 60 e altezza pari a 48, anche se l'osservazione avrebbe voci qualificate per il valore 60 e il codice di altezza, solo in sezioni di componenti diverse.
Con l'API di Azure per FHIR, sono supportate le associazioni di tipi di parametro di ricerca seguenti:
- Riferimento, Token
- Token, Data
- Token, Number, Number
- Token, Quantità
- Token, String
- Token, Token
Per altre informazioni, vedere i parametri di ricerca composita HL7.
Nota
I parametri di ricerca compositi non supportano modificatori in base alla specifica FHIR.
Modificatori e prefissi
I modificatori consentono di modificare il parametro di ricerca. Di seguito è riportata una panoramica di tutti i modificatori FHIR e del supporto nell'API di Azure per FHIR.
| Modificatori | API di Azure per FHIR | Servizio FHIR in Servizi dati di integrità di Azure | Commento |
|---|---|---|---|
| :Mancante | Sì | Sì | |
| :Esatta | Sì | Sì | |
| :Contiene | Sì | Sì | |
| text: | Sì | Sì | |
| :type (riferimento) | Sì | Sì | |
| :Non | 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 |
Per i parametri di ricerca con un ordine specifico (numeri, date e quantità), è possibile usare un prefisso nel parametro per facilitare la ricerca di corrispondenze. L'API di Azure per FHIR supporta tutti i prefissi.
Parametri dei risultati della ricerca
Per gestire le risorse restituite, nella ricerca sono disponibili parametri dei risultati della ricerca. Per informazioni dettagliate su come usare ognuno dei parametri dei risultati della ricerca, vedere il sito Web HL7 .
| Parametri dei risultati della ricerca | API di Azure per FHIR | Servizio FHIR in Servizi dati di integrità di Azure | Commento |
|---|---|---|---|
| _Elementi | Sì | Sì | |
| _Conteggio | Sì | Sì | _count è limitato a 1000 risorse. Se è impostato su un valore superiore a 1000, verranno restituiti solo 1000 e verrà restituito un avviso nel bundle. |
| _Includono | Sì | Sì | Gli elementi inclusi sono limitati a 100. _include in PaaS e OSS in Azure Cosmos DB non includono il supporto di :iterate (#2137). |
| _revinclude | Sì | Sì | Gli elementi inclusi sono limitati a 100. _revinclude in PaaS e OSS in Azure Cosmos DB non includono :iterate support (#2137). Esiste anche un codice di stato errato per una richiesta non valida #1319 |
| _Riepilogo | Sì | Sì | |
| _Totale | Parziale | Parziale | _total=none e _total=accurate |
| _Sorta | Parziale | Parziale | sort=_lastUpdated è supportato nell'API di Azure per FHIR e nel servizio FHIR. 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. |
| _Contenuti | No | No | |
| _containedType | No | No | |
| _Punteggio | No | Numero |
Nota
Per impostazione predefinita _sort , il record viene ordinato in ordine crescente. È possibile usare il prefisso '-' per ordinare in ordine decrescente. Inoltre, il servizio FHIR e l'API di Azure per FHIR consentono di ordinare solo in un singolo campo alla volta.
Per impostazione predefinita, l'API di Azure per FHIR è impostata sulla gestione delle autorizzazioni. Ciò significa che il server ignorerà qualsiasi parametro sconosciuto o non supportato. Se si vuole usare una gestione rigorosa, è possibile usare l'intestazione Prefer e impostare handling=strict.
Ricerca concatenata e concatenata inversa
Una ricerca concatenata consente di eseguire ricerche usando un parametro di ricerca in una risorsa a cui fa riferimento 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
Analogamente, è possibile eseguire una ricerca concatenata inversa. In questo modo è possibile ottenere risorse in cui si specificano criteri per altre risorse che vi fanno riferimento. Per altri esempi di ricerca concatenati e concatenati inversa, vedere la pagina degli esempi di ricerca FHIR.
Nota
Nell'API di Azure per FHIR e nell'open source supportato da Azure Cosmos DB, esiste una limitazione in cui ogni sottoquery necessaria per le ricerche concatenati e concatenati inversa restituirà solo 1000 elementi. Se sono presenti più di 1000 elementi, verrà visualizzato il messaggio di errore seguente: "Le sottoquery in un'espressione concatenato non possono restituire più di 1000 risultati, usare criteri più selettivi". Per ottenere una query con esito positivo, è necessario essere più specifici in ciò che si sta cercando.
Impaginazione
Come accennato in precedenza, i risultati di una ricerca saranno un bundle di paging. Per impostazione predefinita, la ricerca restituirà 10 risultati per pagina, ma questa operazione può essere aumentata (o ridotta) specificando _count. All'interno del bundle sarà presente un collegamento automatico che contiene il risultato corrente della ricerca. Se sono presenti corrispondenze aggiuntive, il bundle conterrà un collegamento successivo. È possibile continuare a usare il collegamento successivo per ottenere le pagine successive dei risultati. _count è limitato a 1000 elementi o meno.
Il collegamento successivo nel bundle ha un limite di dimensioni del token di continuazione pari a 3 KB. È possibile modificare le dimensioni del token di continuazione da 1 a 3 KB usando l'intestazione "x-ms-documentdb-responsecontinuationtokenlimitinkb".
Attualmente, l'API di Azure per FHIR supporta solo il collegamento successivo nei bundle e non supporta prima, l'ultima o i collegamenti precedenti.
Passaggi successivi
Dopo aver appreso le nozioni di base della ricerca, vedere la pagina degli esempi di ricerca per informazioni dettagliate su come eseguire ricerche usando parametri di ricerca, modificatori e altri scenari di ricerca FHIR.
FHIR® è un marchio registrato di HL7 e viene usato con l'autorizzazione di HL7.