Se usó la API de Cloud Translation para traducir esta página.

Prácticas recomendadas para operaciones de larga duración

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

Propiedades LRO

Las siguientes secciones se aplican a los métodos enumerados en Métodos que muestran una LRO.

Impacto de la cuota

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

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

La API de Cloud Healthcare limita la cantidad de LRO que pueden ejecutarse simultáneamente en un proyecto de Google Cloud. Para obtener más información, consulta Límites en la cantidad de LRO.

Capacidad de procesamiento de datos

Los métodos LRO generalmente logran una mayor capacidad de procesamiento de datos que los métodos CRUD equivalentes. Por ejemplo, importar instancias de DICOM con dicomStores.import suele tener un mejor rendimiento que el almacenamiento de las instancias de forma individual con dicomStores.storeInstances.

Es posible que la ejecución de varias LRO de forma simultánea no aumente la capacidad de procesamiento de datos debido a las siguientes restricciones, en especial cuando se procesan grandes volúmenes de datos:

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

Para obtener la máxima capacidad de procesamiento de datos cuando ejecutas LRO, ten en cuenta lo siguiente:

Los lotes pequeños de importación y exportación suelen tener una capacidad de procesamiento baja debido a la sobrecarga.
Las LRO ejecutan y consumen la cuota de manera independiente de otras operaciones de la API de Cloud Healthcare.
Cada LRO tiene una capacidad de procesamiento máxima.
Las LRO simultáneas en el mismo recurso pueden provocar una contención de bloqueo.
La API de Cloud Healthcare limita la cantidad de LRO que pueden ejecutarse simultáneamente en un proyecto de Google Cloud. Para obtener más información, consulta Límites en la cantidad de LRO.

Planifica la cantidad de LRO que requiere tu caso de uso. Si tienes que particionar lotes de datos grandes en varias LRO, intenta mantener una cantidad baja de particiones.

Integridad referencial de FHIR

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

Para usar fhirStores.import, la aplicación cliente debe asegurarse de que las referencias a los recursos de FHIR sean válidas mediante la verificación de lo siguiente:

Los datos y el formato de los recursos de FHIR son correctos
Los errores que ocurran durante la importación se administran

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

Notificaciones de Pub/Sub

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

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

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

Límites de manejo de errores

Es posible que la API de Cloud Healthcare no registre todos los errores en una LRO, en especial si esta procesa grandes volúmenes de datos y produce muchos errores. Implementa una forma de rastrear el procesamiento y los errores de LRO por separado. Para obtener más información, consulta Manejo de errores de recursos.

Indexación de datos y búsquedas

Pueden ocurrir retrasos en los resultados de la búsqueda debido a la indexación de la búsqueda asíncrona. Si una LRO crea o actualiza un recurso de FHIR, es posible que los cambios demoren más tiempo en estar disponibles en los resultados de la búsqueda.

Por ejemplo, una búsqueda de recursos de paciente en un almacén de FHIR puede no mostrar todos los resultados inmediatamente después de una operación de importación de FHIR.

Orden de ejecución

Las LRO se programan según la disponibilidad de recursos de Google Cloud. Es posible que el orden en que se ejecutan y finalizan las LRO no coincida con el orden en que se solicitaron.

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

En esta sección, se describen las limitaciones de LRO cuando se procesan volúmenes de datos pequeños.

Las LRO que se muestran en las operaciones de importación y exportación ayudan a escalar la capacidad de procesamiento de los datos, ya que procesan grandes cantidades de datos con rapidez y evitan los aumentos repentinos de carga. Si quieres almacenar pequeñas cantidades de datos, usa otra técnica en Prácticas recomendadas para almacenar datos.

Límites en la cantidad de LRO

La API de Cloud Healthcare limita la cantidad de LRO que pueden ejecutarse simultáneamente en un proyecto de Google Cloud. El límite se basa en lo siguiente:

El tipo de LRO.
La cantidad de recursos de Google Cloud asignados a la LRO. Esto depende del tamaño de los datos de entrada.

Si ejecutas demasiadas LRO, la API de Cloud Healthcare limita la frecuencia, genera errores y puede reducir la capacidad de procesamiento de la LRO. La API de Cloud Healthcare conserva de forma automática los recursos de Google Cloud para que la cantidad de LRO permanezca dentro de los límites de recursos.

Las LRO son procesos en segundo plano, por lo que, si la carga de LRO interfiere en los procesos de prioridad más alta, como las operaciones CRUD, la API de Cloud Healthcare puede reducir la capacidad de procesamiento de LRO. Esto garantiza que estén disponibles los procesos de mayor prioridad.

Sobrecarga de asignación y limpieza de recursos

Cuando se inicia una LRO, la API de Cloud Healthcare asigna recursos. Esto puede tardar varios minutos porque la API de Cloud Healthcare tiene que hacer lo siguiente:

