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

Prácticas recomendadas para las 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 Cómo administrar operaciones de larga duración.

Propiedades de LRO

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

Impacto en la cuota

Las LRO no comparten la cuota 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 cuota:

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 se pueden ejecutar de forma simultánea 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 de LRO suelen lograr 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 almacenar las instancias de forma individual con dicomStores.storeInstances.

Ejecutar varias LRO de forma simultánea podría no aumentar 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 baja capacidad de procesamiento debido a la sobrecarga.
Las LRO se ejecutan y consumen cuota por separado 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 causar contención de bloqueo.
La API de Cloud Healthcare limita la cantidad de LRO que se pueden ejecutar de forma simultánea 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 grandes lotes de datos en varios LRO, intenta mantener baja la cantidad de particiones.

Integridad referencial de FHIR

El método fhirStores.import no considera la configuración de disableReferentialIntegrity. Esto te permite importar datos con interdependencias arbitrarias que no requieren ordenamiento ni agrupación, lo que aumenta la capacidad de procesamiento de datos. Si los datos de entrada contienen referencias que no son válidas o si falla la importación de algunos recursos de FHIR, el estado del almacén de FHIR podría incumplir la integridad referencial.

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

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

Para aplicar la integridad referencial, usa fhir.create o fhir.executeBundle en lugar de fhirStores.import. Para obtener más información, consulta Importa datos de FHIR en lugar de ejecutar 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 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 una lista de 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 genera muchos errores. Implementa una forma de hacer un seguimiento del 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úsqueda

Pueden producirse demoras en los resultados de la búsqueda debido a la indexación asíncrona de la búsqueda. Si un LRO crea o actualiza un recurso de FHIR, es posible que debas esperar un tiempo adicional para que los cambios estén disponibles en los resultados de la búsqueda.

Por ejemplo, una búsqueda de recursos de pacientes en un almacén de FHIR podría 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 los recursos de Google Cloud. Es posible que el orden en el que se ejecutan y terminan las LRO no coincida con el orden en el que se solicitaron.

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

En esta sección, se describen las limitaciones de la 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 datos, ya que procesan grandes cantidades de datos con rapidez y evitan los picos de carga. Para 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 se pueden ejecutar de forma simultánea en un proyecto de Google Cloud. El límite se basa en lo siguiente:

El tipo de LRO.
Es la cantidad de recursos de Google Cloud asignados a la LRO. Esto se basa en el 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 las LRO. La API de Cloud Healthcare conserva automáticamente 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 las LRO interfiere con procesos de prioridad más alta, como las operaciones de CRUD, la API de Cloud Healthcare puede reducir la capacidad de procesamiento de las LRO. Esto garantiza que los procesos de mayor prioridad estén disponibles.

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 debe hacer lo siguiente:

Inicia un proceso de controlador.
Asignar trabajadores de un grupo de trabajadores
Determina 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, un LRO que procesa una pequeña cantidad de datos podría dedicar la mayor parte de su tiempo a asignar grupos de trabajadores y limpiar recursos.

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

Límites para solicitar la cuota de LRO

Antes de solicitar más cuota 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. Para realizar una solicitud, consulta Prácticas recomendadas para solicitar una cuota adicional.

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

Importas instancias de DICOM de varios petabytes (PB) de tamaño.
Importarás decenas de miles de millones de recursos de FHIR.

Estado de LRO y estados de error

Cuando inicias una LRO, la respuesta contiene un ID único. Para ver el estado de una LRO, sondea su ID. Después de que termina la LRO, tiene uno de los siguientes estados:

Se completó correctamente sin errores
Se completó correctamente con algunos errores
No se pudo finalizar, pero es posible que se haya generado un resultado 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 LRO y los estados de error

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

