Definiera anpassade sökparametrar

FHIR-specifikationen® definierar en uppsättning sökparametrar som gäller för alla resurser. Dessutom kan du definiera anpassade sökparametrar som är specifika för vissa resurser. Med anpassade sökparametrar kan du söka mot 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 anpassade sökparametrar för användning i FHIR-tjänsten i Azure Health Data Services.

Kommentar

Varje gång du skapar, uppdaterar eller tar bort en sökparameter måste du köra ett omindexeringsjobb för att godkänna ändringarna. Om du vill visa status för sökparametrar tillhandahålls API-slutpunkten $status . Om statusen för en sökparameter är Pendinganger det att sökparametern måste indexeras om.

Skapa ny sökparameter

För att skapa en ny sökparameter, POST lägger du till en SearchParameter resurs i FHIR-tjänstens databas.

POST {{FHIR_URL}}/SearchParameter

Följande exempel visar hur du skapar en ny anpassad sökparameter.

Skapa ny sökparameter per definition i implementeringsguiden

Följande kodexempel visar hur du lägger till sökparametern US Core Race i Patient resurstypen i din FHIR-tjänstdatabas.

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

Skapa ny sökparameter för resursattribut med referenstyp

Följande kodexempel visar hur du skapar en anpassad sökparameter för att söka i MedicationDispense-resurser baserat på platsen där de delades ut. Det här exemplet visar hur du lägger till en anpassad sökparameter för en referenstyp.

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

Kommentar

Den nya sökparametern visas i kapabilitetsuttalandet för FHIR-tjänsten efter att du POST har lagt till sökparametern i databasen och omindexerat databasen. Att visa SearchParameter i kapabilitetsuttrycket är det enda sättet att avgöra om en sökparameter stöds i din FHIR-tjänst. Om du inte hittar SearchParameter i funktionssatsen måste du fortfarande indexera om databasen för att aktivera sökparametern. Du kan POST flera sökparametrar innan du utlöser en omindexeringsåtgärd.

Viktiga element i en SearchParameter resurs är:

url: En unik nyckel för att beskriva sökparametern. Organisationer som HL7 använder ett standard-URL-format för de sökparametrar som de definierar, enligt vad som visades tidigare i sökparametern US Core Race.
code: Värdet som lagras i kodelementet är det namn som används för sökparametern när det ingår i ett API-anrop. I det föregående exemplet med tillägget "US Core Race" söker du med GET {{FHIR_URL}}/Patient?race=<code> där <code> ingår i värdemängden från det angivna kodsystemet. Det här anropet hämtar alla patienter av en viss ras.
base: Beskriver vilka resurstyper sökparametern gäller för. Om sökparametern gäller för alla resurser använder du Resource. Annars anger du alla relevanta resurstyper.
target: Beskriver vilka resurstyper sökparametern matchar.
type: Beskriver datatypen för sökparametern. Typen begränsas av stöd för datatyper i FHIR-tjänsten. Den här begränsningen 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.
expression: 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 specifikationen inte kräver det. Det här kravet finns eftersom du behöver antingen uttrycket eller xpath-syntaxen och FHIR-tjänsten ignorerar xpath-syntaxen.

Testa nya sökparametrar

Du kan inte använda de nya sökparametrarna i produktion förrän du kör ett omindexeringsjobb, men du kan testa dina anpassade sökparametrar innan du indexerar om hela databasen.

Testa först en ny sökparameter för att se vilka värden den returnerar. Genom att köra följande kommando mot en specifik resursinstans (genom att ange resurs-ID:t) får du tillbaka en lista med värdepar med sökparnamnet och värdet som lagras i motsvarande element. Den här listan innehåller alla sökparametrar för resursen. Du kan bläddra igenom för att hitta sökparametern som du skapade. Om du kör det här kommandot ändras inget beteende i FHIR-tjänsten.

Kommentar

