Definieren von benutzerdefinierten Suchparametern für die Azure-API für FHIR
Wichtig
Azure API for FHIR wird am 30. September 2026 eingestellt. Folgen Sie den Migrationsstrategien, um bis zu diesem Datum zum Azure Health Data Services-FHIR®-Dienst zu wechseln. Aufgrund der Einstellung von Azure API for FHIR werden neue Bereitstellungen ab dem 1. April 2025 nicht zugelassen. Der Azure Health Data Services-FHIR-Dienst ist die weiterentwickelte Version der Azure-API für FHIR, mit der Kundschaft FHIR-, DICOM- und Medizintechnikdienste mit Integrationen in andere Azure-Dienste verwalten kann.
Die Spezifikation fast Healthcare Interoperability Resources (FHIR®) definiert eine Reihe von Suchparametern für alle Ressourcen und Suchparameter, die für eine Ressource spezifisch sind. Es gibt jedoch Szenarien, in denen Sie möglicherweise nach einem Element in einer Ressource suchen möchten, das nicht als Standardsuchparameter durch die FHIR-Spezifikation 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, um die Verwendung des Suchparameters in der Produktion zu ermöglichen. In diesem Artikel wird beschrieben, wie Sie Suchparameter testen können, bevor Sie den gesamten FHIR-Server neu indizieren.
Neuen Suchparameter erstellen
Zum Erstellen eines neuen Suchparameters erstellen Sie POST die SearchParameter Ressource für die Datenbank. Das folgende Codebeispiel zeigt, wie Sie der Ressource den US Core Race SearchParameter Patient 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 die Datenbank postiert und die Datenbank neu indizieren. Das Anzeigen der SearchParameter Funktionsanweisung ist die einzige Möglichkeit, um zu erkennen, ob ein Suchparameter auf Ihrem FHIR-Server unterstützt wird. Wenn Sie den Suchparameter finden, ihn aber in der Funktionsanweisung nicht sehen können, müssen Sie den Suchparameter trotzdem indizieren. Sie können mehrere Suchparameter postieren, bevor Sie einen Erneutindizierungsvorgang auslösen.
Wichtige Elemente eines SearchParameter Elements umfassen Folgendes.
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 zuvor im US Core Race Search-Parameter gezeigt.
Code: Der im Code gespeicherte Wert ist das, was Sie bei der Suche verwenden. Im vorherigen Beispiel würden Sie suchen, um
GET {FHIR_URL}/Patient?race=<code>alle Patienten eines bestimmten Rennens zu erhalten. Der Code muss für die Ressource eindeutig sein, für die der Suchparameter gilt.base: Beschreibt, auf welche Ressource der Suchparameter angewendet wird. Wenn der Suchparameter auf alle Ressourcen angewendet wird, können Sie verwenden; andernfalls können Sie alle relevanten Ressourcen auflisten
Resource.type: Beschreibt den Datentyp für den Suchparameter. Der Typ ist 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. Beim Beschreiben eines Suchparameters müssen Sie den Ausdruck einschließen, obwohl er von der Spezifikation nicht benötigt wird. Dies liegt daran, dass Sie entweder den Ausdruck oder die xpath-Syntax benötigen, und die Azure-API für FHIR ignoriert die xpath-Syntax.
Testen von Suchparametern
Obwohl Sie die Suchparameter in der Produktion erst verwenden können, wenn Sie einen Neuindexauftrag ausführen, können Sie Ihre Suchparameter testen, bevor Sie die gesamte Datenbank neu indizieren.
Zunächst können Sie den neuen Suchparameter testen, um zu sehen, welche Werte zurückgegeben werden. Durch Ausführen des folgenden Befehls für eine bestimmte Ressourceninstanz (durch Eingabe ihrer ID) erhalten Sie eine Liste von Wertpaaren mit dem Namen des Suchparameters und dem für den jeweiligen Patienten gespeicherten Wert. Dazu gehören alle Suchparameter für die Ressource. Sie können durch die zurückgegebene Liste scrollen, 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
Wenn Sie beispielsweise alle Suchparameter für einen Patienten finden möchten, verwenden Sie Folgendes.
GET https://{{FHIR_URL}}/Patient/{{PATIENT_ID}}/$reindex
Das Ergebnis sieht wie folgt 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 der Suchparameter erwartungsgemäß angezeigt wird, können Sie eine einzelne Ressource neu indizieren, um die Suche mit dem Element zu testen. Zuerst indizieren Sie eine einzelne Ressource:
POST https://{{FHIR_URL}/{{RESOURCE}}/{{RESOURCE_ID}}/$reindex
Wenn Sie diese Ausführen ausführen, werden die Indizes für alle Suchparameter für die spezifische Ressource festgelegt, die Sie für diesen Ressourcentyp definiert haben. Dadurch wird ein Update an den FHIR-Server vorgenommen. Jetzt können Sie den Teilindizesheader durchsuchen und auf "true" festlegen. Dies bedeutet, dass er Ergebnisse zurückgibt, in denen alle Ressourcen, die den Suchparameter indiziert haben, auch wenn nicht alle Ressourcen dieses Typs indiziert wurden.
Wenn Sie unser Beispiel fortsetzen, können Sie einen Patienten indizieren, um das US Core Race SearchParameter wie folgt zu aktivieren.
POST https://{{FHIR_URL}/Patient/{{PATIENT_ID}}/$reindex
Suchen Sie dann nach Patienten, die ein bestimmtes Rennen haben:
GET https://{{FHIR_URL}}/Patient?race=2028-9
x-ms-use-partial-indices: true
Nachdem Sie zufrieden sind, dass der Suchparameter erwartungsgemäß funktioniert, führen Sie den Neuindexauftrag aus, oder planen Sie den Neuindexierungsauftrag, damit die Suchparameter im FHIR-Server für Produktionsanwendungsfälle verwendet werden können.
Aktualisieren eines Suchparameters
Verwenden Sie PUT zum Aktualisieren eines Suchparameters eine neue Version des Suchparameters. Sie müssen das SearchParameter ID Element id des Textkörpers der PUT Anforderung und im PUT Anruf 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 die Liste scrollen, um den benötigten Suchparameter zu finden. Sie können die Suche auch nach Namen einschränken. Im folgenden Beispiel können Sie mithilfe von USCoreRace: GET {{FHIR_URL}}/SearchParameter?name=USCoreRace"Name" nach "Name" 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 ist ein aktualisiertes SearchParameter Und die Versionsinkremente.
Warnung
Achten Sie beim Aktualisieren von SearchParameters, die bereits in Ihrer Datenbank indiziert wurden. Das Ändern des Verhaltens eines vorhandenen SearchParameter-Elements könnte 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
Achten Sie beim Löschen von SearchParameters, die bereits in Ihrer Datenbank indiziert wurden. Das Ändern des Verhaltens eines vorhandenen SearchParameter-Elements könnte 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.
Hinweis
FHIR® ist eine eingetragene Marke von HL7 und wird mit Genehmigung von HL7 verwendet.