Aangepaste zoekparameters definiëren

Artikel
03/18/2023

De FHIR-specificatie definieert een set zoekparameters die van toepassing zijn op alle resources. Daarnaast definieert FHIR veel zoekparameters die specifiek zijn voor bepaalde resources. Er zijn echter scenario's waarin u mogelijk wilt zoeken op basis van een element in een resource dat niet door de FHIR-specificatie is gedefinieerd als een standaardzoekparameter. In dit artikel wordt beschreven hoe u uw eigen aangepaste zoekparameters kunt definiëren voor gebruik in de FHIR-service in Azure Health Data Services.

Notitie

Telkens wanneer u een zoekparameter maakt, bijwerkt of verwijdert, moet u een herindexeringstaak uitvoeren om de zoekparameter in te schakelen voor liveproductie. Hieronder wordt beschreven hoe u zoekparameters kunt testen voordat u de volledige FHIR-servicedatabase opnieuw indexeert.

Nieuwe zoekparameter maken

Als u een nieuwe zoekparameter wilt maken, hebt u een SearchParameter resource nodig POST voor de FHIR-servicedatabase.

POST {{FHIR_URL}}/SearchParameter

In de onderstaande voorbeelden ziet u hoe u een nieuwe aangepaste zoekparameter maakt

Nieuwe zoekparameter per definitie maken in de implementatiehandleiding

In het onderstaande codevoorbeeld ziet u hoe u de us Core Race-zoekparameter toevoegt aan het Patient resourcetype in uw FHIR-servicedatabase.

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

Nieuwe zoekparameter maken voor resourcekenmerken met verwijzingstype

In het codevoorbeeld ziet u hoe u een aangepaste zoekparameter maakt om te zoeken naar MedicatieDispense-resources op basis van de locatie waar ze zijn opgegeven. Dit is een voorbeeld van het toevoegen van een aangepaste zoekparameter voor een verwijzingstype.

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

Notitie

De nieuwe zoekparameter wordt weergegeven in de mogelijkheidsinstructie van de FHIR-service nadat u POST de zoekparameter naar de database hebt uitgevoerd en de database opnieuw hebt geïndexeerd. Het weergeven van de SearchParameter in de mogelijkheidsinstructie is de enige manier om te zien of een zoekparameter wordt ondersteund in uw FHIR-service. Als u de SearchParameter niet kunt vinden in de mogelijkheidsinstructie, moet u de database nog steeds opnieuw indexeren om de zoekparameter te activeren. U kunt POST meerdere zoekparameters gebruiken voordat u een herindexbewerking activeert.

Belangrijke elementen van een SearchParameter resource:

url: Een unieke sleutel om de zoekparameter te beschrijven. Organisaties zoals HL7 gebruiken een standaard-URL-indeling voor de zoekparameters die ze definiëren, zoals hierboven wordt weergegeven in de US Core Race-zoekparameter.
code: De waarde die is opgeslagen in het code-element is de naam die wordt gebruikt voor de zoekparameter wanneer deze wordt opgenomen in een API-aanroep. In het bovenstaande voorbeeld met de extensie 'US Core Race' zoekt u met GET {{FHIR_URL}}/Patient?race=<code> waar <code> zich bevindt in de waarde die is ingesteld van het opgegeven coderingssysteem. Met deze oproep zouden alle patiënten van een bepaald ras worden opgehaald.
base: Beschrijft op welke resourcetypen de zoekparameter van toepassing is. Als de zoekparameter van toepassing is op alle resources, kunt u gebruiken Resource. Anders kunt u alle relevante resourcetypen weergeven.
target: Beschrijft met welke resourcetypen de zoekparameter overeenkomt.
type: Beschrijft het gegevenstype voor de zoekparameter. Type wordt beperkt door de ondersteuning voor gegevenstypen in de FHIR-service. Dit betekent dat u geen zoekparameter van het type Speciaal of een samengestelde zoekparameter kunt definiëren, tenzij het een ondersteunde combinatie is.
expression: Beschrijft hoe u de waarde voor de zoekopdracht berekent. Wanneer u een zoekparameter beschrijft, moet u de expressie opnemen, ook al is deze niet vereist door de specificatie. Dit komt omdat u de expressie of de xpath-syntaxis nodig hebt en de FHIR-service de xpath-syntaxis negeert.

Nieuwe zoekparameters testen

Hoewel u de nieuwe zoekparameters pas in productie kunt gebruiken als u een herindexeringstaak uitvoert, zijn er een aantal manieren om uw aangepaste zoekparameters te testen voordat u de hele database opnieuw indexeert.

