Definición de parámetros de búsqueda personalizados para Azure API for FHIR
Importante
Azure API for FHIR se retirará el 30 de septiembre de 2026. Siga las estrategias de migración para realizar la transición a servicio FHIR® de Azure Health Data Services en esa fecha. Debido a la retirada de Azure API for FHIR, no se permitirán nuevas implementaciones a partir del 1 de abril de 2025. El servicio FHIR de Azure Health Data Services es la versión evolucionada de la API de Azure para FHIR que permite a los clientes administrar FHIR, DICOM y los servicios de tecnologías médicas con integraciones en otros servicios de Azure.
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.
Nota:
Cada vez que cree, actualice o elimine un parámetro de búsqueda, deberá ejecutar un trabajo de reindexación para permitir que dicho parámetro se utilice en producción. En este artículo se describe cómo probar los parámetros de búsqueda antes de volver a indexar todo el servidor 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"
}
Nota:
El nuevo parámetro de búsqueda aparecerá en la instrucción de funcionalidad del servidor FHIR una vez que aplique POST al parámetro de búsqueda en la base de datos y vuelva a indexarla. Ver el objeto SearchParameter en la instrucción de funcionalidad es la única manera de saber si se admite un parámetro de búsqueda en su servidor FHIR. Si puede encontrar el parámetro de búsqueda, pero no puede verlo en la instrucción de funcionalidad, todavía debe indexar el parámetro de búsqueda. Puede aplicar POST a varios parámetros de búsqueda antes de desencadenar una operación de reindexación.
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.
Nota:
Si no conoce el Id. del parámetro de búsqueda, puede buscarlo. El uso GET {{FHIR_URL}}/SearchParameter devolverá todos los parámetros de búsqueda personalizados y puede desplazarse por la lista para encontrar el parámetro de búsqueda que necesita. También puede limitar la búsqueda por nombre. Con el ejemplo siguiente, podría buscar el nombre mediante 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"
}
El resultado es una actualización SearchParameter y se incrementa la versión.
Advertencia
Tenga cuidado al actualizar parámetros de búsqueda que ya se hayan indexado en su base de datos. El cambio del comportamiento existente de un parámetro podría incidir en el comportamiento esperado. Se recomienda ejecutar un trabajo de reindexación inmediatamente.
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}
Advertencia
Tenga cuidado al eliminar parámetros de búsqueda que ya se hayan indexado en su base de datos. El cambio del comportamiento existente de un parámetro podría incidir en el comportamiento esperado. Se recomienda ejecutar un trabajo de reindexación inmediatamente.
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.
Nota:
FHIR® es una marca registrada de HL7 y se usa con su permiso.