Ejecución de un trabajo de reindexación en Azure API for FHIR

Artículo
10/04/2024

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.

Hay escenarios en los que es posible que tenga parámetros de búsqueda o ordenación en Azure API for FHIR® que aún no se hayan indexado. Este escenario procede cuando se definen parámetros de búsqueda propios. No puede utilizar un parámetro de búsqueda en una búsqueda hasta que se lo indexe. En este artículo se explica cómo ejecutar un trabajo de reindexación para indexar parámetros de búsqueda en la base de datos del servicio FHIR.

Advertencia

Antes de empezar, lea todo el artículo. Un trabajo de reindexación puede requerir mucho rendimiento. En este artículo se incluyen opciones para limitar y controlar el trabajo de reindexación.

Procedimientos para ejecutar un trabajo de reindexación

Un trabajo de reindexación se puede ejecutar en toda la base de datos del servicio FHIR y en parámetros de búsqueda personalizados específicos.

Ejecución del trabajo de reindexación en toda la base de datos del servicio FHIR

Para ejecutar un trabajo de reindexación, use la siguiente POST llamada con el recurso con formato Parameters JSON en el cuerpo de la solicitud.

POST {{FHIR URL}}/$reindex 

{ 

“resourceType”: “Parameters”,  

“parameter”: [] 

}

Deje el "parameter": [] campo en blanco (como se muestra) si no necesita ajustar los recursos asignados al trabajo de reindexación.

Si la solicitud se realiza correctamente, recibirá un código de estado 201 Creado además de un Parameters recurso en la respuesta, como en el ejemplo siguiente.

HTTP/1.1 201 Created 
Content-Location: https://{{FHIR URL}}/_operations/reindex/560c7c61-2c70-4c54-b86d-c53a9d29495e 

{
  "resourceType": "Parameters",
  "id": "560c7c61-2c70-4c54-b86d-c53a9d29495e",
  "meta": {
    "versionId": "\"4c0049cd-0000-0100-0000-607dc5a90000\""
  },
  "parameter": [
    {
      "name": "id",
      "valueString": "560c7c61-2c70-4c54-b86d-c53a9d29495e"
    },
    {
       "name": "lastModified",
       "valueDateTime": "2023-06-08T04:52:44.0974408+00:00"
    },
    {
       "name": "queuedTime",
       "valueDateTime": "2023-06-08T04:52:44.0974406+00:00"
    },
    {
       "name": "totalResourcesToReindex",
       "valueDecimal": 0.0
    },
    {
       "name": "resourcesSuccessfullyReindexed",
       "valueDecimal": 0.0
    },
    {
       "name": "progress",
       "valueDecimal": 0.0
    },
    {
       "name": "status",
       "valueString": "Queued"
    },
    {
       "name": "maximumConcurrency",
       "valueDecimal": 3.0
    },
    {
        "name": "queryDelayIntervalInMilliseconds",
        "valueDecimal": 500.0
    },
    {
        "name": "maximumNumberOfResourcesPerQuery",
        "valueDecimal": 100.0
    }
  ]
}

Ejecución del trabajo de reindexación en un parámetro de búsqueda personalizado específico

Para ejecutar un trabajo de reindexación en un parámetro de búsqueda personalizado específico, use la siguiente POST llamada con el recurso con formato Parameters JSON en el cuerpo de la solicitud.

POST {{FHIR_URL}}/$reindex 
content-type: application/fhir+json
{ 

"resourceType": "Parameters",  

"parameter": [
    {
      "name": "targetSearchParameterTypes",
      "valueString": "{url of custom search parameter. In case of multiple custom search parameters, url list can be comma seperated.}"
    }
] 

}

Nota:

Para comprobar el estado de un trabajo de reindexación o cancelar el trabajo, necesitará el identificador de reindexación. Este es el "id" objeto que se lleva en el "parameter" valor devuelto en la respuesta. En el ejemplo anterior, el identificador del trabajo de reindexación sería 560c7c61-2c70-4c54-b86d-c53a9d29495e.

Comprobación del estado de un trabajo de reindexación

Una vez que inicie un trabajo de reindexación, puede comprobar el estado del trabajo mediante la siguiente llamada.

