Definieren benutzerdefinierter Suchparameter für Azure API for FHIR
Die FHIR-Spezifikation® (Fast Healthcare Interoperability Resources) definiert einen Satz von Suchparametern für alle Ressourcen und Suchparameter, die für eine Ressource spezifisch sind. Es gibt jedoch Szenarien, in denen Sie nach einem Element in einer Ressource suchen möchten, das nicht durch die FHIR-Spezifikation als Standardsuchparameter definiert ist. In diesem Artikel wird beschrieben, wie Sie Ihre eigenen Suchparameter definieren können, die in der Azure-API für FHIR verwendet werden sollen.
Hinweis
Jedes Mal, wenn Sie einen Suchparameter erstellen, aktualisieren oder löschen, müssen Sie einen Neuindizierungsauftrag ausführen, damit der Suchparameter in der Produktion verwendet werden kann. Im Folgenden wird beschrieben, wie Sie Suchparameter testen können, bevor Sie den gesamten FHIR-Server neu indizieren.
Erstellen eines neuen Suchparameters
Um einen neuen Suchparameter zu erstellen, müssen Sie POST
die SearchParameter
Ressource für die Datenbank verwenden. Das folgende Codebeispiel zeigt, wie Sie der Ressource den US Core Race SearchParameterPatient
hinzufügen.
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"
}
Hinweis
Der neue Suchparameter wird in der Funktionsanweisung des FHIR-Servers angezeigt, nachdem Sie den Suchparameter in der Datenbank postiert und Ihre Datenbank neu indizieren. Das Anzeigen von SearchParameter
in der Funktionsanweisung ist die einzige Möglichkeit, zu ermitteln, ob ein Suchparameter auf Ihrem FHIR-Server unterstützt wird. Wenn Sie den Suchparameter finden können, indem Sie nach dem Suchparameter suchen, ihn aber nicht in der Capability-Anweisung sehen können, müssen Sie den Suchparameter trotzdem indizieren. Sie können mehrere Suchparameter postieren, bevor Sie einen Neuindizierungsvorgang auslösen.
Wichtige Elemente eines SearchParameter
:
url: Ein eindeutiger Schlüssel zur Beschreibung des Suchparameters. Viele Organisationen, z. B. HL7, verwenden ein Standard-URL-Format für die von ihnen definierten Suchparameter, wie oben im US Core Race Search-Parameter gezeigt.
Code: Der im Code gespeicherte Wert wird bei der Suche verwendet. Im obigen Beispiel würden Sie mit
GET {FHIR_URL}/Patient?race=<code>
suchen, um alle Patienten einer bestimmten Rasse zu erhalten. Der Code muss für die Ressource(en) eindeutig sein, für die der Suchparameter gilt.base: Beschreibt, für welche Ressource(en) der Suchparameter gilt. Wenn der Suchparameter für alle Ressourcen gilt, können Sie verwenden
Resource
. Andernfalls können Sie alle relevanten Ressourcen auflisten.type: Beschreibt den Datentyp für den Suchparameter. Der Typ wird durch die Unterstützung der Azure-API für FHIR eingeschränkt. Dies bedeutet, dass Sie keinen Suchparameter vom Typ Special definieren oder einen zusammengesetzten Suchparameter definieren können, es sei denn, es handelt sich um eine unterstützte Kombination.
Ausdruck: Beschreibt, wie der Wert für die Suche berechnet wird. Wenn Sie einen Suchparameter beschreiben, müssen Sie den Ausdruck einschließen, obwohl er für die Spezifikation nicht erforderlich ist. Dies liegt daran, dass Sie entweder den Ausdruck oder die xpath-Syntax benötigen und die Azure-API für FHIR die xpath-Syntax ignoriert.
Testen von Suchparametern
Obwohl Sie die Suchparameter erst in der Produktion verwenden können, wenn Sie einen Neuindizierungsauftrag ausführen, gibt es einige Möglichkeiten, Ihre Suchparameter zu testen, bevor Sie die gesamte Datenbank neu indizieren.
Zunächst können Sie Ihren neuen Suchparameter testen, um zu ermitteln, welche Werte zurückgegeben werden. Wenn Sie den folgenden Befehl für eine bestimmte Ressourceninstanz ausführen (indem Sie deren ID eingeben), erhalten Sie eine Liste von Wertpaaren mit dem Namen des Suchparameters und dem für den jeweiligen Patienten gespeicherten Wert zurück. Dies schließt alle Suchparameter für die Ressource ein, und Sie können einen Bildlauf durchführen, um den von Ihnen erstellten Suchparameter zu finden. Wenn Sie diesen Befehl ausführen, ändert sich kein Verhalten auf Ihrem FHIR-Server.
GET https://{{FHIR_URL}}/{{RESOURCE}}/{{RESOUCE_ID}}/$reindex
So suchen Sie beispielsweise alle Suchparameter für einen Patienten:
GET https://{{FHIR_URL}}/Patient/{{PATIENT_ID}}/$reindex
Das Ergebnis sieht so aus:
{
"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"
},
...
Sobald Sie sehen, dass Ihr Suchparameter erwartungsgemäß angezeigt wird, können Sie eine einzelne Ressource neu indizieren, um die Suche mit dem Element zu testen. Zunächst indizieren Sie eine einzelne Ressource neu:
POST https://{{FHIR_URL}/{{RESOURCE}}/{{RESOURCE_ID}}/$reindex
Legt die Indizes für alle Suchparameter für die spezifische Ressource fest, die Sie für diesen Ressourcentyp definiert haben. Dadurch wird ein Update für den FHIR-Server vorgenommen. Jetzt können Sie den Header "Partielle Indizes verwenden" durchsuchen und auf "true" festlegen. Dies bedeutet, dass ergebnisse zurückgegeben werden, bei denen eine der Ressourcen den Suchparameter indiziert hat, auch wenn nicht alle Ressourcen dieses Typs indiziert sind.
Wenn Sie mit unserem obigen Beispiel fortfahren, können Sie einen Patienten indizieren, um das US Core Race SearchParameter
zu aktivieren:
POST https://{{FHIR_URL}/Patient/{{PATIENT_ID}}/$reindex
Suchen Sie dann nach Patienten, die eine bestimmte Rasse haben:
GET https://{{FHIR_URL}}/Patient?race=2028-9
x-ms-use-partial-indices: true
Nachdem Sie getestet und sich davon überzeugt haben, dass Ihr Suchparameter wie erwartet funktioniert, führen Sie Ihren Neuindizierungsauftrag aus, oder planen Sie sie, damit die Suchparameter auf dem FHIR-Server für Produktionsanwendungsfälle verwendet werden können.
Aktualisieren eines Suchparameters
Verwenden PUT
Sie zum Aktualisieren eines Suchparameters, um eine neue Version des Suchparameters zu erstellen. Sie müssen die SearchParameter ID
in das id
Element des Textkörpers der PUT
Anforderung und in den PUT
Aufruf einschließen.
Hinweis
Wenn Sie die ID für Ihren Suchparameter nicht kennen, können Sie danach suchen. Die Verwendung GET {{FHIR_URL}}/SearchParameter
gibt alle benutzerdefinierten Suchparameter zurück, und Sie können durch den Suchparameter scrollen, um den benötigten Suchparameter zu finden. Sie können die Suche auch nach Name einschränken. Im folgenden Beispiel können Sie mithilfe von USCoreRace: GET {{FHIR_URL}}/SearchParameter?name=USCoreRace
nach namen suchen.
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"
}
Das Ergebnis wird aktualisiert SearchParameter
, und die Version wird inkrementieren.
Warnung
Seien Sie vorsichtig beim Aktualisieren von SearchParameters, die bereits in Ihrer Datenbank indiziert wurden. Das Ändern des Verhaltens eines vorhandenen SearchParameter-Objekts kann Auswirkungen auf das erwartete Verhalten haben. Es wird empfohlen, sofort einen Neuindizierungsauftrag auszuführen.
Löschen eines Suchparameters
Wenn Sie einen Suchparameter löschen müssen, verwenden Sie Folgendes:
Delete {{FHIR_URL}}/SearchParameter/{SearchParameter ID}
Warnung
Seien Sie vorsichtig beim Löschen von SearchParameters, die bereits in Ihrer Datenbank indiziert wurden. Das Ändern des Verhaltens eines vorhandenen SearchParameter-Objekts kann Auswirkungen auf das erwartete Verhalten haben. Es wird empfohlen, sofort einen Neuindizierungsauftrag auszuführen.
Nächste Schritte
In diesem Artikel haben Sie erfahren, wie Sie einen Suchparameter erstellen. Als Nächstes erfahren Sie, wie Sie Ihren FHIR-Server neu indizieren.
FHIR® ist eine eingetragene Marke von HL7 und wird mit Genehmigung von HL7 verwendet.