Definieren von benutzerdefinierten Suchparametern

  • Artikel

Die FHIR-Spezifikation definiert einen Satz von Suchparametern, die für alle Ressourcen gelten. Darüber hinaus definiert FHIR viele Suchparameter, die für bestimmte Ressourcen spezifisch sind. Es gibt jedoch Szenarien, in denen Sie möglicherweise 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 benutzerdefinierten Suchparameter für die Verwendung im FHIR-Dienst in Azure Health Data Services definieren können.

Hinweis

Jedes Mal, wenn Sie einen Suchparameter erstellen, aktualisieren oder löschen, müssen Sie einen Neuindizierungsauftrag ausführen, um den Suchparameter für die Liveproduktion zu aktivieren. Im Folgenden wird beschrieben, wie Sie Suchparameter testen können, bevor Sie die gesamte FHIR-Dienstdatenbank neu indizieren.

Erstellen eines neuen Suchparameters

Um einen neuen Suchparameter zu erstellen, müssen POST Sie eine SearchParameter Ressource für die FHIR-Dienstdatenbank erstellen.

POST {{FHIR_URL}}/SearchParameter

Die folgenden Beispiele veranschaulichen das Erstellen eines neuen benutzerdefinierten Suchparameters.

Erstellen eines neuen Suchparameters pro Definition im Implementierungshandbuch

Das folgende Codebeispiel zeigt, wie Sie dem Ressourcentyp in Ihrer FHIR-Dienstdatenbank den PatientSuchparameter US Core Race hinzufügen.

{
  "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"
}

Erstellen eines neuen Suchparameters für Ressourcenattribute mit Verweistyp

Das Codebeispiel zeigt, wie Sie einen benutzerdefinierten Suchparameter erstellen, um MedicationDispense-Ressourcen basierend auf dem Ort zu durchsuchen, an dem sie ausgegeben wurden. Dies ist ein Beispiel für das Hinzufügen eines benutzerdefinierten Suchparameters für einen Verweistyp.

{
 "resourceType": "SearchParameter",
  "id": "a3c28d46-fd06-49ca-aea7-5f9314ef0497",
  "url": "{{An absolute URI that is used to identify this search parameter}}",
  "version": "1.0",
  "name": "MedicationDispenseLocationSearchParameter",
  "status": "active",
  "description": "Search parameter for MedicationDispense by location",
  "code": "location",
  "base": ["MedicationDispense"],
  "target": ["Location"],
  "type": "reference",
  "expression": "MedicationDispense.location"
}

Hinweis

Der neue Suchparameter wird in der Capability-Anweisung des FHIR-Diensts angezeigt, nachdem Sie POST den Suchparameter für die Datenbank verwendet und Ihre Datenbank neu indiziert haben. Das Anzeigen von SearchParameter in der Capability-Anweisung ist die einzige Möglichkeit, um zu ermitteln, ob ein Suchparameter in Ihrem FHIR-Dienst unterstützt wird. Wenn Sie die SearchParameter in der capability-Anweisung nicht finden können, müssen Sie Ihre Datenbank dennoch neu indizieren, um den Suchparameter zu aktivieren. Sie können POST mehrere Suchparameter vor dem Auslösen eines Neuindizierungsvorgangs verwenden.

Wichtige Elemente einer SearchParameter Ressource:

  • url: Ein eindeutiger Schlüssel zum Beschreiben des Suchparameters. Organisationen wie HL7 verwenden ein Standard-URL-Format für die von ihnen definierten Suchparameter, wie oben im Suchparameter US Core Race gezeigt.

  • code: Der im Codeelement gespeicherte Wert ist der Name, der für den Suchparameter verwendet wird, wenn er in einem API-Aufruf enthalten ist. Im obigen Beispiel mit der Erweiterung "US Core Race" würden Sie mit GET {{FHIR_URL}}/Patient?race=<code><code> dem Wert suchen, der aus dem angegebenen Codierungssystem festgelegt wurde. Dieser Aufruf würde alle Patienten einer bestimmten Rasse abrufen.

  • base: Beschreibt, auf welche Ressourcentypen der Suchparameter angewendet wird. Wenn der Suchparameter für alle Ressourcen gilt, können Sie verwenden Resource. Andernfalls können Sie alle relevanten Ressourcentypen auflisten.

  • target: Beschreibt, mit welchen Ressourcentypen der Suchparameter übereinstimmt.

  • type: Beschreibt den Datentyp für den Suchparameter. Der Typ wird durch die Unterstützung für Datentypen im FHIR-Dienst 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.

  • expression: Beschreibt, wie der Wert für die Suche berechnet wird. Wenn Sie einen Suchparameter beschreiben, müssen Sie den Ausdruck einschließen, obwohl er in der Spezifikation nicht erforderlich ist. Dies liegt daran, dass Sie entweder den Ausdruck oder die xpath-Syntax benötigen und der FHIR-Dienst die xpath-Syntax ignoriert.

