Condividi tramite

Definizione di parametri di ricerca personalizzati

  • Articolo

La specifica FHIR definisce un set di parametri di ricerca che si applicano a tutte le risorse. FHIR definisce inoltre molti parametri di ricerca specifici di determinate risorse. Esistono tuttavia scenari in cui è possibile cercare un elemento in una risorsa che 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 Azure Health Data Services.

Nota

Ogni volta che si crea, si aggiorna o si elimina un parametro di ricerca, è necessario eseguire un processo di reindex per abilitare il parametro di ricerca per la produzione in tempo reale. Di seguito verrà illustrato come testare i parametri di ricerca prima di reinserire l'intero database del servizio FHIR.

Creare un nuovo parametro di ricerca

Per creare un nuovo parametro di ricerca, è necessario eseguire POST una SearchParameter risorsa nel 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

Nell'esempio di codice riportato di seguito viene illustrato 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 di riferimento

Nell'esempio di codice viene illustrato come creare un parametro di ricerca personalizzato per cercare le risorse MedicationDispense in base alla posizione in cui sono stati dispensati. Si tratta di un esempio di aggiunta di parametri di ricerca personalizzati per un tipo di 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 della funzionalità del servizio FHIR dopo POST aver eseguito la ricerca nel database e reindicizzare il database. La visualizzazione dell'istruzione nella funzionalità è l'unico SearchParameter modo per indicare se un parametro di ricerca è supportato nel servizio FHIR. Se non è possibile trovare l'oggetto nell'istruzione SearchParameter funzionalità, è comunque necessario reindicizzare il database per attivare il parametro di ricerca. È possibile POST eseguire più parametri di ricerca prima di attivare un'operazione di reindex.

Elementi importanti di una SearchParameter risorsa:

  • 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 è incluso in una chiamata API. Per l'esempio precedente con l'estensione "US Core Race", è possibile cercare dove GET {{FHIR_URL}}/Patient?race=<code><code> si trova nel set di valori dal sistema di codifica specificato. Questa chiamata recupera 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 quali tipi di risorsa corrispondono al 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 Speciale 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. Questo perché è necessaria l'espressione o la sintassi xpath e il servizio FHIR ignora la sintassi xpath.

Testare 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 reindex, esistono alcuni modi per testare i parametri di ricerca personalizzati prima di reindexing dell'intero database.

Prima di tutto, è possibile testare un nuovo parametro di ricerca per visualizzare i valori restituiti. Eseguendo il comando seguente su un'istanza di risorsa specifica (specificando l'ID risorsa), viene restituito 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 verso il basso per 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 reindexare una singola risorsa per testare la ricerca con il nuovo parametro di ricerca. Per reinserire una singola risorsa:

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 causa la restituzione dei risultati del servizio FHIR per una qualsiasi delle risorse che hanno il parametro di ricerca indicizzato, anche se non tutte le istanze di risorsa di tale tipo sono indicizzate.

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

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

Eseguire quindi una ricerca 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 confermato che funziona come previsto, eseguire o pianificare il processo di reindex in modo che i nuovi parametri di ricerca possano essere usati in produzione in tempo reale.

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

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 la PUT stringa di richiesta.

Nota

Se non si conosce l'ID per il parametro di ricerca, è possibile cercarlo usando GET {{FHIR_URL}}/SearchParameter. Verrà restituito tutti i parametri di ricerca personalizzati e standard e sarà 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 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 effetti sul comportamento previsto. È consigliabile eseguire immediatamente un processo di reindex.

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 reindex.

Passaggi successivi

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

Come eseguire un processo di reindex

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