Overzicht van zoeken in Azure API for FHIR
Belangrijk
Azure API for FHIR wordt buiten gebruik gesteld op 30 september 2026. Volg de migratiestrategieën om op die datum over te stappen naar de FHIR-service van Azure Health Data Services. Vanwege de buitengebruikstelling van Azure API for FHIR zijn nieuwe implementaties vanaf 1 april 2025 niet toegestaan. De FHIR-service van Azure Health Data Services is de ontwikkelde versie van Azure API for FHIR waarmee klanten FHIR-, DICOM- en MedTech-services kunnen beheren met integraties in andere Azure-services.
De FHIR-specificatie® (Fast Healthcare Interoperability Resources) definieert de basisprincipes van het zoeken naar FHIR-resources. In dit artikel vindt u enkele belangrijke aspecten van het zoeken naar resources in FHIR. Raadpleeg Zoeken in de HL7 FHIR-specificatie voor meer informatie over het zoeken in FHIR-resources. In dit artikel geven we voorbeelden van zoeksyntaxis. Elke zoekopdracht is tegen uw FHIR-server, die doorgaans een URL van https://<FHIRSERVERNAME>.azurewebsites.net. In de voorbeelden gebruiken we de tijdelijke aanduiding {{FHIR_URL}} voor deze URL.
FHIR-zoekopdrachten kunnen betrekking hebben op een specifiek resourcetype, een opgegeven compartiment of alle resources. De eenvoudigste manier om een zoekopdracht uit te voeren in FHIR is door een GET aanvraag te gebruiken. Als u bijvoorbeeld alle patiënten in de database wilt ophalen, kunt u de volgende aanvraag gebruiken:
GET {{FHIR_URL}}/Patient
U kunt ook zoeken met behulp van POST, wat handig is als de querytekenreeks te lang is. Als u wilt zoeken met behulp POSTvan, kunnen de zoekparameters worden verzonden als hoofdtekst van een formulier. Dit maakt langere, complexere reeks queryparameters mogelijk moeilijk te zien en te begrijpen in een queryreeks.
Als de zoekaanvraag is geslaagd, ontvangt u een FHIR-bundelantwoord met het type searchset. Als de zoekopdracht mislukt, vindt u de foutdetails in de OperationOutcome lijst om te begrijpen waarom de zoekopdracht is mislukt.
In de volgende secties behandelen we de verschillende aspecten van het zoeken. Zodra u deze details hebt bekeken, raadpleegt u onze voorbeeldpagina met voorbeelden van zoekopdrachten die u kunt uitvoeren in de Azure API for FHIR.
Zoekparameters
Wanneer u een zoekopdracht uitvoert, zoekt u op basis van verschillende kenmerken van de resource. Deze kenmerken worden zoekparameters genoemd. Elke resource heeft een set gedefinieerde zoekparameters. De zoekparameter moet worden gedefinieerd en geïndexeerd in de database, zodat u ermee kunt zoeken.
Elke zoekparameter heeft een gedefinieerde gegevenstypen. De ondersteuning voor de verschillende gegevenstypen wordt hieronder beschreven:
Waarschuwing
Er is momenteel een probleem bij het gebruik van _sort in de Azure API for FHIR met gekoppelde zoekopdrachten. Zie opensource-probleem #2344 voor meer informatie. Dit wordt opgelost tijdens een release in december 2021.
| Type zoekparameter | Azure API for FHIR | FHIR-service in Azure Health Data Services | Opmerking |
|---|---|---|---|
| Nummer | Ja | Ja | |
| datum | Ja | Ja | |
| tekenreeks | Ja | Ja | |
| token | Ja | Ja | |
| Verwijzing | Ja | Ja | |
| Samengestelde | Gedeeltelijk | Gedeeltelijk | De lijst met ondersteunde samengestelde typen wordt verderop in dit artikel beschreven |
| quantity | Ja | Ja | |
| uri | Ja | Ja | |
| Speciale | Nee | Nr. |
Algemene zoekparameters
Er zijn algemene zoekparameters die van toepassing zijn op alle resources. Deze worden hieronder vermeld, samen met hun ondersteuning binnen de Azure API for FHIR:
| Algemene zoekparameter | Azure API for FHIR | FHIR-service in Azure Health Data Services | Opmerking |
|---|---|---|---|
| _id | Ja | Ja | |
| _lastUpdated | Ja | Ja | |
| _Tag | Ja | Ja | |
| _Type | Ja | Ja | |
| _Veiligheid | Ja | Ja | |
| _Profiel | Ja | Ja | |
| _Hsa | Gedeeltelijk | Ja | Ondersteuning voor _has bevindt zich in MVP in de Azure API for FHIR en de OSS-versie die wordt ondersteund door Azure Cosmos DB. Meer informatie vindt u in de onderstaande sectie over ketens. |
| _Query | Nee | Nr. | |
| _Filter | Nee | Nr. | |
| _Lijst | Nee | Nr. | |
| _Tekst | Nee | Nr. | |
| _Inhoud | Nee | Nr. |
Resourcespecifieke parameters
Met de Azure API for FHIR ondersteunen we bijna alle resourcespecifieke zoekparameters die zijn gedefinieerd door de FHIR-specificatie. De enige zoekparameters die niet worden ondersteund, zijn beschikbaar in de onderstaande koppelingen:
U kunt ook de huidige ondersteuning voor zoekparameters zien in de FHIR-mogelijkheidsinstructie met de volgende aanvraag:
GET {{FHIR_URL}}/metadata
Als u de zoekparameters in de mogelijkheidsinstructie wilt zien, gaat u naar CapabilityStatement.rest.resource.searchParam de zoekparameters voor elke resource en CapabilityStatement.rest.searchParam zoekt u de zoekparameters voor alle resources.
Notitie
Met de Azure API for FHIR worden geen zoekparameters gemaakt of geïndexeerd die niet zijn gedefinieerd door de FHIR-specificatie. We bieden u echter wel ondersteuning om uw eigen zoekparameters te definiëren.
Samengestelde zoekparameters
Met samengestelde zoekopdrachten kunt u zoeken op waardeparen. Als u bijvoorbeeld zoekt naar een hoogteobservatie waarbij de persoon 60 inch was, moet u ervoor zorgen dat één onderdeel van de observatie de code van hoogte en de waarde van 60 bevat. U zou geen observatie willen krijgen waarbij een gewicht van 60 en hoogte van 48 werd opgeslagen, ook al zou de observatie vermeldingen bevatten die zijn gekwalificeerd voor de waarde 60 en de hoogtecode, alleen in verschillende onderdeelsecties.
Met de Azure API for FHIR ondersteunen we de volgende combinaties van zoekparameters:
- Verwijzing, token
- Token, datum
- Token, getal, getal
- Token, Hoeveelheid
- Token, tekenreeks
- Token, Token
Zie de HL7 Samengestelde zoekparameters voor meer informatie.
Notitie
Samengestelde zoekparameters bieden geen ondersteuning voor modifiers volgens de FHIR-specificatie.
Modifiers en voorvoegsels
Met modifiers kunt u de zoekparameter wijzigen. Hieronder vindt u een overzicht van alle FHIR-modifiers en de ondersteuning in de Azure API for FHIR.
| Modifiers | Azure API for FHIR | FHIR-service in Azure Health Data Services | Opmerking |
|---|---|---|---|
| :Ontbrekende | Ja | Ja | |
| :Exacte | Ja | Ja | |
| :Bevat | Ja | Ja | |
| :Tekst | Ja | Ja | |
| :type (verwijzing) | Ja | Ja | |
| :Niet | Ja | Ja | |
| :below (URI) | Ja | Ja | |
| :above (URI) | Ja | Ja | |
| :in (token) | Nee | Nr. | |
| :below (token) | Nee | Nr. | |
| :above (token) | Nee | Nr. | |
| :not-in (token) | Nee | Nr. |
Voor zoekparameters met een specifieke volgorde (getallen, datums en hoeveelheden) kunt u een voorvoegsel voor de parameter gebruiken om te helpen bij het vinden van overeenkomsten. De Azure API for FHIR ondersteunt alle voorvoegsels.
Parameters voor zoekresultaat
Om de geretourneerde resources te beheren, zijn er zoekresultaatparameters die u in uw zoekopdracht kunt gebruiken. Raadpleeg de HL7-website voor meer informatie over het gebruik van elk van de parameters voor zoekresultaten.
| Parameters voor zoekresultaat | Azure API for FHIR | FHIR-service in Azure Health Data Services | Opmerking |
|---|---|---|---|
| _Elementen | Ja | Ja | |
| _Tellen | Ja | Ja | _count is beperkt tot 1000 resources. Als deze hoger is dan 1000, wordt er slechts 1000 geretourneerd en wordt er een waarschuwing geretourneerd in de bundel. |
| _include | Ja | Ja | Opgenomen items zijn beperkt tot 100. _include op PaaS en OSS in Azure Cosmos DB bevatten geen :iterrate-ondersteuning (#2137). |
| _revinclude | Ja | Ja | Opgenomen items zijn beperkt tot 100. _revinclude op PaaS en OSS in Azure Cosmos DB bevatten geen :iterrate-ondersteuning (#2137). Er is ook een onjuiste statuscode voor een ongeldige aanvraag #1319 |
| _Samenvatting | Ja | Ja | |
| _Totale | Gedeeltelijk | Gedeeltelijk | _total=none en _total=accurate |
| _Sorteren | Gedeeltelijk | Gedeeltelijk | sort=_lastUpdated wordt ondersteund in Azure API for FHIR en de FHIR-service. Voor Azure API for FHIR- en OSS Azure Cosmos DB-databases die na 20 april 2021 zijn gemaakt, wordt sortering ondersteund op voornaam, achternaam, geboortedatum en klinische datum. |
| _contained | Nee | Nr. | |
| _containedType | Nee | Nr. | |
| _Score | Nee | Nr. |
Notitie
De record wordt standaard _sort in oplopende volgorde gesorteerd. U kunt het voorvoegsel '-' gebruiken om in aflopende volgorde te sorteren. Bovendien kunt u met de FHIR-service en de Azure API for FHIR alleen op één veld tegelijk sorteren.
De Azure API for FHIR is standaard ingesteld op lenient handling. Dit betekent dat de server onbekende of niet-ondersteunde parameters negeert. Als u strikte verwerking wilt gebruiken, kunt u de voorkeurskoptekst en set handling=strictgebruiken.
Gekoppelde en omgekeerde zoekopdrachten
Met een gekoppelde zoekopdracht kunt u zoeken met behulp van een zoekparameter voor een resource waarnaar wordt verwezen door een andere resource. Als u bijvoorbeeld wilt zien waar de naam van de patiënt Jane is, gebruikt u:
GET {{FHIR_URL}}/Encounter?subject:Patient.name=Jane
Op dezelfde manier kunt u een omgekeerd geketende zoekopdracht doen. Hiermee kunt u resources ophalen waarbij u criteria opgeeft voor andere resources die ernaar verwijzen. Raadpleeg de pagina met FHIR-zoekvoorbeelden voor meer voorbeelden van geketende en omgekeerde zoekopdrachten.
Notitie
In de Azure API for FHIR en de open source die wordt ondersteund door Azure Cosmos DB, is er een beperking waarbij elke subquery die is vereist voor de gekoppelde en omgekeerde zoekopdrachten slechts 1000 items retourneert. Als er meer dan 1000 items zijn gevonden, wordt het volgende foutbericht weergegeven: 'Subquery's in een ketenexpressie kunnen niet meer dan 1000 resultaten retourneren, gebruik dan een selectiever criterium. Als u een geslaagde query wilt krijgen, moet u specifieker zijn in wat u zoekt.
Paginering
Zoals hierboven vermeld, zijn de resultaten van een zoekopdracht een bundel met pagina's. Standaard retourneert de zoekopdracht 10 resultaten per pagina, maar dit kan worden verhoogd (of verlaagd) door op te _countgeven. Binnen de bundel is er een zelfkoppeling die het huidige resultaat van de zoekopdracht bevat. Als er extra overeenkomsten zijn, bevat de bundel een volgende koppeling. U kunt de volgende koppeling blijven gebruiken om de volgende pagina's met resultaten op te halen. _count is beperkt tot 1000 items of minder.
De volgende koppeling in de bundel heeft een vervolgtokengroottelimiet van 3 KB. U hebt flexibiliteit om de grootte van het vervolgtoken tussen 1 en 3 kB aan te passen met behulp van de header 'x-ms-documentdb-responsecontinuationtokenlimitinkb'.
Op dit moment ondersteunt de Azure API for FHIR alleen de volgende koppeling in bundels en biedt deze geen ondersteuning voor eerste, laatste of vorige koppelingen.
Volgende stappen
Nu u meer hebt geleerd over de basisbeginselen van zoeken, raadpleegt u de pagina met zoekvoorbeelden voor meer informatie over het zoeken met behulp van verschillende zoekparameters, modifiers en andere FHIR-zoekscenario's.
FHIR® is een geregistreerd handelsmerk van HL7 en wordt gebruikt met de machtiging HL7.