Varje gång du skapar, uppdaterar eller tar bort en sökparameter måste du köra ett omindexeringsjobb för att godkänna ändringarna. Om du vill visa status för sökparametrar tillhandahålls en API-slutpunkt ($status). Om statusen för sökparametern är i väntande tillstånd är det en bra indikation på att den måste indexeras om.

GET https://{{FHIR_URL}}/{{RESOURCE}}/{{RESOURCE_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 den nya sökparametern. Om du vill indexera om en enskild resurs använder du följande kommando.

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

Om du kör det här POST anropet anges indexen för alla sökparametrar som definierats för resursinstansen som anges i begäran. Det här anropet gör en ändring i FHIR-tjänstdatabasen. Nu kan du söka och ange x-ms-use-partial-indices rubriken till true. Den här inställningen gör att FHIR-tjänsten returnerar resultat för någon av de resurser som har sökparametern indexerad, även om inte alla resursinstanser av den typen har indexerat den.

Om du fortsätter med exemplet kan du indexera en patient för att aktivera SearchParameter:

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

Och gör sedan testsökningar:

Per patient uppdelat efter ras:

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

För Plats (referenstyp)

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

När du har testat den nya sökparametern och bekräftat att den fungerar som förväntat kör eller schemalägger du omindexeringsjobbet så att de nya sökparametrarna kan användas i liveproduktion.

Information om hur du indexerar om FHIR-tjänstdatabasen finns i Köra ett omindexeringsjobb.

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 sökparameter-ID:t i fältet id i brödtexten i begäran PUT och i begärandesträngen PUT.

Kommentar

Om du inte känner till ID:t för sökparametern kan du söka efter det med hjälp GET {{FHIR_URL}}/SearchParameterav . Den här begäran returnerar alla anpassade sökparametrar och standardsökparametrar. Du kan bläddra igenom listan för att hitta den sökparameter du behöver. Du kan också begränsa sökningen efter namn. Som visas i följande exempelbegäran är namnet på den anpassade SearchParameterresursinstansen USCoreRace. Du kan söka efter den här SearchParameter resursen efter namn med hjälp GET {{FHIR_URL}}/SearchParameter?name=USCoreRaceav .

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 av föregående begäran är en uppdaterad SearchParameter resurs.

Om du vill undvika avbrott med omindexering av en befintlig anpassad sökparameter bör du överväga att skapa en ny anpassad sökparameter i stället. Kontrollera att bas-, kod- och URL-värdena som är associerade med den nya sökparametern är unika. Om du duplicerar dessa fält kan det leda till ett obestämt beteende under omindexeringen.

Varning

Var försiktig när du uppdaterar sökparametrarna. Att ändra en befintlig sökparameter kan påverka förväntat beteende. Starta ett omindexeringsjobb omedelbart. Obs! Frekventa ändringar av anpassade sökparametrar i produktionsinstanser kan störa frågor. Planera sådana ändringar noggrant för att undvika potentiella problem.

Ta bort en sökparameter

Om du vill ta bort en sökparameter använder du följande begäran.

Kommentar

Varje gång du tar bort en sökparameter måste du köra ett omindexera jobb för att godkänna ändringarna. Om du vill visa status för sökparametrar tillhandahålls en API-slutpunkt ($status). Om sökparameterns status är i PendingDelete eller PendingHardDelete tillstånd kontrollerar du att du kör omindexering.

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

Nästa steg

I den här artikeln har du lärt dig hur du skapar en anpassad sökparameter. Sedan kan du lära dig hur du indexerar om FHIR-tjänstdatabasen.

Så här kör du ett omindexeringsjobb

Kommentar

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

Feedback

Var den här sidan till hjälp?

Uppdaterades senast 2026-07-07

Definiera anpassade sökparametrar

Skapa ny sökparameter

Skapa ny sökparameter per definition i implementeringsguiden

Skapa ny sökparameter för resursattribut med referenstyp

Testa nya sökparametrar

Uppdatera en sökparameter

Ta bort en sökparameter

Nästa steg

Feedback

Ytterligare resurser