Übersicht über die Suche in Azure API für FHIR
Wichtig
Die Azure-API für 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 der Azure-API für 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 Kunden FHIR-, DICOM- und MedTech-Dienste mit Integrationen in andere Azure-Dienste verwalten können.
Die Spezifikation der Fast Healthcare Interoperability Resources (FHIR®) definiert die Grundlagen der Suche nach FHIR-Ressourcen. Dieser Artikel führt Sie durch einige wichtige Aspekte für die Suche nach Ressourcen in FHIR. Ausführliche Informationen zur Suche in FHIR-Ressourcen finden Sie unter Suche in der HL7 FHIR-Spezifikation. In diesem Artikel werden wir Beispiele für die Such-Syntax geben. Jede Suche wird über Ihren FHIR-Server ausgeführt, der in der Regel eine URL von https://<FHIRSERVERNAME>.azurewebsites.net aufweist. In den Beispielen verwenden wir den Platzhalter {{FHIR_URL}} für diese URL.
FHIR-Suchvorgänge können nach einem bestimmten Ressourcentyp, einem bestimmten Depot oder nach allen Ressourcen erfolgen. Die einfachste Möglichkeit zum Ausführen einer Suche in FHIR besteht darin, eine GET-Anforderung zu verwenden. Wenn Sie beispielsweise alle Patienten in der Datenbank pullen möchten, könnten Sie die folgende Anforderung verwenden:
GET {{FHIR_URL}}/Patient
Sie können auch mit POST suchen, was nützlich ist, wenn die Abfragezeichenfolge zu lang ist. Für die Suche mit POST können die Suchparameter als Formulartext übermittelt werden. Dies ermöglicht längere, komplexere Reihen von Abfrageparametern, die in einer Abfragezeichenfolge schwer zu sehen und zu verstehen wären.
Wenn die Suchanfrage erfolgreich ist, erhalten Sie eine FHIR-Bundle-Antwort mit dem Typ searchset. Wenn die Suche fehlschlägt, finden Sie die Fehlerdetails unter OperationOutcome, damit Sie verstehen, warum die Suche fehlgeschlagen ist.
In den folgenden Abschnitten werden wir die verschiedenen Aspekte der Suche behandeln. Wenn Sie diese Details überprüft haben, sehen Sie sich unsere Beispielseite an, auf der Sie Beispiele für Suchvorgänge finden, die Sie in der Azure API für FHIR durchführen können.
Suchparameter
Wenn Sie eine Suche durchführen, suchen Sie auf der Grundlage verschiedener Attribute der Ressource. Diese Attribute werden als Suchparameter bezeichnet. Jede Ressource hat eine Reihe von definierten Suchparametern. Der Suchparameter muss in der Datenbank definiert und indiziert sein, damit Sie erfolgreich nach ihm suchen können.
Jeder Suchparameter verfügt über einen definierten Datentyp. Die Unterstützung für die verschiedenen Datentypen wird im Folgenden beschrieben:
Warnung
Derzeit gibt es ein Problem bei der Verwendung von _sort in der Azure API für FHIR mit verketteter Suche. Weitere Informationen finden Sie in der Open-Source-Ausgabe #2344. Dies wird mit der Veröffentlichung im Dezember 2021 behoben sein.
| Suchparametertyp | Azure API for FHIR | FHIR-Dienst in Azure Health Data Services | Kommentar |
|---|---|---|---|
| Zahl | Ja | Ja | |
| Datum | Ja | Ja | |
| Zeichenfolge | Ja | Ja | |
| token | Ja | Ja | |
| reference | Ja | Ja | |
| composite | Teilweise | Partial | Die Liste der unterstützten zusammengesetzten Typen wird weiter unten in diesem Artikel beschrieben. |
| Menge | Ja | Ja | |
| uri | Ja | Ja | |
| speziell | Nein | Nein |
Allgemeine Suchparameter
Es gibt allgemeine Suchparameter, die für alle Ressourcen gelten. Diese sind unten aufgeführt, zusammen mit ihrer Unterstützung durch die Azure API für FHIR:
| Allgemeiner Suchparameter | Azure API for FHIR | FHIR-Dienst in Azure Health Data Services | Kommentar |
|---|---|---|---|
| _id | Ja | Ja | |
| _lastUpdated | Ja | Ja | |
| _tag | Ja | Ja | |
| _type | Ja | Ja | |
| _security | Ja | Ja | |
| _profile | Ja | Ja | |
| _has | Teilweise | Ja | Unterstützung für _has gibt es in MVP in der Azure API für FHIR und der OSS-Version, die von Azure Cosmos DB unterstützt wird. Weitere Einzelheiten finden Sie im Abschnitt über Verkettung weiter unten. |
| _query | Nein | Nein | |
| _filter | Nein | Nein | |
| -List | Nein | Nein | |
| _text | Nein | Nein | |
| _content | Nein | Nein |
Ressourcenspezifische Parameter
Mit der Azure API für FHIR unterstützen wir fast alle ressourcenspezifischen Suchparameter, die in der FHIR-Spezifikation definiert sind. Die einzigen Suchparameter, die wir nicht unterstützen, finden Sie unter den unten stehenden Links:
Sie können auch die aktuelle Unterstützung für Suchparameter in der FHIR-Funktionsbestätigung mit der folgenden Anforderung anzeigen:
GET {{FHIR_URL}}/metadata
Um die Suchparameter in der Funktionsbestätigung einzusehen, gehen Sie zu CapabilityStatement.rest.resource.searchParam, um die Suchparameter für die einzelnen Ressourcen zu erhalten und zu CapabilityStatement.rest.searchParam, um die Suchparameter für alle Ressourcen zu finden.
Hinweis
Die Azure API für FHIR erstellt oder indiziert nicht automatisch Suchparameter, die nicht in der FHIR-Spezifikation definiert sind. Wir unterstützen Sie jedoch, ihre eigenen Suchparameter zu definieren.
Zusammengesetzte Suchparameter
Die zusammengesetzte Suche ermöglicht es Ihnen, nach Wertepaaren zu suchen. Wenn Sie beispielsweise nach einer Beobachtung zur Körpergröße suchen, bei der die Person 60 Zoll groß war, müssen Sie sicherstellen, dass eine einzelne Komponente der Beobachtung den Code für Größe und den Wert 60 enthält. Sie möchten sicher keine Beobachtung erhalten, bei der das Gewicht von 60 und die Größe von 48 abgespeichert wurde, auch wenn die Beobachtung Einträge enthält, die für den Wert 60 und den Code der Größe geeignet sind, nur eben in unterschiedlichen Komponenten-Abschnitten.
Mit der Azure API für FHIR unterstützen wir die folgenden Suchparametertyp-Paarungen:
- Verweis, Token
- Token, Datum
- Token, Zahl, Zahl
- Token, Menge
- Token, Zeichenfolge
- Token, Token
Weitere Informationen finden Sie unter HL7 Zusammengesetzte Suchparameter.
Hinweis
Zusammengesetzte Suchparameter unterstützen keine Modifizierer gemäß der FHIR-Spezifikation.
Modifizierer und Präfixe
Modifiziererermöglichen es Ihnen, die Suchparameter zu ändern. Im Folgenden finden Sie eine Übersicht über alle FHIR-Modifizierer und den Support in der Azure-API für FHIR.
| Modifizierer | Azure API for FHIR | FHIR-Dienst in Azure Health Data Services | Kommentar |
|---|---|---|---|
| :missing | Ja | Ja | |
| :exact | Ja | Ja | |
| :contains | Ja | Ja | |
| :text | Ja | Ja | |
| :type (reference) | Ja | Ja | |
| :not | Ja | Ja | |
| :below (uri) | Ja | Ja | |
| :above (uri) | Ja | Ja | |
| :in (Token) | Nein | Nein | |
| :below (Token) | Nein | Nein | |
| :above (Token) | Nein | Nein | |
| :not-in (Token) | Nein | Nein |
Für Suchparameter, die eine bestimmte Reihenfolge haben (Zahlen, Daten und Mengen), können Sie ein Präfix für den Parameter verwenden, um die Suche nach Übereinstimmungen zu erleichtern. Die Azure API für FHIR unterstützt alle Präfixe.
Suchergebnisparameter
Um die zurückgegebenen Ressourcen zu verwalten, gibt es Suchergebnisparameter, die Sie in Ihrer Suche verwenden können. Einzelheiten zur Verwendung der einzelnen Suchergebnisparameter finden Sie auf der HL7-Website.
| Suchergebnisparameter | Azure API for FHIR | FHIR-Dienst in Azure Health Data Services | Kommentar |
|---|---|---|---|
| _elements | Ja | Ja | |
| _Count | Ja | Ja | _count ist auf 1000 Ressourcen beschränkt. Wenn hierfür ein höherer Wert als 1000 festgelegt ist, wird nur 1000 zurückgegeben, und im Bundle wird eine Warnung ausgegeben. |
| _include | Ja | Ja | Enthaltene Elemente sind auf 100 beschränkt. _include auf PaaS und OSS auf Azure Cosmos DB enthalten keinen :iterate Support (#2137). |
| _revinclude | Ja | Ja | Enthaltene Elemente sind auf 100 beschränkt. _revinclude auf PaaS und OSS auf Azure Cosmos DB enthalten keinen :iterate Support (#2137). Es gibt auch einen fehlerhaften Statuscode für eine ungültige Anforderung, #1319. |
| _summary | Ja | Ja | |
| _total | Teilweise | Partial | _total=none und _total=accurate |
| _sort | Teilweise | Partial | sort=_lastUpdated wird von Azure API für FHIR und dem FHIR-Dienst unterstützt. Für Azure API für FHIR- und Azure Cosmos DB-OSS-Datenbanken, die nach dem 20. April 2021 erstellt wurden, wird das Sortieren nach Vorname, Nachname, Geburtsdatum und klinischem Datum unterstützt. |
| _contained | Nein | Nein | |
| _containedType | Nein | Nein | |
| _score | Nein | Nein |
Hinweis
Standardmäßig sortiert _sort den Datensatz in aufsteigender Reihenfolge. Sie können das Präfix '-' verwenden, um in absteigender Reihenfolge zu sortieren. Außerdem können Sie mit dem FHIR-Dienst und der Azure API für FHIR jeweils nur nach einem einzigen Feld sortieren.
Standardmäßig ist die Azure API für FHIR auf nachsichtige Behandlung eingestellt. Dies bedeutet, dass der Server unbekannte oder nicht unterstützte Parameter ignoriert. Wenn Sie eine strikte Handhabung verwenden möchten, können Sie die Kopfzeile Prefer verwenden und die Option handling=strict festlegen.
Verkettete und umgekehrte Verkettete Suche
Bei einer verketteten Suche können Sie mithilfe eines Suchparameters nach einer Ressource suchen, auf die von einer anderen Ressource verwiesen wird. Wenn Sie beispielsweise Untersuchungen finden möchten, bei denen der Name der Patientin „Jane“ ist, verwenden Sie:
GET {{FHIR_URL}}/Encounter?subject:Patient.name=Jane
Ebenso können Sie eine umgekehrte verkettete Suche durchführen. Dadurch können Sie Ressourcen abrufen, bei denen Sie Kriterien für andere Ressourcen angeben, die auf sie verweisen. Weitere Beispiele für verkettete und umgekehrte verkettete Suchen finden Sie auf der Seite mit FHIR-Suchbeispielen.
Hinweis
In der Azure API für FHIR und der von Azure Cosmos DB unterstützten Open Source gibt es eine Einschränkung, bei der jede Unterabfrage, die für die verkettete und umgekehrt verkettete Suche erforderlich ist, nur 1000 Elemente zurückgibt. Wenn mehr als 1000 Elemente gefunden werden, erhalten Sie die folgende Fehlermeldung: „Unterabfragen in einem verketteten Ausdruck können nicht mehr als 1000 Ergebnisse liefern, bitte verwenden Sie ein gezielteres Kriterium.“ Um eine erfolgreiche Anfrage zu erhalten, müssen Sie genauer beschreiben, wonach Sie suchen.
Paginierung
Wie bereits erwähnt, werden die Ergebnisse einer Suche in Form eines Seiten-Bundles angezeigt. Standardmäßig gibt die Suche 10 Ergebnisse pro Seite zurück. Dies kann jedoch durch Angabe von _count erhöht (oder verringert) werden. Innerhalb des Bundles gibt es einen Self-Link, der das aktuelle Ergebnis der Suche enthält. Wenn es weitere Übereinstimmungen gibt, enthält das Bundle einen weiteren Link. Sie können mit dem nächsten Link fortfahren, um die nachfolgenden Ergebnisseiten zu erhalten. _count ist auf 1000 Elemente oder weniger beschränkt.
Der nächste Link im Bundle hat eine Größenbeschränkung für Fortsetzungstoken von 3 KB. Sie haben flexibilität, die Größe des Fortsetzungstokens zwischen 1 und 3 KB zu optimieren, indem Sie den Header "x-ms-documentdb-responsecontinuationtokenlimitinkb" verwenden.
Derzeit unterstützt die Azure API für FHIR nur den nächsten Link in Bundles, nicht aber den ersten, letzten oder vorherigen Link.
Nächste Schritte
Nachdem Sie nun die Grundlagen der Suche kennengelernt haben, finden Sie auf der Seite mit den Suchbeispielen detaillierte Informationen zur Suche mit verschiedenen Suchparametern, Modifizierern und anderen FHIR-Suchmethoden.
FHIR® ist eine eingetragene Marke von HL7 und wird mit Genehmigung von HL7 verwendet.