Sondea las LRO para obtener su estado y verificar cuándo terminan. Para sondear una LRO, llama de forma 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, significa que la LRO finalizó.
Después de que finalice una LRO, verifica si la respuesta contiene un campo error. Si es así, determina si debes reintentar la operación según lo siguiente:
- Es el código de error. Consulta Cómo solucionar problemas de LRO para obtener códigos de error y acciones recomendadas.
- Es la cantidad de reintentos que ya se produjeron.
- El tiempo entre el inicio de la LRO y el momento en que se produjo el error. Por ejemplo, si una LRO que normalmente tarda varias horas tarda varios días y no muestra un estado de error, es posible que desees que una persona intervenga. Para obtener más información sobre cuándo se puede requerir intervención humana, consulta Planifica los estados de error finales.
Consulta Cómo poner en cola una LRO para obtener información sobre cómo reintentar una LRO.
Si no vuelves a intentar 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 Cómo controlar los errores de recursos.

Cómo controlar 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 que se invocan desde el método projects.locations.datasets.fhirStores.import contienen import_fhir en el campo operation.producer.

Si varios LRO tienen el mismo operation.id y operation.producer, usa 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 la cantidad de errores reales registrados debido a lo siguiente:
- Limitaciones de la cuota de Cloud Logging
- Disponibilidad del servicio de Cloud Logging
- Límites de registro de LRO
Por ejemplo, si un LRO importa 10 millones de recursos de FHIR y el 50% de ellos tiene errores de formato, es posible que solo se registren unos cientos o unos 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 que se ejecuta la LRO cuando 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 extendieron durante un período prolongado y no estuvieron sujetos a la limitación de frecuencia.

Efectos de volver a intentar una LRO

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

Considera una situación en la que una LRO de fhirStores.import finaliza con errores porque algunos de los recursos de FHIR que intentó importar no eran válidos. Si vuelves a intentar la importación automáticamente con los mismos datos, es posible que se generen 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 que falló, no vuelvas a intentarlo automáticamente. Una persona debe revisar los errores 409 ALREADY_EXISTS.

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

Cómo volver a intentar una LRO

Si tienes una canalización de procesamiento del cliente que detecta errores de LRO, no uses Cloud Logging. Como se muestra en Detalles de los errores de las 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 de las siguientes secciones.

Vuelve a intentar las operaciones de importación

Para detectar los datos que no se pudieron importar, compara los datos importados en la API de Cloud Healthcare con sus datos de origen en Cloud Storage. Puedes importar datos con los siguientes métodos:

Usa un identificador único, como un número de registro médico (MRN) para un recurso de paciente de FHIR, para comparar los datos.

Consulta Efectos de volver a intentar una LRO para conocer los pasos que debes seguir cuando reintentes una operación de importación.

Si vuelves a ejecutar una importación, es posible que se vuelvan a crear los recursos que borraste anteriormente. Considera la siguiente situación:

Intentas 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 IDs únicos de los datos de origen con los datos exportados.

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

Cómo poner en cola y administrar las 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 una cantidad pequeña, como 5. Puedes ajustar este límite según el tamaño y los tipos de LRO que ejecutes.
Supervisa la finalización de la LRO. Si se producen errores, reprograma la LRO o resuelve los errores por separado en tu canalización de procesamiento.
Resuelve automáticamente los errores en Cómo manejar errores de recursos cuando sea posible.
- Comprende el caso de uso de las importaciones de FHIR para determinar si se deben ignorar los errores de 409 ALREADY_EXISTS o realizar operaciones CRUD separadas para resolverlos. Como se muestra en los detalles de los errores de LRO, es posible que algunos errores de 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 Cómo volver a intentar una LRO.
- Para resolver algunos errores, coloca 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 podría ser la opción más simple para garantizar la coherencia. Consulta Cómo reintentar 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 libros de jugadas operativos para los administradores del sistema. Las tareas para abordar los errores pueden incluir las siguientes:
- Reprograma una LRO.
- Reprograma 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 LRO. Puedes programar las LRO para evitar que se ejecuten en horas pico, cuando se ejecutan muchas operaciones de CRUD. Para obtener más información, consulta Administra la cuota para maximizar el rendimiento de los datos.

Supervisa y recibe alertas

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

LRO que reintenta más veces de las configuradas sin éxito
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 intervención humana. Consulta Cómo crear una fila y administrar las 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.
Verificaciones de coherencia que muestran problemas sistémicos en varios 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, es posible que se trate de datos sin procesar.
Problemas de cuota de LRO Para obtener más información, consulta Administra la cuota para maximizar el rendimiento de los datos y Prácticas recomendadas para la administración de cuotas.