Aangepaste zoekparameters definiëren voor Azure API for FHIR
Belangrijk
Azure API for FHIR wordt op 30 september 2026 buiten gebruik gesteld. 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 een set zoekparameters voor alle resources en zoekparameters die specifiek zijn voor een resource. Er zijn echter scenario's waarin u kunt zoeken op basis van een element in een resource die niet is gedefinieerd als een standaardzoekparameter door de FHIR-specificatie. In dit artikel wordt beschreven hoe u uw eigen zoekparameters kunt definiëren die moeten worden gebruikt in de Azure API for FHIR.
Notitie
Telkens wanneer u een zoekparameter maakt, bijwerkt of verwijdert, moet u een herindextaak uitvoeren om de zoekparameter in te schakelen voor gebruik in productie. In dit artikel wordt beschreven hoe u zoekparameters kunt testen voordat u de volledige FHIR-server opnieuw indexeert.
Nieuwe zoekparameter maken
Als u een nieuwe zoekparameter wilt maken, maakt u POST de SearchParameter resource naar de database. In het volgende codevoorbeeld ziet u hoe u de US Core Race SearchParameter toevoegt aan de Patient resource.
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"
}
Notitie
De nieuwe zoekparameter wordt weergegeven in de mogelijkheidsinstructie van de FHIR-server nadat u de zoekparameter post naar de database en de database opnieuw hebt geïndexeert. Het weergeven van de in de mogelijkheidsinstructie SearchParameter is de enige manier om te zien of een zoekparameter wordt ondersteund op uw FHIR-server. Als u de zoekparameter kunt vinden, maar deze niet kunt zien in de mogelijkheidsinstructie, moet u de zoekparameter nog steeds indexeren. U kunt meerdere zoekparameters posten voordat u een herindexbewerking activeert.
Belangrijke elementen van een SearchParameter omvatten het volgende.
URL: Een unieke sleutel om de zoekparameter te beschrijven. Veel organisaties, zoals HL7, gebruiken een standaard-URL-indeling voor de zoekparameters die ze definiëren, zoals eerder weergegeven in de zoekparameter van de US Core-race.
code: De waarde die in code is opgeslagen, is wat u gebruikt bij het zoeken. In het voorgaande voorbeeld zoekt u met
GET {FHIR_URL}/Patient?race=<code>alle patiënten van een specifiek ras. De code moet uniek zijn voor de resource waarvoor de zoekparameter van toepassing is.basis: Beschrijft op welke resource de zoekparameter van toepassing is. Als de zoekparameter van toepassing is op alle resources, kunt u deze gebruiken
Resource. Anders kunt u alle relevante resources weergeven.type: Beschrijft het gegevenstype voor de zoekparameter. Het type wordt beperkt door de ondersteuning voor de Azure API for FHIR. Dit betekent dat u geen zoekparameter van het type Speciaal kunt definiëren of een samengestelde zoekparameter kunt definiëren, tenzij dit een ondersteunde combinatie is.
expressie: Beschrijft hoe u de waarde voor de zoekopdracht berekent. Wanneer u een zoekparameter beschrijft, moet u de expressie opnemen, ook al is deze niet vereist voor de specificatie. Dit komt doordat u de expressie of de xpath-syntaxis nodig hebt en de Azure API for FHIR de xpath-syntaxis negeert.
Zoekparameters testen
Hoewel u de zoekparameters in productie pas kunt gebruiken als u een herindextaak uitvoert, kunt u uw zoekparameters testen voordat u de hele database opnieuw indexeert.
Eerst kunt u de nieuwe zoekparameter testen om te zien welke waarden worden geretourneerd. Door de volgende opdracht uit te voeren op een specifiek resource-exemplaar (door hun id in te voeren), krijgt u een lijst met waardeparen met de naam van de zoekparameter en de waarde die is opgeslagen voor de specifieke patiënt. Dit omvat alle zoekparameters voor de resource. U kunt door de geretourneerde lijst bladeren om de zoekparameter te vinden die u hebt gemaakt. Als u deze opdracht uitvoert, wordt er geen gedrag in uw FHIR-server gewijzigd.
GET https://{{FHIR_URL}}/{{RESOURCE}}/{{RESOUCE_ID}}/$reindex
Als u bijvoorbeeld alle zoekparameters voor een patiënt wilt zoeken, gebruikt u het volgende.
GET https://{{FHIR_URL}}/Patient/{{PATIENT_ID}}/$reindex
Het resultaat ziet er als volgt uit.
{
"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"
},
...
Zodra u ziet dat de zoekparameter wordt weergegeven zoals verwacht, kunt u één resource opnieuw indexeren om het zoeken met het element te testen. Eerst indexeer u één resource opnieuw:
POST https://{{FHIR_URL}/{{RESOURCE}}/{{RESOURCE_ID}}/$reindex
Als u dit uitvoert, worden de indexen ingesteld voor zoekparameters voor de specifieke resource die u voor dat resourcetype hebt gedefinieerd. Hiermee wordt een update naar de FHIR-server uitgevoerd. U kunt nu de header gedeeltelijke indexen doorzoeken en instellen op true, wat betekent dat er resultaten worden geretourneerd waarbij een van de resources waarop de zoekparameter is geïndexeerd, zelfs als niet alle resources van dat type deze hebben geïndexeerd.
Als u verdergaat met ons voorbeeld, kunt u één patiënt indexeren om de US Core Race SearchParameter als volgt in te schakelen.
POST https://{{FHIR_URL}/Patient/{{PATIENT_ID}}/$reindex
Zoek vervolgens naar patiënten met een specifieke ras:
GET https://{{FHIR_URL}}/Patient?race=2028-9
x-ms-use-partial-indices: true
Nadat u tevreden bent dat uw zoekparameter werkt zoals verwacht, voert u de taak opnieuw uit of plant u deze opnieuw, zodat de zoekparameters kunnen worden gebruikt op de FHIR-server voor gebruiksscenario's in productieomgevingen.
Een zoekparameter bijwerken
Als u een zoekparameter wilt bijwerken, gebruikt PUT u om een nieuwe versie van de zoekparameter te maken. U moet het SearchParameter ID element van de id hoofdtekst van de PUT aanvraag en in het PUT gesprek opnemen.
Notitie
Als u de id voor uw zoekparameter niet weet, kunt u ernaar zoeken. Hiermee GET {{FHIR_URL}}/SearchParameter worden alle aangepaste zoekparameters geretourneerd en kunt u door de lijst bladeren om de zoekparameter te vinden die u nodig hebt. U kunt de zoekopdracht ook beperken op naam. In het volgende voorbeeld kunt u zoeken naar een naam met behulp van 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"
}
Het resultaat is bijgewerkt SearchParameter en de versie wordt verhoogd.
Waarschuwing
Wees voorzichtig bij het bijwerken van SearchParameters die al zijn geïndexeerd in uw database. Het wijzigen van het gedrag van een bestaande SearchParameter kan gevolgen hebben voor het verwachte gedrag. U wordt aangeraden een taak voor opnieuw indexeren onmiddellijk uit te voeren.
Een zoekparameter verwijderen
Als u een zoekparameter wilt verwijderen, gebruikt u het volgende.
Delete {{FHIR_URL}}/SearchParameter/{SearchParameter ID}
Waarschuwing
Wees voorzichtig bij het verwijderen van SearchParameters die al zijn geïndexeerd in uw database. Het wijzigen van het gedrag van een bestaande SearchParameter kan gevolgen hebben voor het verwachte gedrag. U wordt aangeraden een taak voor opnieuw indexeren onmiddellijk uit te voeren.
Volgende stappen
In dit artikel hebt u geleerd hoe u een zoekparameter maakt. Hierna leert u hoe u uw FHIR-server opnieuw kunt indexeren.
Notitie
FHIR® is een geregistreerd handelsmerk van HL7 en wordt gebruikt met de machtiging HL7.