Übersicht über die Suche in 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 der Fast Healthcare Interoperability Resources (FHIR®) definiert die Grundlagen der Suche nach FHIR-Ressourcen. Dieser Artikel führt Sie durch einige wichtige Aspekte der 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 finden Sie Beispiele für die Suchsyntax. Jede Suche richtet sich an Ihren FHIR-Server, der in der Regel über eine URL von https://<FHIRSERVERNAME>.azurewebsites.net. 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 abrufen möchten, können Sie die folgende Anforderung verwenden.
GET {{FHIR_URL}}/Patient
Sie können auch mithilfe von POSTSuchvorgängen suchen, was nützlich ist, wenn die Abfragezeichenfolge 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 Suchanforderung erfolgreich ist, erhalten Sie eine FHIR-Paketantwort mit dem Typ searchset. Wenn die Suche fehlschlägt, finden Sie die Fehlerdetails in der OperationOutcome Liste, um zu verstehen, warum die Suche fehlgeschlagen ist.
In den folgenden Abschnitten behandeln wir die verschiedenen Aspekte der Suche. 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
Suchvorgänge basieren auf verschiedenen Attributen 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. In der folgenden Tabelle wird die Unterstützung für die verschiedenen Datentypen beschrieben.
Warnung
Es gibt derzeit ein Problem bei der Verwendung _sort in der Azure-API für FHIR mit verketteter Suche. Weitere Informationen finden Sie im Open Source-Problem Nr. 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 | |
| date | Ja | Ja | |
| Zeichenfolge | Ja | Ja | |
| token | Ja | Ja | |
| Referenz | Ja | Ja | |
| composite | Teilweise | Partial | Die Liste der unterstützten Verbundtypen wird weiter unten in diesem Artikel beschrieben. |
| Menge | Ja | Ja | |
| uri | Ja | Ja | |
| speziell | No | No |
Allgemeine Suchparameter
Es gibt allgemeine Suchparameter, die für alle Ressourcen gelten. Diese befinden sich in der folgenden Liste sowie deren Unterstützung innerhalb der 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 | Partial | Ja | Unterstützung in _has MVP in der Azure-API für FHIR und der osS-Version, die von Azure Cosmos DB unterstützt wird. Weitere Details finden Sie im folgenden Verkettungsabschnitt. |
| _query | No | No | |
| _filter | No | No | |
| -List | No | No | |
| _text | No | No | |
| _content | No | No |
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, sind in den folgenden Links verfügbar.
Sie können auch die aktuelle Unterstützung für Suchparameter in der FHIR Capability Statement mit der folgenden Anforderung sehen.
GET {{FHIR_URL}}/metadata
Um die Suchparameter in der Funktionsanweisung anzuzeigen, navigieren Sie zu CapabilityStatement.rest.resource.searchParam den Suchparametern für jede Ressource, und CapabilityStatement.rest.searchParam suchen Sie die Suchparameter für alle Ressourcen.
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 Suchparametertyppaarungen.
- 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. Die folgende Tabelle enthält eine Übersicht über alle FHIR-Modifizierer und deren Unterstützung 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) | No | No | |
| :below (Token) | No | No | |
| :above (Token) | No | No | |
| :not-in (Token) | No | No |
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 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 | |
| _zählen | Ja | Ja | _count ist auf 1000 Ressourcen beschränkt. Wenn sie höher als 1000 festgelegt sind, werden nur 1000 zurückgegeben, und eine Warnung wird im Bundle zurückgegeben. |
| _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 | No | No | |
| _containedType | No | No | |
| _score | No | 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, sind die Ergebnisse einer Suche ein seitenseitiges Bündel. Standardmäßig gibt die Suche 10 Ergebnisse pro Seite zurück, dies kann jedoch durch Angabe _counterhö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 1.000 Elemente oder weniger beschränkt.
Der nächste Link im Bundle hat eine Größenbeschränkung für Fortsetzungstoken von 3 KB. Sie haben die Flexibilität, die Größe des Fortsetzungstokens zwischen 1 KB und 3 KB mithilfe von Headern x-ms-documentdb-responsecontinuationtokenlimitinkbzu optimieren.
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 sich nun mit den Grundlagen der Suche beschäftigt haben, finden Sie auf der Suchbeispielseite Details dazu, wie Sie mit verschiedenen Suchparametern, Modifizierern und anderen FHIR-Suchszenarien suchen können.
Hinweis
FHIR® ist eine eingetragene Marke von HL7 und wird mit Genehmigung von HL7 verwendet.