Aangepaste zoekparameters definiëren

Artikel
10/16/2024

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. Mogelijk wilt u echter ook zoeken op basis van een element in een resource die niet is gedefinieerd door de FHIR-specificatie 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 herindextaak uitvoeren om de zoekparameter voor liveproductie in te schakelen. We beschrijven hoe u zoekparameters kunt testen voordat u de volledige FHIR-servicedatabase opnieuw indexeert.

Nieuwe zoekparameter maken

Als u een nieuwe zoekparameter wilt maken, moet u een SearchParameter resource in POST de FHIR-servicedatabase maken.

POST {{FHIR_URL}}/SearchParameter

In de volgende voorbeelden ziet u hoe u een nieuwe aangepaste zoekparameter maakt.

Nieuwe zoekparameter per definitie maken in de implementatiehandleiding

In het volgende codevoorbeeld ziet u hoe u de zoekparameter US Core Race 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 volgende codevoorbeeld ziet u hoe u een aangepaste zoekparameter maakt om resources voor Medicatiedispense te doorzoeken op basis van de locatie waar ze zijn uitgedeeld. 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 indexeert. Het weergeven van de in de mogelijkheidsinstructie SearchParameter is de enige manier om te zien of een zoekparameter wordt ondersteund in uw FHIR-service. Als u de SearchParameter in de mogelijkheidsinstructie niet kunt vinden, 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 zijn:

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 zoekparameter us Core Race.
code: De waarde die is opgeslagen in het code-element is de naam die wordt gebruikt voor de zoekparameter wanneer deze is opgenomen in een API-aanroep. Voor het voorgaande voorbeeld met de extensie 'US Core Race' zoekt u waar GET {{FHIR_URL}}/Patient?race=<code> <code> zich bevindt in de waardeset van het opgegeven coderingssysteem. Deze oproep zou alle patiënten van een bepaald ras ophalen.
base: Beschrijft op welke resourcetypen de zoekparameter van toepassing is. Als de zoekparameter van toepassing is op alle resources, kunt u deze gebruiken Resource. Anders kunt u alle relevante resourcetypen weergeven.
target: Beschrijft aan welke resourcetypen de zoekparameter overeenkomt.
type: Beschrijft het gegevenstype voor de zoekparameter. Het type wordt beperkt door de ondersteuning voor gegevenstypen in de FHIR-service. Dit betekent dat u geen zoekparameter van het type Speciaal kunt definiëren of een samengestelde zoekparameter kunt definiëren, tenzij dit 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 voor de specificatie. Dit komt doordat 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 in productie pas kunt gebruiken als u een herindextaak uitvoert, kunt u uw aangepaste zoekparameters testen voordat u de hele database opnieuw indexeert.

Eerst kunt u een nieuwe zoekparameter testen om te zien welke waarden worden geretourneerd. Door de volgende opdracht uit te voeren voor een specifiek resource-exemplaar (door de resource-id op te geven), krijgt u een lijst met waardeparen 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 schuiven om de zoekparameter te vinden die u hebt gemaakt. Als u deze opdracht uitvoert, wordt er geen gedrag in uw FHIR-service gewijzigd.

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

Als u bijvoorbeeld alle zoekparameters voor een patiënt wilt zoeken:

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 de zoekparameter wordt weergegeven zoals verwacht, kunt u één resource opnieuw indexeren om te testen of u zoekt met de nieuwe zoekparameter. Als u één resource opnieuw wilt indexeren, gebruikt u het volgende.

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

Als u deze POST aanroep uitvoert, worden de indexen ingesteld voor zoekparameters die zijn gedefinieerd voor het resource-exemplaar dat is opgegeven in de aanvraag. Deze aanroep brengt een wijziging aan in de FHIR-servicedatabase. U kunt nu zoeken en de x-ms-use-partial-indices header trueinstellen op, 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 testzoekopdrachten 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 opnieuw uit of plant u deze opnieuw, zodat de nieuwe zoekparameters kunnen worden gebruikt in liveproductie.

Zie Een herindextaak 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 id van de zoekparameter opnemen in het id veld in de hoofdtekst van de PUT aanvraag en 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. U kunt door de lijst bladeren om de zoekparameter te vinden die u nodig hebt. U kunt de zoekopdracht ook beperken op naam. Zoals wordt weergegeven in de volgende voorbeeldaanvraag, is USCoreRacede naam van het aangepaste resource-exemplaarSearchParameter. U kunt zoeken naar deze SearchParameter resource 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. U wordt aangeraden een taak voor opnieuw indexeren onmiddellijk 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. U wordt aangeraden een taak voor opnieuw indexeren onmiddellijk uit te voeren.

Volgende stappen

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

Een herindextaak uitvoeren

Notitie

FHIR® is een geregistreerd handelsmerk van HL7 en wordt gebruikt met de machtiging 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

Feedback

Aanvullende resources