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 aplicaciones de servicio (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 de 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 la API de Cloud Healthcare para crear, leer, actualizar delete (CRUD) que consumen los siguientes tipos de la 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 a las siguientes restricciones, en especial cuando se procesan grandes volúmenes de datos:

Limitaciones de cuotas
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 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 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 grandes lotes de datos en varios LRO, intenta mantener baja la cantidad de particiones.

Integridad referencial de FHIR

La fhirStores.import no considera la disableReferentialIntegrity del lugar. Esto te permite importar datos con interdependencias arbitrarias que no requieren ordenamiento o agrupación, lo que aumenta la capacidad de procesamiento de datos. Si los datos de entrada contiene referencias no válidas o, si no se pueden importar algunos recursos de FHIR, podría infringir el estado 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
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 ver más 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 casos clínicos eventos, como la creación o eliminación de un recurso de atención médica. Para obtener una lista de métodos que envían notificaciones de Pub/Sub, consulta Cómo 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 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, especialmente si la LRO procesa grandes volúmenes de datos y produce 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 ocurrir retrasos en los resultados de la búsqueda debido a la indexación de la búsqueda asíncrona. 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 los datos ya que procesan grandes cantidades de datos rápido y evitan los aumentos repentinos de carga. Para almacenas 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.
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, los límites de frecuencia de la API de Cloud Healthcare producen y puede reducir la capacidad de procesamiento de LRO. La API de Cloud Healthcare se aplica automáticamente conserva los recursos de Google Cloud para que la cantidad de LRO permanezca dentro los límites de los 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 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 debe hacer lo siguiente:

Inicia un proceso de control.
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 los gastos generales, una LRO que procese una pequeña cantidad de datos podría dedicar la mayor parte de su tiempo a asignar grupos de trabajadores y limpiar. y configurar los 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.
Estás importando 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. Puedes ver un el estado de la LRO sondeando su ID. Después del cuando 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 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 cuando hayan terminado. 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, 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.
- 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 tarda varias horas tarda varios días y no ha muestre un estado de falla, quizás intervenga una persona. Para más información sobre cuándo puede 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 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.

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 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 registros 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 lentamente, 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 reintentar 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 fhirStores.import termina con errores porque algunos de los recursos de FHIR que trató de 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 un reintento se realiza correctamente, el campo metadata.counter.failure no incluye errores de operaciones anteriores. Esto podría provocar un recuento de errores incorrecto de un reintento exitoso no incluye errores de intentos anteriores.

Vuelve 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 los detalles de errores de LRO, los registros de errores de Cloud Logging para LRO son incompletos y poco confiables. Usa el en las secciones siguientes.

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 sus 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) de un recurso de paciente de FHIR para comparar los datos.

Consulta Efectos de reintentar una LRO para conocer los pasos que debes seguir en los siguientes casos: reintentar una operación de importación.

Volver a ejecutar una importación puede volver a crear los recursos que borraste anteriormente. Reflexiona 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 elimines sus registros.
Si vuelves a ejecutar la importación, corres el riesgo de recrear los datos del paciente que 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:

Pon en cola y administra LRO

Si ejecutas LRO que procesan grandes volúmenes de datos para la integración o de forma periódica implementar 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 las LRO que ejecutas.
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 independientes 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 depende de registros de errores, usa una de las técnicas Reintenta una LRO.
- Para corregir algunos errores, pon en cola LRO de los datos que encontraron los errores o realizan distintas operaciones CRUD.
- 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 elementos de datos que encontraron errores. Esta tarea solo es posible si puedes determinar que todos los errores de la LRO se registraron.
Determina los programas de la LRO. Puedes programar LRO para evitar que se ejecuten en las horas pico cuando se ejecutan muchas operaciones de CRUD. Para Para obtener más información, consulta Administra la cuota para maximizar la capacidad de procesamiento de los datos.

Supervisa y recibe alertas

Crear y mantener procedimientos para supervisar las LRO y resolver alertas Alertas de Google se deben principalmente a los estados de LRO y a las colas problemas. 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 la sección sobre cómo 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 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 alguna discrepancia que crece 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.