Eerst kunt u een nieuwe zoekparameter testen om te zien welke waarden worden geretourneerd. Door de onderstaande opdracht uit te voeren voor een specifiek resource-exemplaar (door de resource-id op te geven), krijgt u een lijst met waardeparen terug met de naam van de zoekparameter en de waarde die is opgeslagen in het bijbehorende element. Deze lijst bevat alle zoekparameters voor de resource. U kunt door scrollen om de zoekparameter te vinden die u hebt gemaakt. Als u deze opdracht uitvoert, wordt het gedrag in uw FHIR-service niet gewijzigd.

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

Als u bijvoorbeeld alle zoekparameters voor een patiënt wilt zoeken, gaat u als volgt te werk:

GET https://{{FHIR_URL}}/Patient/{{PATIENT_ID}}/$reindex

Het resultaat ziet er als volgt uit:

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

Zodra u ziet dat uw zoekparameter wordt weergegeven zoals verwacht, kunt u één resource opnieuw indexeren om het zoeken te testen met uw nieuwe zoekparameter. Een enkele resource opnieuw indexeren:

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

Door deze POST aanroep uit te voeren, worden de indexen ingesteld voor alle zoekparameters die zijn gedefinieerd voor het resource-exemplaar dat is opgegeven in de aanvraag. Deze aanroep brengt wel een wijziging aan in de FHIR-servicedatabase. U kunt nu de x-ms-use-partial-indices header zoeken en instellen op true, waardoor de FHIR-service resultaten retourneert voor alle resources waarop de zoekparameter is geïndexeerd, zelfs als niet alle resource-exemplaren van dat type deze hebben geïndexeerd.

Als u verdergaat met ons voorbeeld, kunt u één patiënt indexeren om het volgende in te schakelen SearchParameter:

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

En voer vervolgens een testzoekopdracht uit

Voor de patiënt per ras:

GET {{FHIR_URL}}/Patient?race=2028-9
x-ms-use-partial-indices: true

Voor Locatie (referentietype):

{{fhirurl}}/MedicationDispense?location=<locationid referenced in MedicationDispense Resource>
x-ms-use-partial-indices: true

Nadat u de nieuwe zoekparameter hebt getest en hebt bevestigd dat deze werkt zoals verwacht, voert u de taak voor opnieuw indexeren uit of plant u deze zodat de nieuwe zoekparameter(s) kan worden gebruikt in liveproductie.

Zie Een taak voor opnieuw indexeren uitvoeren voor informatie over het opnieuw indexeren van uw FHIR-servicedatabase.

Een zoekparameter bijwerken

Als u een zoekparameter wilt bijwerken, gebruikt PUT u om een nieuwe versie van de zoekparameter te maken. U moet de zoekparameter-id opnemen in het id veld in de hoofdtekst van de PUT aanvraag, evenals de PUT aanvraagtekenreeks.

Notitie

Als u de id voor uw zoekparameter niet weet, kunt u ernaar zoeken met behulp van GET {{FHIR_URL}}/SearchParameter. Hiermee worden alle aangepaste en standaardzoekparameters geretourneerd en kunt u door de lijst bladeren om de zoekparameter te vinden die u nodig hebt. U kunt ook de zoekopdracht op naam beperken. Zoals weergegeven in de onderstaande voorbeeldaanvraag, is USCoreRacede naam van het aangepaste SearchParameter resource-exemplaar . U kunt deze SearchParameter resource zoeken op naam met behulp van GET {{FHIR_URL}}/SearchParameter?name=USCoreRace.

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

Het resultaat van de bovenstaande aanvraag is een bijgewerkte SearchParameter resource.

Waarschuwing

Wees voorzichtig bij het bijwerken van zoekparameters. Het wijzigen van een bestaande zoekparameter kan gevolgen hebben voor het verwachte gedrag. We raden u aan om onmiddellijk een herindexeringstaak uit te voeren.

Een zoekparameter verwijderen

Als u een zoekparameter wilt verwijderen, gebruikt u het volgende:

DELETE {{FHIR_URL}}/SearchParameter/{{SearchParameter_ID}}

Waarschuwing

Wees voorzichtig bij het verwijderen van zoekparameters. Het verwijderen van een bestaande zoekparameter kan gevolgen hebben voor het verwachte gedrag. We raden u aan om onmiddellijk een herindexeringstaak uit te voeren.

Volgende stappen

In dit artikel hebt u geleerd hoe u een aangepaste zoekparameter maakt. Vervolgens leert u hoe u uw FHIR-servicedatabase opnieuw kunt indexeren. Zie voor meer informatie

Een taak opnieuw indexeren uitvoeren

FHIR® is een gedeponeerd handelsmerk van HL7 en wordt gebruikt met de toestemming van HL7.

Delen via

Aangepaste zoekparameters definiëren

Nieuwe zoekparameter maken

Nieuwe zoekparameter per definitie maken in de implementatiehandleiding

Nieuwe zoekparameter maken voor resourcekenmerken met verwijzingstype

Nieuwe zoekparameters testen

Een zoekparameter bijwerken

Een zoekparameter verwijderen

Volgende stappen

Aanvullende resources