Aangepaste zoekparameters definiëren voor Azure API for FHIR
De FHIR-specificatie® (Fast Healthcare Interoperability Resources) definieert een set zoekparameters voor alle resources en zoekparameters die specifiek zijn voor een of meer resources. Er zijn echter scenario's waarin u mogelijk wilt zoeken op een element in een resource die niet is gedefinieerd door de FHIR-specificatie als een standaardzoekparameter. 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 herindexeringstaak uitvoeren om de zoekparameter in productie te kunnen gebruiken. Hieronder wordt beschreven hoe u zoekparameters kunt testen voordat u de hele FHIR-server opnieuw indexeert.
Nieuwe zoekparameter maken
Als u een nieuwe zoekparameter wilt maken, gebruikt u POST de SearchParameter resource voor de database. In het onderstaande 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 in de database en uw database opnieuw hebt geïndexeert. Het weergeven van de SearchParameter in de mogelijkheidsinstructie is de enige manier om te zien of een zoekparameter wordt ondersteund in uw FHIR-server. Als u de zoekparameter kunt vinden door te zoeken naar de zoekparameter, 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:
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 hierboven wordt weergegeven in de US Core racezoekparameter.
code: de waarde die is opgeslagen in code , is de waarde die u gebruikt bij het zoeken. In het bovenstaande voorbeeld zoekt u met
GET {FHIR_URL}/Patient?race=<code>om alle patiënten van een specifieke race op te halen. De code moet uniek zijn voor de resource(s) waarvoor de zoekparameter van toepassing is.base: beschrijft op welke resource(s) de zoekparameter van toepassing is. Als de zoekparameter van toepassing is op alle resources, kunt u gebruiken
Resource. Anders kunt u alle relevante resources weergeven.type: beschrijft het gegevenstype voor de zoekparameter. Type wordt beperkt door de ondersteuning voor de Azure API for FHIR. Dit betekent dat u geen zoekparameter van het type Speciaal of een samengestelde zoekparameter kunt definiëren, tenzij het een ondersteunde combinatie is.
expression: 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 door de specificatie. Dit komt omdat 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 pas in productie kunt gebruiken als u een herindexeringstaak uitvoert, zijn er een aantal manieren om uw zoekparameters te testen voordat u de hele database opnieuw indexeert.
Eerst kunt u de nieuwe zoekparameter testen om te zien welke waarden worden geretourneerd. Door de onderstaande opdracht uit te voeren voor een specifiek resource-exemplaar (door de 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 en u kunt door schuiven om de zoekparameter te vinden die u hebt gemaakt. Als u deze opdracht uitvoert, wordt het gedrag van uw FHIR-server niet gewijzigd.
GET https://{{FHIR_URL}}/{{RESOURCE}}/{{RESOUCE_ID}}/$reindex
Als u bijvoorbeeld alle zoekparameters voor een patiënt wilt zoeken, gaat u als volgt te werk:
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 gaat u één resource opnieuw indexeren:
POST https://{{FHIR_URL}/{{RESOURCE}}/{{RESOURCE_ID}}/$reindex
Hiermee stelt u de indexen in voor alle zoekparameters voor de specifieke resource die u voor dat resourcetype hebt gedefinieerd. Hiermee wordt de FHIR-server bijgewerkt. U kunt nu de header use partial indices zoeken en instellen op true, wat betekent dat er resultaten worden geretourneerd wanneer de zoekparameter is geïndexeerd voor een van de resources, zelfs als niet alle resources van dat type deze hebben geïndexeerd.
In het bovenstaande voorbeeld kunt u één patiënt indexeren om de US Core Race SearchParameterin te schakelen:
POST https://{{FHIR_URL}/Patient/{{PATIENT_ID}}/$reindex
En zoek vervolgens naar patiënten met een specifiek ras:
GET https://{{FHIR_URL}}/Patient?race=2028-9
x-ms-use-partial-indices: true
Nadat u hebt getest en er zeker van bent dat uw zoekparameter werkt zoals verwacht, voert u de taak voor opnieuw indexeren uit of plant u deze zodat de zoekparameters kunnen worden gebruikt in de FHIR-server voor productiegebruiksscenario's.
Een zoekparameter bijwerken
Als u een zoekparameter wilt bijwerken, gebruikt PUT u om een nieuwe versie van de zoekparameter te maken. U moet de SearchParameter ID opnemen in het id element van de hoofdtekst van de PUT aanvraag en in de PUT aanroep.
Notitie
Als u de id voor uw zoekparameter niet weet, kunt u ernaar zoeken. Als GET {{FHIR_URL}}/SearchParameter u gebruikt, worden alle aangepaste zoekparameters geretourneerd en kunt u door de zoekparameter bladeren om de zoekparameter te vinden die u nodig hebt. U kunt ook de zoekopdracht op naam beperken. In het onderstaande voorbeeld kunt u zoeken naar 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 wordt 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. We raden u aan om onmiddellijk een herindexeringstaak 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. We raden u aan om onmiddellijk een herindexeringstaak uit te voeren.
Volgende stappen
In dit artikel hebt u geleerd hoe u een zoekparameter maakt. Vervolgens leert u hoe u uw FHIR-server opnieuw indexeren.
FHIR® is een gedeponeerd handelsmerk van HL7 en wordt gebruikt met de toestemming van HL7.