Inicia un proceso de control.
Asigna trabajadores de un grupo de trabajadores.
Determinar el tamaño de los datos de entrada
Comienza a asignar trabajo a gran escala.

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

Debido a la sobrecarga, una LRO que procesa una pequeña cantidad de datos puede ocupar la mayor parte de su tiempo en asignar grupos de trabajadores y limpiar recursos.

Si tienes muchas de estas LRO, es posible que experimentes una capacidad de procesamiento de datos menor, ya que es más probable que alcances los límites de cuota de tu proyecto de Google Cloud.

Límites para solicitar cuota de LRO

Antes de solicitar una cuota mayor de LRO, implementa las Prácticas recomendadas para la administración de cuotas. Si aún necesitas más cuota, comunícate con Atención al cliente de Google Cloud. Si quieres realizar una solicitud, consulta Prácticas recomendadas para solicitar cuota adicional.

Es posible que necesites una cuota adicional si tus datos de entrada son grandes, por ejemplo:

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

Estado de LRO y estados de falla

Cuando inicias una LRO, la respuesta contiene un ID único. Para ver el estado de una LRO, sondea su ID. Una vez que finaliza la LRO, tiene uno de los siguientes estados:

Finalizó correctamente sin errores
Se completó correctamente con algunos errores
No se pudo finalizar, pero es posible que se genere una salida parcial antes de fallar.

En el siguiente ejemplo de JSON, se describe la respuesta que se muestra cuando finaliza una LRO:

{
  "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 LRO, enumerarlas y cancelarlas, consulta Administra operaciones de larga duración.

Administra el estado de la LRO y los estados de falla

Para administrar el estado de LRO y los estados de falla, sigue estas prácticas recomendadas:

Sondea las LRO para obtener su estado y verificar cuando hayan terminado. Para sondear una LRO, llama de manera reiterada al método projects.locations.datasets.operations.get hasta que finalice la operación. Usa una retirada entre cada solicitud de sondeo, por ejemplo, 10 segundos. Cuando la respuesta contiene "done": true, la LRO finalizó.
Después de que finaliza una LRO, verifica si la respuesta contiene un campo error. De ser así, determina si debes reintentar la operación de acuerdo con lo siguiente:
- El código de error. Consulta Solución de problemas de LRO para ver los códigos de error y las acciones recomendadas.
- La cantidad de reintentos que ya ocurrieron.
- El tiempo que transcurre entre el inicio de la LRO y el momento en que se produjo el error. Por ejemplo, si una LRO que normalmente demora varias horas tarda varios días y no muestra un estado de falla, es posible que desees que una persona intervenga. Para obtener más información sobre cuándo podría ser necesaria la intervención humana, consulta Planifica los estados de error finales.
Consulta Poner en cola una LRO para obtener información sobre cómo reintentar una LRO.
Si no estás volviendo a ejecutar la LRO, consulta el campo metadata.counter.failure para ver si se produjeron errores en recursos específicos. Es posible que puedas procesar los recursos de forma individual. Para obtener más información, consulta Maneja errores de recursos.

Maneja errores de recursos

Una LRO puede finalizar con errores. Los errores en la respuesta de la LRO siguen el modelo de error de Google Cloud. La respuesta de la LRO incluye un vínculo 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 encontrar el estado y los errores de la LRO. Por ejemplo, las LRO invocadas desde el método projects.locations.datasets.fhirStores.import contienen import_fhir en el campo operation.producer.

Si varias LRO tienen el mismo operation.id y operation.producer, usa las marcas de tiempo createTime y endTime para identificar la LRO correcta.
No todos los errores de LRO están disponibles en Cloud Logging. El campo metadata.counter.failure puede exceder la cantidad de errores reales registrados debido a lo siguiente:
- Limitaciones de cuota de Cloud Logging
- Disponibilidad del servicio de Cloud Logging
- Límites de registros de LRO
Por ejemplo, si una LRO importa 10 millones de recursos FHIR y el 50% de ellos tiene errores de formato, solo se pueden registrar cientos o miles de errores debido al límite de frecuencia y las cuotas de Cloud Logging.

La cantidad de errores registrados también varía según el tiempo durante el que se ejecuta la LRO mientras se encuentran tasas de error altas. Si la LRO se ejecuta con lentitud, es posible que muestre más errores en Cloud Logging, ya que los errores se repartieron durante mucho tiempo y no estaban sujetos a límites de frecuencia.

Efectos de reintentar una LRO

Si una LRO encuentra un error y una aplicación cliente vuelve a intentar la operación de forma automática con los mismos datos, el reintento puede causar más errores.

Considera una situación en la que una LRO fhirStores.import termina con errores porque algunos de los recursos de FHIR que intentó importar no eran válidos. Volver a intentar la importación de forma automática con los mismos datos puede generar muchos errores 409 ALREADY_EXISTS porque algunos recursos de FHIR se importaron en la operación original. Si consultas una LRO y encuentras una operación de creación con errores, no vuelvas a intentarlo automáticamente. Una persona debe revisar los errores 409 ALREADY_EXISTS.

Si un reintento se realiza correctamente, el campo metadata.counter.failure no incluye los errores de las operaciones anteriores. Esto puede generar un recuento de errores incorrecto porque la respuesta del reintento exitoso no incluye errores de intentos anteriores.

Vuelve a intentar una 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 los detalles de errores de LRO, los registros de errores de Cloud Logging para las LRO no son confiables 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 pudieron importar, compara los datos importados en la API de Cloud Healthcare con los datos de origen en Cloud Storage. Puedes importar datos con los siguientes métodos:

Usa un identificador único, como un número de historia clínica (MRN) para un recurso de paciente de FHIR, para comparar los datos.

Consulta Efectos de reintentar una LRO para conocer los pasos que debes seguir cuando se reintenta una operación de importación.

Volver a ejecutar una importación puede volver a crear los recursos que borraste anteriormente. Considera la siguiente situación:

Intenta importar 1,000,000 de recursos de FHIR. 50,000 recursos fallan debido a errores de formato.
Pasas varios días corrigiendo los errores de formato. Durante ese tiempo, un paciente solicita que quites sus registros.
Si vuelves a ejecutar la importación, corres el riesgo de volver a crear los datos del paciente que borraste.

Vuelve a intentar las operaciones de exportación

Para detectar los datos que no se pudieron exportar a BigQuery, escribe una secuencia de comandos para comparar los ID únicos en los datos de origen con los datos exportados.

Puedes exportar datos a BigQuery con los siguientes métodos:

Pon en cola y administra LRO

Si ejecutas LRO que procesan grandes volúmenes de datos para la integración o en un programa regular, implementa las siguientes técnicas de cola de LRO:

Limita las LRO simultáneas a un número pequeño, como 5. Puedes ajustar este límite según el tamaño y los tipos de LRO que ejecutes.
Supervisa la finalización de LRO. Si se producen errores, reprograma la LRO o resuelve los errores por separado en la canalización de procesamiento.
Cuando sea posible, resuelve de forma automática los errores en Manejo de errores de recursos.
- Comprende el caso práctico de las importaciones de FHIR para determinar si se deben ignorar los errores 409 ALREADY_EXISTS o realizar operaciones CRUD independientes para resolverlos. Como se muestra en los detalles de error de LRO, es posible que algunos errores 409 ALREADY_EXISTS no se registren en Cloud Logging. Si tu aplicación se basa en registros de errores, usa una de las técnicas que se indican en Reintenta una LRO.
- A fin de resolver algunos errores, pon en cola una LRO más pequeña para los datos que encontraron los errores o realiza operaciones CRUD separadas.
- Para resolver muchos errores, volver a ejecutar la LRO puede ser la opción más simple para garantizar la coherencia. Consulta Reintentar las operaciones de importación para conocer los riesgos de volver a ejecutar una importación en datos borrados.
Detecta automáticamente si se requiere intervención humana para abordar los errores. Debes tener herramientas y guías operativas para los administradores del sistema. Las tareas para abordar errores pueden incluir lo siguiente:
- Reprograma una LRO.
- Reprogramar un subconjunto de datos de una LRO anterior.
- Examina los errores y aborda los elementos de datos individuales que encontraron errores. Esta tarea solo es posible si puedes determinar que se registraron todos los errores en la LRO.
Determina los programas de la LRO. Puedes programar las LRO para evitar que se ejecuten en las horas pico cuando se ejecutan muchas operaciones de CRUD. Si quieres obtener más información, consulta Administra la cuota para maximizar la capacidad de procesamiento de datos.

Supervisa y recibe alertas

Crear y mantener procedimientos para supervisar las LRO y resolver alertas Las alertas se deben principalmente a estados de LRO y problemas de queueing. Los procedimientos deben abordar las siguientes situaciones:

LRO que fallan más veces de lo que están configuradas para reintentar
Problemas que requieren intervención humana para resolver un subconjunto de errores. Por ejemplo, si falla una LRO y el cliente no puede resolver los errores, es probable que se requiera la intervención humana. Consulta Poner en cola y administrar LRO para obtener más información sobre cómo resolver problemas que requieren intervención humana.
Colas que superan una longitud o que aumentan demasiado rápido.
No se cumplen los requisitos de la política, como un problema de permisos o una configuración incorrecta.
Verificaciones de coherencia que muestran problemas sistémicos en varias LRO Es posible que tengas varias LRO de desidentificación que esperan que el conjunto de datos de origen y el de destino tengan la misma cantidad de recursos de FHIR. Si hay una discrepancia que aumenta con el tiempo, podría indicar que hay datos sin procesar.
Problemas de cuota de LRO. Si quieres obtener más información, consulta Administra la cuota para maximizar la capacidad de procesamiento de datos y Prácticas recomendadas para la administración de cuotas.