Esta página se ha traducido con Cloud Translation API.

Prácticas recomendadas para las operaciones de larga duración

En esta página se describen las prácticas recomendadas para ejecutar y gestionar operaciones de larga duración (OLDs) en la API Cloud Healthcare. Para obtener una descripción general de las operaciones de larga duración en la API Cloud Healthcare, consulta Gestionar operaciones de larga duración.

Propiedades de LRO

Las siguientes secciones se aplican a los métodos que se indican en Métodos que devuelven un LRO.

Impacto de las cuotas

Las operaciones LRO no comparten cuota con los métodos de creación, lectura, actualización y eliminación (CRUD) de la API Cloud Healthcare, que consumen los siguientes tipos de cuota:

La cuota de LRO se calcula mediante las métricas fhir_store_lro_ops y dicom_store_lro_ops.

La API Cloud Healthcare limita el número de operaciones de larga duración que se pueden ejecutar simultáneamente en un Google Cloud proyecto. Para obtener más información, consulta Límites en el número de operaciones de larga duración.

Velocidad de transferencia de datos

Los métodos LRO suelen conseguir un mayor rendimiento de datos que los métodos CRUD equivalentes. Por ejemplo, importar instancias DICOM con dicomStores.import suele ser más eficiente que almacenar las instancias individualmente con dicomStores.storeInstances.

Ejecutar varias operaciones LRO simultáneamente puede no aumentar el rendimiento de los datos debido a las siguientes restricciones, especialmente al procesar grandes volúmenes de datos:

Limitaciones de cuota
Contención de recursos
Otro tráfico que tu Google Cloud proyecto envía a la API Cloud Healthcare mientras se ejecuta una operación LRO

Para maximizar el rendimiento de los datos al ejecutar operaciones LRO, tenga en cuenta lo siguiente:

Los lotes de importación y exportación pequeños suelen tener un rendimiento bajo debido a la sobrecarga.
Las operaciones LRO se ejecutan y consumen cuota de forma independiente a otras operaciones de la API Cloud Healthcare.
Cada LRO tiene un rendimiento máximo.
Las LROs simultáneas en el mismo recurso pueden provocar conflictos de bloqueo.
La API Cloud Healthcare limita el número de operaciones de larga duración que se pueden ejecutar simultáneamente en un Google Cloud proyecto. Para obtener más información, consulta Límites en el número de operaciones de larga duración.

Planifica el número de operaciones de larga duración que requiere tu caso práctico. Si tienes que particionar grandes lotes de datos en varias operaciones LRO, intenta que el número de particiones sea bajo.

Integridad referencial de FHIR

El método fhirStores.import no tiene en cuenta el ajuste disableReferentialIntegrity. Esto le permite importar datos con interdependencias arbitrarias que no requieren orden ni agrupación, lo que aumenta el rendimiento de los datos. Si los datos de entrada contienen referencias no válidas o si no se pueden importar algunos recursos FHIR, el estado del almacén FHIR puede infringir la integridad referencial.

Para usar fhirStores.import, tu aplicación cliente debe asegurarse de que las referencias de recursos FHIR sean válidas verificando lo siguiente:

Los datos y el formato del recurso FHIR son correctos
Los errores que se produzcan durante la importación se gestionan

Para aplicar la integridad referencial, usa fhir.create o fhir.executeBundle en lugar de fhirStores.import. Para obtener más información, consulta Importar datos FHIR o ejecutar paquetes.

Notificaciones de Pub/Sub

Algunos métodos de la API Cloud Healthcare envían notificaciones de Pub/Sub para eventos clínicos, como la creación o eliminación de un recurso sanitario. Para ver una lista de los métodos que envían notificaciones de Pub/Sub, consulta Configurar notificaciones de Pub/Sub.

Los siguientes métodos de importación no envían notificaciones de Pub/Sub:

Si algunas partes de tu aplicación requieren una notificación cuando finaliza una importación, usa otro método de notificación que pueda mostrar los datos de la importación.

Límites de gestión de errores

Es posible que la API Cloud Healthcare no registre todos los errores de una operación de larga duración, sobre todo si esta procesa grandes volúmenes de datos y produce muchos errores. Implementa una forma de monitorizar el procesamiento y los errores de las operaciones de larga duración por separado. Para obtener más información, consulta el artículo sobre gestión de errores de recursos.

Datos e indexación de búsquedas

Los retrasos en los resultados de búsqueda pueden deberse a la indexación de búsqueda asíncrona. Si una operación LRO crea o actualiza un recurso FHIR, puede que tarde más tiempo en que los cambios estén disponibles en los resultados de búsqueda.

