Definizione di parametri di ricerca personalizzati

  • Articolo

La specifica FHIR® definisce un set di parametri di ricerca che si applicano a tutte le risorse. Inoltre, FHIR definisce molti parametri di ricerca specifici per determinate risorse. Tuttavia, è anche possibile cercare un elemento in una risorsa non definita dalla specifica FHIR come parametro di ricerca standard. Questo articolo descrive come definire i propri parametri di ricerca personalizzati da usare nel servizio FHIR in Servizi dati di integrità di Azure.

Nota

Ogni volta che si crea, si aggiorna o si elimina un parametro di ricerca, è necessario eseguire un processo di reindicizzazione per abilitare il parametro di ricerca per la produzione in tempo reale. Verrà descritto come testare i parametri di ricerca prima di reindicizzare l'intero database del servizio FHIR seguente.

Creare un nuovo parametro di ricerca

Per creare un nuovo parametro di ricerca, è necessario usare POST una SearchParameter risorsa per il database del servizio FHIR.

POST {{FHIR_URL}}/SearchParameter

Gli esempi seguenti illustrano la creazione di un nuovo parametro di ricerca personalizzato.

Creare un nuovo parametro di ricerca per definizione nella Guida all'implementazione

L'esempio di codice seguente illustra come aggiungere il parametro di ricerca US Core Race al Patient tipo di risorsa nel database del servizio FHIR.

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

Creare un nuovo parametro di ricerca per gli attributi delle risorse con tipo riferimento

L'esempio di codice seguente illustra come creare un parametro di ricerca personalizzato per cercare le risorse MedicationDispense in base alla posizione in cui sono stati erogati. Questo è un esempio di aggiunta di un parametro di ricerca personalizzato per un tipo riferimento.

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

Nota

Il nuovo parametro di ricerca verrà visualizzato nell'istruzione capability del servizio FHIR dopo aver POST eseguito il parametro di ricerca nel database e reindicizzare il database. SearchParameter La visualizzazione di nell'istruzione capability è l'unico modo per stabilire se un parametro di ricerca è supportato nel servizio FHIR. Se non è possibile trovare nell'istruzione SearchParameter capability, è comunque necessario reindicizzare il database per attivare il parametro di ricerca. È possibile POST eseguire più parametri di ricerca prima di attivare un'operazione di reindicizzazione.

Gli elementi importanti di una SearchParameter risorsa sono:

  • url: chiave univoca per descrivere il parametro di ricerca. Le organizzazioni come HL7 usano un formato URL standard per i parametri di ricerca definiti, come illustrato in precedenza nel parametro di ricerca US Core Race.

  • code: il valore archiviato nell'elemento di codice è il nome usato per il parametro di ricerca quando viene incluso in una chiamata API. Per l'esempio precedente con l'estensione "US Core Race", eseguire una ricerca con GET {{FHIR_URL}}/Patient?race=<code> dove <code> si trova nel valore impostato dal sistema di codifica specificato. Questa chiamata recupererebbe tutti i pazienti di una determinata razza.

  • base: descrive i tipi di risorsa a cui si applica il parametro di ricerca. Se il parametro di ricerca si applica a tutte le risorse, è possibile usare Resource; in caso contrario, è possibile elencare tutti i tipi di risorse pertinenti.

  • target: descrive i tipi di risorsa a cui corrisponde il parametro di ricerca.

  • type: descrive il tipo di dati per il parametro di ricerca. Il tipo è limitato dal supporto per i tipi di dati nel servizio FHIR. Ciò significa che non è possibile definire un parametro di ricerca di tipo Special o definire un parametro di ricerca composito, a meno che non sia una combinazione supportata.

  • expression: descrive come calcolare il valore per la ricerca. Quando si descrive un parametro di ricerca, è necessario includere l'espressione, anche se non è richiesta dalla specifica. Ciò è dovuto al fatto che è necessaria l'espressione o la sintassi xpath e il servizio FHIR ignora la sintassi xpath.

Testare i nuovi parametri di ricerca

Anche se non è possibile usare i nuovi parametri di ricerca nell'ambiente di produzione fino a quando non si esegue un processo di reindicizzazione, è possibile testare i parametri di ricerca personalizzati prima di reindicizzare l'intero database.

