Definición de parámetros de búsqueda personalizados para Azure API for FHIR

La especificación Fast Healthcare Interoperability Resources (FHIR®) define un conjunto de parámetros de búsqueda para todos los recursos y parámetros de búsqueda específicos de un recurso. Sin embargo, hay escenarios en los que es posible que desee buscar en un elemento de un recurso que no esté definido como un parámetro de búsqueda estándar mediante la especificación de FHIR. En este artículo se describe cómo definir sus propios parámetros de búsqueda para usarlos en Azure API for FHIR.

Creación de un parámetro de búsqueda

Para crear un parámetro de búsqueda, aplica POST al recurso SearchParameter en la base de datos. En el ejemplo de código siguiente se muestra cómo agregar us Core Race SearchParameter al Patient recurso.

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

Entre los elementos importantes de se SearchParameter incluyen los siguientes.

• url: clave única para describir el parámetro de búsqueda. Muchas organizaciones, como HL7, usan un formato de dirección URL estándar para los parámetros de búsqueda que definen, como se mostró anteriormente en el parámetro de búsqueda de carreras de US Core.

• code: el valor almacenado en el código es lo que se usa al buscar. En el ejemplo anterior, buscaría GET {FHIR_URL}/Patient?race=<code> con para obtener todos los pacientes de una raza específica. El código debe ser único para el recurso al que se aplica el parámetro de búsqueda.

• base: describe a qué recurso se aplica el parámetro de búsqueda. Si el parámetro de búsqueda se aplica a todos los recursos, puede usar Resource; de lo contrario, puede enumerar todos los recursos pertinentes.

• type: describe el tipo de datos del parámetro de búsqueda. El tipo está limitado por la compatibilidad con Azure API for FHIR. Esto significa que no se puede definir un parámetro de búsqueda de tipo Especial o definir un parámetro de búsqueda compuesto a menos que sea una combinación admitida.

• expression: describe cómo calcular el valor de la búsqueda. Al describir un parámetro de búsqueda, debe incluir la expresión, aunque la especificación no lo requiera. Esto se debe a que necesita la expresión o la sintaxis xpath y Azure API for FHIR omite la sintaxis xpath.

Prueba de los parámetros de búsqueda

Aunque no puede usar los parámetros de búsqueda en producción hasta que ejecute un trabajo de reindexación, puede probar los parámetros de búsqueda antes de volver a indexar toda la base de datos.

En primer lugar, puede probar el nuevo parámetro de búsqueda para ver qué valores se devuelven. Al ejecutar el siguiente comando en una instancia de recurso específica (mediante la entrada de su identificador), se obtiene una lista de pares de valor con el nombre del parámetro de búsqueda y el valor almacenado para el paciente específico. Esto incluye todos los parámetros de búsqueda del recurso. Puede desplazarse por la lista devuelta para buscar el parámetro de búsqueda que creó. La ejecución de este comando no cambiará ningún comportamiento en el servidor FHIR.

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

Por ejemplo, para buscar todos los parámetros de búsqueda de un paciente, use lo siguiente.

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

El resultado es similar al siguiente.

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

Una vez que vea que el parámetro de búsqueda se muestre según lo previsto, puede volver a indexar un único recurso para probar la búsqueda con el elemento. En primer lugar, vuelva a indexar un único recurso:

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

Al ejecutar esto se establecen los índices de los parámetros de búsqueda para el recurso específico que definió para ese tipo de recurso. Esta acción actualiza el servidor FHIR. Ahora puede buscar y establecer el encabezado usar índices parciales en true, lo que significa que devuelve resultados donde cualquiera de los recursos que tienen el parámetro de búsqueda indexado, incluso si no todos los recursos de ese tipo lo han indexado.

Siguiendo con nuestro ejemplo, podría indizar un paciente para habilitar la carrera SearchParameter básica de EE. UU. como se indica a continuación.

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

A continuación, busque pacientes que tengan una raza específica:

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

Una vez satisfecho que el parámetro de búsqueda funciona según lo previsto, ejecute o programe el trabajo de reindexación para que los parámetros de búsqueda se puedan usar en el servidor FHIR para casos de uso de producción.

Actualización de un parámetro de búsqueda

Para actualizar un parámetro de búsqueda, use PUT para crear una versión del parámetro. Debe incluir el objeto SearchParameter ID en el elemento id del cuerpo de la solicitud PUT y en la llamada PUT.

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

El resultado es una actualización SearchParameter y se incrementa la versión.

Eliminación de un parámetro de búsqueda

Si necesita eliminar un parámetro de búsqueda, use lo siguiente.

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

Pasos siguientes

En este artículo, ha aprendido a crear un parámetro de búsqueda. A continuación, puede obtener información sobre cómo volver a indexar el servidor FHIR.