Por ejemplo, es posible que una búsqueda de recursos Patient en un almacén FHIR no devuelva todos los resultados inmediatamente después de una operación de importación de FHIR.

Orden de ejecución

Las operaciones LRO se programan en función de la Google Cloud disponibilidad de recursos. El orden en el que se ejecutan y finalizan las operaciones de larga duración puede no coincidir con el orden en el que se solicitaron.

Evitar solicitudes de importación y exportación pequeñas

En esta sección se describen las limitaciones de las operaciones de larga duración al procesar volúmenes de datos pequeños.

Los objetos LRO devueltos de las operaciones de importación y exportación ayudan a escalar el rendimiento de los datos procesando grandes cantidades de datos rápidamente y evitando picos de carga. Para almacenar pequeñas cantidades de datos, usa otra técnica de las prácticas recomendadas para almacenar datos.

Límites en el número de LROs

La API Cloud Healthcare limita el número de operaciones de larga duración que se pueden ejecutar simultáneamente en un Google Cloud proyecto. El límite se basa en lo siguiente:

El tipo de LRO.
Cantidad de recursos Google Cloud asignados al LRO. Esto se basa en el tamaño de los datos de entrada.

Si ejecutas demasiadas operaciones LRO, la API Cloud Healthcare limitará la frecuencia, producirá errores y podría reducir el rendimiento de las operaciones LRO. La API Cloud Healthcare conserva automáticamente los Google Cloud recursos para que el número de operaciones de larga duración se mantenga dentro de los límites de recursos.

Las operaciones LRO son procesos en segundo plano, por lo que, si la carga de las LROs interfiere con procesos de mayor prioridad, como las operaciones CRUD, la API Cloud Healthcare puede reducir el rendimiento de las LROs. De esta forma, se asegura de que los procesos de mayor prioridad estén disponibles.

Sobrecarga de asignación y limpieza de recursos

Cuando se inicia una operación LRO, la API Cloud Healthcare asigna recursos. Este proceso puede tardar varios minutos, ya que la API Cloud Healthcare tiene que hacer lo siguiente:

Inicia un proceso de controlador.
Asigna trabajadores de un grupo de trabajadores.
Determina el tamaño de los datos de entrada.
Empieza a asignar trabajo a gran escala.

Detener y limpiar un LRO también puede tardar varios minutos.

Debido a la sobrecarga, una operación de larga duración que procesa una pequeña cantidad de datos puede dedicar la mayor parte del tiempo a asignar grupos de trabajadores y a limpiar recursos.

Si tienes muchas de estas operaciones LRO, es posible que el rendimiento de los datos sea menor, ya que es más probable que alcances los límites de cuota de tu proyecto Google Cloud.

Límites para solicitar cuota de LRO

Antes de solicitar más cuota de LRO, implementa las prácticas recomendadas para gestionar las cuotas. Si sigues necesitando más cuota, ponte en contacto con el Google Cloud servicio de atención al cliente. Para hacer una solicitud, consulta las prácticas recomendadas para solicitar cuota adicional.

Puede que necesites cuota adicional si tus datos de entrada son grandes. Por ejemplo:

Estás importando instancias DICOM que tienen un tamaño de varios petabytes (PB).
Estás importando decenas de miles de millones de recursos FHIR.

Estados de error y estado de LRO

Cuando inicias una operación LRO, la respuesta contiene un ID único. Puedes ver el estado de una LRO consultando su ID. Una vez que finaliza la operación de larga duración, tiene uno de los siguientes estados:

Se ha completado correctamente sin errores
Se ha completado correctamente con algunos errores
No se ha podido completar, pero es posible que haya generado un resultado parcial antes de fallar

En el siguiente ejemplo de JSON se describe la respuesta devuelta cuando finaliza una operación de larga duración:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "METADATA_TYPE",
    "apiMethodName": "API_METHOD_NAME",
    "createTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "endTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "logsUrl": "https://console.cloud.google.com/CLOUD_LOGGING_URL"
    "counter": {
      "success": "SUCCESS_COUNT",
      // If there were any failures, they display in the `failure` field.
      "failure": "FAILURE_COUNT"
    }
  },
  "done": true,
  // The `response` field only displays if there were no errors.
  "response": {
    "@type": 
    
  },
  // If there were any errors, an `error` field displays instead of a `response` field.
  // See Troubleshooting long-running operations for a list of response codes.
  "error": {
    "code": ERROR_CODE,
    "message": "DESCRIPTION",
    "details": [
      {
        "@type": "...",
        FIELD1: ...,
        ...
      }
    ]
  }
}

Para obtener el estado de una operación de larga duración, enumerar las operaciones de larga duración y cancelar las operaciones de larga duración, consulta Gestionar operaciones de larga duración.

