Definieren benutzerdefinierter Suchparameter für Azure API for FHIR

Artikel
06/01/2023

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 SearchParameterzu 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=USCoreRacenach 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.

Ausführen eines Auftrags zum Neuindizieren

FHIR® ist eine eingetragene Marke von HL7 und wird mit Genehmigung von HL7 verwendet.

Definieren benutzerdefinierter Suchparameter für Azure API for FHIR

Erstellen eines neuen Suchparameters

Testen von Suchparametern

Aktualisieren eines Suchparameters

Löschen eines Suchparameters

Nächste Schritte

Zusätzliche Ressourcen