Definiera anpassade sökparametrar för Azure API för FHIR

Artikel
06/01/2023

FHIR-specifikationen® (Fast Healthcare Interoperability Resources) definierar en uppsättning sökparametrar för alla resurser och sökparametrar som är specifika för en eller flera resurser. Det finns dock scenarier där du kanske vill söka efter ett element i en resurs som inte definieras av FHIR-specifikationen som en standardsökparameter. Den här artikeln beskriver hur du kan definiera dina egna sökparametrar som ska användas i Azure API för FHIR.

Anteckning

Varje gång du skapar, uppdaterar eller tar bort en sökparameter måste du köra ett omindexeringsjobb för att aktivera sökparametern som ska användas i produktion. Nedan beskrivs hur du kan testa sökparametrar innan du indexerar om hela FHIR-servern.

Skapa ny sökparameter

Om du vill skapa en ny sökparameter använder du POSTSearchParameter resursen till databasen. Kodexemplet nedan visar hur du lägger till US Core Race SearchParameter i resursen Patient .

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

Anteckning

Den nya sökparametern visas i FHIR-serverns funktionsuttryck när du har posta sökparametern i databasen och indexera om databasen. SearchParameter Att visa i -funktionssatsen är det enda sättet att se om en sökparameter stöds på din FHIR-server. Om du hittar sökparametern genom att söka efter sökparametern men inte kan se den i funktionsinstrukationen måste du fortfarande indexeras sökparametern. Du kan PUBLICERA flera sökparametrar innan du utlöser en omindexeringsåtgärd.

Viktiga element i en SearchParameter:

url: En unik nyckel för att beskriva sökparametern. Många organisationer, till exempel HL7, använder ett standard-URL-format för de sökparametrar som de definierar, enligt vad som visas ovan i frågeparametern US Core.
code: Värdet som lagras i koden är det du ska använda när du söker. I exemplet ovan skulle du söka med GET {FHIR_URL}/Patient?race=<code> för att hämta alla patienter i en specifik ras. Koden måste vara unik för de resurser som sökparametern gäller för.
base: Beskriver vilka resurser som sökparametern gäller för. Om sökparametern gäller för alla resurser kan du använda Resource. Annars kan du visa en lista över alla relevanta resurser.
typ: Beskriver datatypen för sökparametern. Typen begränsas av stödet för Azure API för FHIR. Det innebär att du inte kan definiera en sökparameter av typen Special eller definiera en sammansatt sökparameter om det inte är en kombination som stöds.
uttryck: Beskriver hur du beräknar värdet för sökningen. När du beskriver en sökparameter måste du inkludera uttrycket, även om det inte krävs av specifikationen. Det beror på att du behöver antingen uttrycket eller xpath-syntaxen och Azure API för FHIR ignorerar xpath-syntaxen.

Testa sökparametrar

Du kan inte använda sökparametrarna i produktion förrän du kör ett omindexeringsjobb, men det finns några sätt att testa sökparametrarna innan du indexerar om hela databasen.

Först kan du testa den nya sökparametern för att se vilka värden som ska returneras. Genom att köra kommandot nedan mot en specifik resursinstans (genom att ange deras ID) får du tillbaka en lista med värdepar med sökparameterns namn och det värde som lagras för den specifika patienten. Detta inkluderar alla sökparametrar för resursen och du kan bläddra igenom för att hitta sökparametern som du skapade. Om du kör det här kommandot ändras inte något beteende på FHIR-servern.

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

Om du till exempel vill hitta alla sökparametrar för en patient:

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

Resultatet ser ut så här:

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

När du ser att sökparametern visas som förväntat kan du indexera om en enskild resurs för att testa sökningen med elementet. Först indexerar du om en enskild resurs:

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

Om du kör detta anger du indexen för alla sökparametrar för den specifika resurs som du definierade för den resurstypen. Detta gör en uppdatering av FHIR-servern. Nu kan du söka efter och ställa in rubriken använd partiella index till true, vilket innebär att den returnerar resultat där någon av resurserna har sökparametern indexerad, även om inte alla resurser av den typen har indexerat den.

Om du fortsätter med vårt exempel ovan kan du indexera en patient för att aktivera US Core Race SearchParameter:

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

Och sök sedan efter patienter som har en specifik ras:

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

När du har testat och är nöjd med att sökparametern fungerar som förväntat kör eller schemalägger du ditt omindexeringsjobb så att sökparametrarna kan användas på FHIR-servern för produktionsanvändningsfall.

Uppdatera en sökparameter

Om du vill uppdatera en sökparameter använder du PUT för att skapa en ny version av sökparametern. Du måste inkludera SearchParameter ID i elementet id i brödtexten i PUT begäran och i anropet PUT .

Anteckning

Om du inte känner till ID:t för sökparametern kan du söka efter den. Om du använder GET {{FHIR_URL}}/SearchParameter returneras alla anpassade sökparametrar och du kan bläddra igenom sökparametern för att hitta den sökparameter du behöver. Du kan också begränsa sökningen efter namn. Med exemplet nedan kan du söka efter namn med hjälp av USCoreRace: 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"
}

Resultatet uppdateras SearchParameter och versionen ökar.

Varning

Var försiktig när du uppdaterar SearchParameters som redan har indexerats i databasen. Om du ändrar en befintlig SearchParameters beteende kan det påverka det förväntade beteendet. Vi rekommenderar att du kör ett omindexera jobb omedelbart.

Ta bort en sökparameter

Om du behöver ta bort en sökparameter använder du följande:

Delete {{FHIR_URL}}/SearchParameter/{SearchParameter ID}

Varning

Var försiktig när du tar bort SearchParameters som redan har indexerats i databasen. Om du ändrar en befintlig SearchParameters beteende kan det påverka det förväntade beteendet. Vi rekommenderar att du kör ett omindexera jobb omedelbart.

Nästa steg

I den här artikeln har du lärt dig hur du skapar en sökparameter. Härnäst kan du lära dig hur du indexerar om FHIR-servern.

Så här kör du ett omindexera jobb

FHIR® är ett registrerat varumärke som tillhör HL7 och används med tillstånd av HL7.

Definiera anpassade sökparametrar för Azure API för FHIR

Skapa ny sökparameter

Testa sökparametrar

Uppdatera en sökparameter

Ta bort en sökparameter

Nästa steg

Ytterligare resurser