Gestionar el estado de las operaciones de larga duración y los estados de error

Para gestionar el estado y los estados de error de las operaciones de larga duración, sigue estas prácticas recomendadas:

Consulta el estado de las LROs para verificar cuándo han terminado. Para sondear un LRO, llama repetidamente al método projects.locations.datasets.operations.get hasta que finalice la operación. Usa un tiempo de espera entre cada solicitud de sondeo, como 10 segundos. Cuando la respuesta contiene "done": true, la LRO ha finalizado.
Cuando finaliza un LRO, comprueba si la respuesta contiene un campo error. Si es así, determina si quieres volver a intentar la operación en función de lo siguiente:
- El código de error. Consulta Solucionar problemas de operaciones de larga duración para ver los códigos de error y las acciones recomendadas.
- Número de reintentos que ya se han producido.
- El tiempo transcurrido entre el inicio del LRO y el momento en que se produjo el error. Por ejemplo, si una operación de larga duración que normalmente tarda varias horas tarda varios días y no ha devuelto un estado de error, puede que quieras que intervenga una persona. Para obtener más información sobre cuándo puede ser necesaria la intervención humana, consulta Planificar los estados de error finales.
Consulta Poner en cola un LRO para obtener información sobre cómo reintentar un LRO.
Si no vuelves a intentar la operación LRO, consulta el campo metadata.counter.failure para ver si se han producido errores en recursos específicos. Es posible que puedas procesar los recursos de forma individual. Para obtener más información, consulta el artículo sobre cómo gestionar errores de recursos.

Gestionar errores de recursos

Una LRO puede finalizar con errores. Los errores en la respuesta de la LRO siguen el Google Cloud modelo de error. La respuesta de la operación de larga duración incluye un enlace a Cloud Logging para obtener más información.

Detalles del error de LRO

Los errores de LRO en Cloud Logging tienen las siguientes propiedades:

El registro de errores de Cloud Logging no contiene el ID de LRO. Usa los campos operation.id y operation.producer para consultar el estado y los errores de la operación de larga duración. Por ejemplo, las LROs invocadas desde el método projects.locations.datasets.fhirStores.import contienen import_fhir en el campo operation.producer.

Si varios LROs tienen el mismo operation.id y operation.producer, utiliza las marcas de tiempo createTime y endTime para identificar el LRO correcto.
No todos los errores de LRO están disponibles en Cloud Logging. Es posible que el campo metadata.counter.failure supere el número de errores reales registrados por los siguientes motivos:
- Limitaciones de las cuotas de Cloud Logging
- Disponibilidad del servicio Cloud Logging
- Límites de registros de operaciones de larga duración
Por ejemplo, si una operación LRO importa 10 millones de recursos FHIR y el 50% de ellos tienen errores de formato, es posible que solo se registren unos cientos o unos miles de errores debido a la limitación de la frecuencia y a las cuotas de Cloud Logging.

El número de errores registrados también varía en función del tiempo que se ejecute la operación de larga duración mientras se producen tasas de error altas. Si la operación LRO se ejecuta lentamente, es posible que muestre más errores en Cloud Logging porque los errores se han distribuido durante un periodo prolongado y no se han sometido a la limitación de frecuencia.

Efectos de volver a intentar una operación LRO

Si una operación de larga duración detecta un error y una aplicación cliente vuelve a intentar automáticamente la operación con los mismos datos, el reintento puede provocar más errores.

Imagina una situación en la que una LRO de fhirStores.import finaliza con errores porque algunos de los recursos FHIR que ha intentado importar no eran válidos. Si se vuelve a intentar importar los datos automáticamente, es posible que se generen muchos errores 409 ALREADY_EXISTS, ya que algunos recursos FHIR se importaron en la operación original. Si consultas un LRO y encuentras una operación de creación fallida, no vuelvas a intentarlo automáticamente. Un humano debe revisar los errores 409 ALREADY_EXISTS.

Si se realiza un reintento correctamente, el campo metadata.counter.failure no incluye errores de operaciones anteriores. Esto puede provocar que el recuento de errores sea incorrecto, ya que la respuesta del reintento correcto no incluye los errores de los intentos anteriores.

Reintentar una operación LRO

Si tienes una canalización de procesamiento del lado del cliente que detecta errores de LRO, no uses Cloud Logging. Como se muestra en Detalles de errores de operaciones de larga duración, los registros de errores de Cloud Logging de las operaciones de larga duración no son fiables y están incompletos. En su lugar, usa las técnicas que se describen en las siguientes secciones.

Reintentar operaciones de importación