GET {{FHIR URL}}/_operations/reindex/{{reindexJobId}

Este es un ejemplo de respuesta.

{
    "resourceType": "Parameters",
    "id": "560c7c61-2c70-4c54-b86d-c53a9d29495e",
    "meta": {
        "versionId": "138087"
    },
    "parameter": [
        {
            "name": "id",
            "valueString": "560c7c61-2c70-4c54-b86d-c53a9d29495e"
        },
        {
            "name": "startTime",
            "valueDateTime": "2023-06-08T04:54:53.2943069+00:00"
        },
        {
            "name": "endTime",
            "valueDateTime": "2023-06-08T04:54:54.4052272+00:00"
        },
        {
            "name": "lastModified",
            "valueDateTime": "2023-06-08T04:54:54.4053002+00:00"
        },
        {
            "name": "queuedTime",
            "valueDateTime": "2023-06-08T04:52:44.0974406+00:00"
        },
        {
            "name": "totalResourcesToReindex",
            "valueDecimal": 2.0
        },
        {
            "name": "resourcesSuccessfullyReindexed",
            "valueDecimal": 2.0
        },
        {
            "name": "progress",
            "valueDecimal": 100.0
        },
        {
            "name": "status",
            "valueString": "Completed"
        },
        {
            "name": "maximumConcurrency",
            "valueDecimal": 3.0
        },
        {
            "name": "resources",
            "valueString": "{{LIST_OF_IMPACTED_RESOURCES}}"
        },
        {
            "name": "resourceReindexProgressByResource (CountReindexed of Count)",
            "valueString": "{{RESOURCE_TYPE:REINDEXED_COUNT OF TOTAL_COUNT}}"
        },
        {
            "name": "searchParams",
            "valueString": "{{LIST_OF_SEARCHPARAM_URLS}}h"
        },
        {
            "name": "queryDelayIntervalInMilliseconds",
            "valueDecimal": 500.0
        },
        {
            "name": "maximumNumberOfResourcesPerQuery",
            "valueDecimal": 100.0
        }
    ]
}

La siguiente información se muestra en la respuesta.

totalResourcesToReindex: incluye el número total de recursos que se vuelven a indexar en este trabajo.
resourcesSuccessfullyReindexed: el número total de recursos que ya se han vuelto a indexar en este trabajo.
progress: se ha completado el porcentaje de trabajo de reindexación. Calculado como resourcesSuccessfullyReindexed/totalResourcesToReindex x 100.
status: indica si el trabajo de reindexación está en cola, en ejecución, completado, con errores o cancelado.
resources: enumera todos los tipos de recursos afectados por el trabajo de reindexación.
resourceReindexProgressByResource (CountReindexed of Count): proporciona un recuento reindexado del recuento total, por tipo de recurso. En los casos en los que se pone en cola la reindexación de un tipo de recurso específico, solo se proporciona Count.
searchParams: muestra la dirección URL de los parámetros de búsqueda afectados por el trabajo de reindexación.

Eliminación de un trabajo de reindexación

Si necesita cancelar un trabajo de reindexación, use una llamada de eliminación y especifique el identificador del trabajo de reindexación:

Delete {{FHIR URL}}/_operations/reindex/{{reindexJobId}

Consideraciones sobre el rendimiento

Un trabajo de reindexación puede requerir mucho rendimiento. Hemos implementado algunos controles de limitación para ayudarle a administrar cómo se ejecuta un trabajo de reindexación en la base de datos.

Nota:

En los conjuntos de datos de gran tamaño, no es poco frecuente que la ejecución de un trabajo de reindexación dure varios días. En el caso de una base de datos con 30 000 000 recursos, hemos observado que tardó entre 4 y 5 días en 100 000 unidades de solicitud (RU) para volver a indexar toda la base de datos.

A continuación se muestra una tabla que describe los parámetros disponibles, los valores predeterminados y los intervalos recomendados. Puede usar estos parámetros, ya sea para acelerar el proceso (usar más), o para ralentizarlo (usar menos). Por ejemplo, podría ejecutar el trabajo de reindexación en un tiempo de tráfico bajo y aumentar el proceso para que se haga más rápido. También puede usar la configuración para garantizar un bajo uso de proceso y que se ejecute durante días en segundo plano.

Parámetro	Descripción	Valor predeterminado	Intervalo disponible
QueryDelayIntervalInMilliseconds	Retraso entre cada lote de recursos que se va a iniciar durante el trabajo de reindexación. Un número menor acelera el trabajo mientras un número mayor lo ralentiza.	500 MS (0,5 segundos)	50-500 000
MaximumResourcesPerQuery	Número máximo de recursos incluidos en el lote de recursos que se van a reindexar.	100	1-5000
MaximumConcurrency	Es el número de lotes que se realiza al mismo tiempo.	1	1-10
targetDataStoreUsagePercentage	Permite especificar el porcentaje del almacén de datos que se va a usar para el trabajo de reindexación. Por ejemplo, podría especificar el 50 % y eso garantizaría que el trabajo de reindexación usaría, como máximo, el 50 % de las RU disponibles en Azure Cosmos DB.	No existe, lo que significa que se puede usar hasta el 100 %.	0-100

Si desea usar cualquiera de los parámetros anteriores, puede pasarlos al recurso Parameters al iniciar el trabajo de reindexación.

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "maximumConcurrency",
      "valueInteger": "3"
    },
    {
      "name": "targetDataStoreUsagePercentage",
      "valueInteger": "20"
    },
    {
      "name": "queryDelayIntervalInMilliseconds",
      "valueInteger": "1000"
    },
    {
      "name": "maximumNumberOfResourcesPerQuery",
      "valueInteger": "1"
    }
  ]
}

Pasos siguientes

En este artículo, ha aprendido a iniciar un trabajo de reindexación. Si desea aprender a definir parámetros de búsqueda nuevos que requieran el trabajo de reindexación, consulte

Definición de parámetros de búsqueda personalizados

Nota:

FHIR® es una marca registrada de HL7 y se usa con su permiso.

Compartir a través de

Ejecución de un trabajo de reindexación en Azure API for FHIR

Procedimientos para ejecutar un trabajo de reindexación

Ejecución del trabajo de reindexación en toda la base de datos del servicio FHIR

Ejecución del trabajo de reindexación en un parámetro de búsqueda personalizado específico

Comprobación del estado de un trabajo de reindexación

Eliminación de un trabajo de reindexación

Consideraciones sobre el rendimiento

Pasos siguientes

Comentarios

Recursos adicionales