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 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 LRO generalmente logran una mayor capacidad de procesamiento de datos que
equivalentes de CRUD. 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
.
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 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 ejecutes LRO, considera lo siguiente: lo siguiente:
- Los lotes pequeños de importación y exportación suelen tener una capacidad de procesamiento baja debido a 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 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 debes particionar lotes de datos grandes en varias LRO, intenta mantener una cantidad baja de particiones.
Integridad referencial de FHIR
El 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 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 necesita
para asegurarte de que las referencias a los recursos de FHIR sean válidas, verifica 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 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 hay partes de la aplicación que requieren una notificación cuando se finaliza la 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, especialmente si la LRO procesa grandes volúmenes de datos y produce muchos errores. Implementación 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 lleve más tiempo antes de que estén disponibles en los resultados de la búsqueda.
Por ejemplo: es posible que una búsqueda de recursos de pacientes en un almacén de FHIR no muestre todos los resultados de inmediato 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. El pedido en el que las LRO se ejecutan y finalizan podría no coincidir con el orden en que que se solicitaron.
Evita las solicitudes de importación y exportación pequeñas
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 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 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 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 realizar las siguientes acciones:
- 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 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 encuentres y tiene menos capacidad de procesamiento de datos, ya que es más probable que cumplas límites de cuota del proyecto.
Límites para solicitar cuota de LRO
Antes de solicitar más cuota de LRO, implementa el 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 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. Puedes ver un el estado de la LRO sondeando su ID. Después de que termina 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 una LRO termina:
{ "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 los estados de LRO y de falla, sigue estas prácticas recomendadas:
- Sondea las LRO para obtener su estado y verificar cuando hayan terminado. Para sondear una LRO, llama repetidamente a
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
. 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 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 Maneja 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 el Campos
operation.id
yoperation.producer
para encontrar el estado de la LRO y errores. Por ejemplo, las LRO invocadas desde el métodoprojects.locations.datasets.fhirStores.import
contienenimport_fhir
en el campooperation.producer
.Si varias LRO tienen los mismos
operation.id
yoperation.producer
, Usa las marcas de tiempocreateTime
yendTime
para identificar la LRO correcta.No todos los errores de LRO están disponibles en Cloud Logging. El
metadata.counter.failure
podría superar 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 de FHIR y el 50% de ellos tienen errores de formato, solo se pueden registrar cientos o miles de errores. debido al límite de frecuencia y a las cuotas de Cloud Logging.
La cantidad de errores registrados también varía según la duración la LRO se ejecuta y encuentra tasas de error altas. Si la LRO funciona lentamente, Es posible que muestre más errores en Cloud Logging porque los errores se propagaron 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 intentarlo 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.
Volver a intentar la importación automáticamente con los mismos datos podría
generar muchos errores 409 ALREADY_EXISTS
porque algunos recursos de FHIR
importados en la operación original. Si consultas una LRO y encuentras un error
crear, no vuelvas a intentarlo automáticamente. Una persona debería revisar
409 ALREADY_EXISTS
de errores.
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.
Cómo volver a intentar una LRO
Si tienes una canalización de procesamiento del lado del cliente que detecta la 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. 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 a sus datos de origen en Cloud Storage. Puedes importar datos con los siguientes métodos:
projects.locations.datasets.fhirStores.import
projects.locations.datasets.dicomStores.import
projects.locations.datasets.hl7V2Stores.import
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 quites 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 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:
projects.locations.datasets.fhirStores.export
projects.locations.datasets.dicomStores.export
projects.locations.datasets.hl7V2Stores.export
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 LRO. Si se producen errores, reprograma la LRO o resuelve el errores por separado en tu canalización de procesamiento.
Resolver automáticamente los errores en Manejo de errores de recursos cuando sea posible.
Comprender el caso de uso de las importaciones de FHIR para determinar si se debe ignora los errores
409 ALREADY_EXISTS
o realiza CRUD independientes. las operaciones para resolver los errores. Como se muestra en los detalles de error de LRO, Es posible que algunos errores409 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 sencilla y 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 contar con herramientas y guías operativas para administradores de sistemas. Las tareas para abordar errores pueden incluir lo siguiente:
- 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 se registraron todos los errores en la LRO.
Determina los programas de la LRO. Puedes programar las LRO para evitar que se ejecuten en 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 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, la intervención humana es probable que se requiera. 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 que aumentan demasiado rápido.
- No se cumplen los requisitos de la política, por ejemplo, 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 las LRO de desidentificación que esperan el conjunto de datos de origen y el de destino. la misma cantidad de recursos 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.