Para detectar los datos que no se han importado, compare los datos importados en la API de Cloud Healthcare con los datos de origen en Cloud Storage. Puede importar datos con los siguientes métodos:

Usa un identificador único, como un número de historial médico (NHM) de un recurso Patient de FHIR, para comparar los datos.

Consulta Efectos de reintentar una LRO para ver los pasos que debes seguir al reintentar una operación de importación.

Si vuelves a ejecutar una importación, es posible que se vuelvan a crear recursos que hayas eliminado anteriormente. Veamos la siguiente situación:

Intentas importar 1.000.000 de recursos FHIR. 50.000 recursos fallan debido a errores de formato.
Pasas varios días corrigiendo los errores de formato. Durante ese tiempo, un paciente te pide que elimines sus registros.
Si vuelves a ejecutar la importación, corres el riesgo de recrear los datos del paciente que has eliminado.

Reintentar operaciones de exportación

Para detectar los datos que no se han exportado a BigQuery, escribe una secuencia de comandos para comparar los IDs únicos de los datos de origen con los datos exportados.

Puede exportar datos a BigQuery mediante los siguientes métodos:

Poner en cola y gestionar LROs

Si ejecutas operaciones de larga duración que procesan grandes volúmenes de datos para la incorporación o de forma periódica, implementa las siguientes técnicas de colas de operaciones de larga duración:

Limita el número de operaciones LRO simultáneas a un número pequeño, como 5. Puede ajustar este límite en función del tamaño y los tipos de operaciones de larga duración que ejecute.
Monitoriza la finalización de la operación de larga duración. Si se producen errores, vuelve a programar el LRO o resuélvelos por separado en tu canalización de procesamiento.
Resuelve automáticamente los errores de Gestión de errores de recursos cuando sea posible.
- Comprende el caso práctico de las importaciones de FHIR para determinar si debes ignorar los errores 409 ALREADY_EXISTS o realizar operaciones CRUD independientes para resolverlos. Como se muestra en los detalles de los errores de las operaciones de larga duración, puede que algunos errores 409 ALREADY_EXISTS no se registren en Cloud Logging. Si tu aplicación depende de los registros de errores, utiliza una de las técnicas que se describen en Reintentar una operación LRO.
- Para resolver algunos errores, pon en cola una LRO más pequeña para los datos que hayan provocado los errores o realiza operaciones CRUD independientes.
- Para resolver muchos errores, volver a ejecutar la operación de larga duración puede ser la opción más sencilla para asegurar la coherencia. Consulta los riesgos de volver a ejecutar una importación en datos eliminados en el artículo Reintentar operaciones de importación.
Detecta automáticamente si se requiere intervención humana para corregir errores. Deberías tener herramientas y manuales de operaciones para administradores de sistemas. Entre las tareas para solucionar errores se pueden incluir las siguientes:
- Reprogramar una LRO.
- Reprograma un subconjunto de datos de un LRO anterior.
- Examina los errores y corrige los elementos de datos que los hayan provocado. Esta tarea solo es posible si puedes determinar que se han registrado todos los errores de la operación de larga duración.
Determina las programaciones de las operaciones de larga duración. Puedes programar operaciones LRO para evitar que se ejecuten en las horas punta, cuando se estén ejecutando muchas operaciones CRUD. Para obtener más información, consulta Gestionar la cuota para maximizar el volumen de datos.

Monitorizar y recibir alertas

Crea y mantén procedimientos para monitorizar las LROs y resolver las alertas. Las alertas se deben principalmente a los estados de LRO y a problemas de colas. Los procedimientos deben abordar las siguientes situaciones:

Operaciones de larga duración que no se reintentan correctamente más veces de las que se han configurado.
Problemas que requieren la intervención humana para resolver un subconjunto de errores. Por ejemplo, si falla una operación de larga duración y el cliente no puede resolver los errores, es probable que se requiera la intervención humana. Consulta Cola y gestión de operaciones LRO para obtener más información sobre cómo resolver problemas que requieren intervención humana.
Colas que superan una longitud o crecen demasiado rápido.
No se cumplen los requisitos de las políticas, como un problema de permisos o una configuración incorrecta.
Comprobaciones de coherencia que muestran problemas sistémicos en varios LROs. Es posible que tengas varios LROs de desidentificación que esperen que el conjunto de datos de origen y el de destino tengan el mismo número de recursos FHIR. Si hay una discrepancia que aumenta con el tiempo, puede indicar que hay datos sin procesar.
Problemas con las cuotas de LRO. Para obtener más información, consulta Gestionar la cuota para maximizar el volumen de datos y Prácticas recomendadas para gestionar las cuotas.

Prácticas recomendadas para las operaciones de larga duración Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.