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

Artikel
10/04/2024

Viktigt!

Azure API för FHIR avvecklas den 30 september 2026. Följ migreringsstrategierna för att övergå till Azure Health Data Services FHIR-tjänsten® senast det datumet. På grund av tillbakadragandet av Azure API för FHIR tillåts inte nya distributioner från och med den 1 april 2025. Azure Health Data Services FHIR-tjänsten är den utvecklade versionen av Azure API för FHIR som gör det möjligt för kunder att hantera FHIR-, DICOM- och MedTech-tjänster med integreringar i andra Azure-tjänster.

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 resurs. Det finns dock scenarier där du kanske vill söka efter ett element i en resurs som inte definieras som en standardsökparameter enligt FHIR-specifikationen. Den här artikeln beskriver hur du kan definiera dina egna sökparametrar som ska användas i Azure API för FHIR.

Kommentar

Varje gång du skapar, uppdaterar eller tar bort en sökparameter måste du köra ett omindexeringsjobb så att sökparametern kan användas i produktion. Den här artikeln beskriver 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 kan du använda POST resursen SearchParameter i databasen. Följande kodexempel 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"
}

Kommentar

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, men inte kan se den i funktionssatsen, 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 inkluderar följande.

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, som tidigare visades i US Core-parametern för racesökning.
kod: Värdet som lagras i kod är det du använder när du söker. I föregående exempel skulle du söka med GET {FHIR_URL}/Patient?race=<code> för att få alla patienter i en specifik ras. Koden måste vara unik för resursen som sökparametern gäller för.
base: Beskriver vilken resurs 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 du kan 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 returneras. Genom att köra följande kommando mot en specifik resursinstans (genom att ange deras ID) får du en lista över värdepar med sökparnamnet och värdet som lagras för den specifika patienten. Detta inkluderar alla sökparametrar för resursen. Du kan bläddra igenom den returnerade listan för att hitta sökparametern som du skapade. Om du kör det här kommandot ändras inget 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 använder du följande.

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 anges indexen för sökparametrar för den specifika resurs som du har definierat för den resurstypen. Detta gör en uppdatering av FHIR-servern. Nu kan du söka efter och ange rubriken använd partiella index till true, vilket innebär att den returnerar resultat där någon av de resurser som har sökparametern indexerad, även om inte alla resurser av den typen har indexerats.

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

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

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 är nöjd med att sökparametern fungerar som förväntat kör eller schemalägger du omindexeringsjobbet så att sökparametrarna kan användas i 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 .

Kommentar

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 listan för att hitta sökparametern som du behöver. Du kan också begränsa sökningen efter namn. Med följande exempel 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 är en uppdaterad 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

Kommentar

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

Dela via

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

Feedback

Ytterligare resurser