Testen neuer Suchparameter

Obwohl Sie die neuen Suchparameter erst in der Produktion verwenden können, wenn Sie einen Neuindizierungsauftrag ausführen, gibt es einige Möglichkeiten, Ihre benutzerdefinierten Suchparameter zu testen, bevor Sie die gesamte Datenbank neu indizieren.

Zunächst können Sie einen neuen Suchparameter testen, um zu sehen, welche Werte zurückgegeben werden. Wenn Sie den folgenden Befehl für eine bestimmte Ressource instance ausführen (indem Sie die Ressourcen-ID angeben), erhalten Sie eine Liste von Wertpaaren mit dem Suchparameternamen und dem im entsprechenden Element gespeicherten Wert zurück. Diese Liste enthält alle Suchparameter für die Ressource. Sie können durch scrollen, um den von Ihnen erstellten Suchparameter zu finden. Wenn Sie diesen Befehl ausführen, ändert sich kein Verhalten in Ihrem FHIR-Dienst.

GET https://{{FHIR_URL}}/{{RESOURCE}}/{{RESOURCE_ID}}/$reindex

So suchen Sie beispielsweise alle Suchparameter für einen Patienten:

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 Ihr Suchparameter erwartungsgemäß angezeigt wird, können Sie eine einzelne Ressource neu indizieren, um die Suche mit Ihrem neuen Suchparameter zu testen. So indizieren Sie eine einzelne Ressource neu:

POST https://{{FHIR_URL}/{{RESOURCE}}/{{RESOURCE_ID}}/$reindex

Durch Ausführen dieses Aufrufs POST werden die Indizes für alle Suchparameter festgelegt, die für die in der Anforderung angegebene Ressource instance definiert sind. Dieser Aufruf nimmt eine Änderung an der FHIR-Dienstdatenbank vor. Jetzt können Sie den x-ms-use-partial-indices Header durchsuchen und auf truefestlegen, wodurch der FHIR-Dienst Ergebnisse für alle Ressourcen zurückgibt, für die der Suchparameter indiziert ist, auch wenn nicht alle Ressourceninstanzen dieses Typs indiziert sind.

In unserem Beispiel können Sie einen Patienten indizieren, um zu aktivieren SearchParameter:

POST {{FHIR_URL}}/Patient/{{PATIENT_ID}}/$reindex

Führen Sie dann eine Testsuche durch.

  1. Für den Patienten nach Rasse:
GET {{FHIR_URL}}/Patient?race=2028-9
x-ms-use-partial-indices: true
  1. Für Standort (Verweistyp):
{{fhirurl}}/MedicationDispense?location=<locationid referenced in MedicationDispense Resource>
x-ms-use-partial-indices: true

Nachdem Sie Ihren neuen Suchparameter getestet und bestätigt haben, dass er wie erwartet funktioniert, führen Sie ihren Neuindizierungsauftrag aus, oder planen Sie den Neuindizierungsauftrag, damit die neuen Suchparameter in der Liveproduktion verwendet werden können.

Informationen zum erneuten Indizieren Ihrer FHIR-Dienstdatenbank finden Sie unter Ausführen eines Neuindizierungsauftrags .

Aktualisieren eines Suchparameters

Um einen Suchparameter zu aktualisieren, verwenden Sie PUT , um eine neue Version des Suchparameters zu erstellen. Sie müssen die Suchparameter-ID in das id Feld im Text der PUT Anforderung sowie die Anforderungszeichenfolge PUT einfügen.

Hinweis

Wenn Sie die ID für Ihren Suchparameter nicht kennen, können Sie mithilfe von GET {{FHIR_URL}}/SearchParameterdanach suchen. Dadurch werden alle benutzerdefinierten sowie Standard-Suchparameter zurückgegeben, und Sie können durch die Liste scrollen, um den benötigten Suchparameter zu finden. Sie können die Suche auch anhand des Namens einschränken. Wie in der folgenden Beispielanforderung gezeigt, lautet USCoreRaceder Name der benutzerdefinierten SearchParameter Ressource instance . Sie können mithilfe GET {{FHIR_URL}}/SearchParameter?name=USCoreRacevon nach dieser SearchParameter Ressource nach dem 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 der obigen Anforderung ist eine aktualisierte SearchParameter Ressource.

Warnung

Seien Sie beim Aktualisieren von Suchparametern vorsichtig. Das Ändern eines vorhandenen Suchparameters 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 beim Löschen von Suchparametern vorsichtig. Das Löschen eines vorhandenen Suchparameters 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 benutzerdefinierten Suchparameter erstellen. Als Nächstes erfahren Sie, wie Sie Ihre FHIR-Dienstdatenbank neu indizieren. Weitere Informationen finden Sie unter

Ausführen eines Auftrags zum Neuindizieren

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