Prima di tutto, è possibile testare un nuovo parametro di ricerca per vedere quali valori vengono restituiti. Eseguendo il comando seguente su un'istanza di risorsa specifica (specificando l'ID risorsa), si ottiene un elenco di coppie di valori con il nome del parametro di ricerca e il valore archiviato nell'elemento corrispondente. Questo elenco include tutti i parametri di ricerca per la risorsa. È possibile scorrere fino a trovare il parametro di ricerca creato. L'esecuzione di questo comando non modifica alcun comportamento nel servizio FHIR.

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

Ad esempio, per trovare tutti i parametri di ricerca per un paziente:

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

Il risultato è simile al seguente:

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

Dopo aver visualizzato il parametro di ricerca come previsto, è possibile reindicizzare una singola risorsa per testare la ricerca con il nuovo parametro di ricerca. Per reindicizzare una singola risorsa, usare quanto segue.

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

L'esecuzione di questa POST chiamata imposta gli indici per tutti i parametri di ricerca definiti per l'istanza della risorsa specificata nella richiesta. Questa chiamata apporta una modifica al database del servizio FHIR. È ora possibile cercare e impostare l'intestazione x-ms-use-partial-indices su true, che fa in modo che il servizio FHIR restituisca i risultati per tutte le risorse con il parametro di ricerca indicizzato, anche se non tutte le istanze di risorse di quel tipo lo hanno indicizzato.

Continuando con l'esempio, è possibile indicizzare un paziente per abilitare SearchParameter:

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

Eseguire quindi ricerche di test:

  1. Per il paziente per razza:
GET {{FHIR_URL}}/Patient?race=2028-9
x-ms-use-partial-indices: true
  1. Per Location (tipo di riferimento)
{{fhirurl}}/MedicationDispense?location=<locationid referenced in MedicationDispense Resource>
x-ms-use-partial-indices: true

Dopo aver testato il nuovo parametro di ricerca e aver verificato che funzioni come previsto, eseguire o pianificare il processo di reindicizzazione in modo che i nuovi parametri di ricerca possano essere usati nell'ambiente di produzione in tempo reale.

Per informazioni su come reindicizzare il database del servizio FHIR, vedere Esecuzione di un processo di reindicizzazione.

Aggiornare un parametro di ricerca

Per aggiornare un parametro di ricerca, usare PUT per creare una nuova versione del parametro di ricerca. È necessario includere l'ID del parametro di ricerca nel id campo nel corpo della PUT richiesta e della stringa di PUT richiesta.

Nota

Se non si conosce l'ID per il parametro di ricerca, è possibile cercarlo usando GET {{FHIR_URL}}/SearchParameter. Verranno restituiti tutti i parametri di ricerca personalizzati e standard. È possibile scorrere l'elenco per trovare il parametro di ricerca necessario. È anche possibile limitare la ricerca in base al nome. Come illustrato nella richiesta di esempio seguente, il nome dell'istanza della risorsa personalizzata SearchParameter è USCoreRace. È possibile cercare questa SearchParameter risorsa in base al nome usando 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"
}

Il risultato della richiesta precedente sarà una risorsa aggiornata SearchParameter .

Avviso

Prestare attenzione quando si aggiornano i parametri di ricerca. La modifica di un parametro di ricerca esistente potrebbe avere un impatto sul comportamento previsto. È consigliabile eseguire immediatamente un processo di reindicizzazione.

Eliminare un parametro di ricerca

Se è necessario eliminare un parametro di ricerca, usare quanto segue.

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

Avviso

Prestare attenzione quando si eliminano i parametri di ricerca. L'eliminazione di un parametro di ricerca esistente potrebbe influire sul comportamento previsto. È consigliabile eseguire immediatamente un processo di reindicizzazione.

Passaggi successivi

In questo articolo si è appreso come creare un parametro di ricerca personalizzato. Successivamente è possibile imparare a reindicizzare il database del servizio FHIR. Per ulteriori informazioni, vedere,

Come eseguire un processo di reindicizzazione

Nota

FHIR® è un marchio registrato di HL7 ed è usato con l'autorizzazione di HL7.