Esta página descreve as práticas recomendadas para executar e gerenciar operações de longa duração (LROs, na sigla em inglês) na API Cloud Healthcare. Para uma visão geral de LROs Na API Cloud Healthcare, consulte Como gerenciar operações de longa duração.
Propriedades de LRO
As seções a seguir se aplicam aos métodos listados em Métodos que retornam um LRO.
Impacto na cota
Os LROs não compartilham a cota com os métodos de criar, ler, atualizar e excluir (CRUD) da API Cloud Healthcare que consomem os seguintes tipos de cota:
A cota de LRO é calculada usando a propriedade fhir_store_lro_ops
e dicom_store_lro_ops
métricas.
A API Cloud Healthcare limita o número de LROs que podem ser executadas simultaneamente em um projeto do Google Cloud. Para mais informações, consulte Limites no número de LROs.
Capacidade de processamento de dados
Os métodos de LRO geralmente atingem uma capacidade de processamento de dados maior
ou métodos CRUD equivalentes. Por exemplo, a importação de instâncias DICOM com dicomStores.import
normalmente tem um desempenho melhor do que armazenar as instâncias individualmente com dicomStores.storeInstances
.
A execução de várias LROs simultaneamente pode não aumentar a capacidade de dados devido às seguintes restrições, especialmente ao processar grandes volumes de dados:
- Limitações de cota
- Contenção de recursos
- Outro tráfego que seu projeto do Google Cloud envia para a API Cloud Healthcare enquanto uma LRO é executada
Para ter a capacidade máxima de dados ao executar LROs, considere o seguinte:
- Pequenos lotes de importação e exportação geralmente têm baixa taxa de transferência devido ao overhead.
- As LROs executam e consomem a cota separadamente de outras operações da API Cloud Healthcare.
- Cada LRO tem uma capacidade máxima de processamento.
- LROs simultâneas no mesmo recurso podem causar contenção de bloqueio.
- A API Cloud Healthcare limita o número de LROs que podem ser executadas simultaneamente em um projeto do Google Cloud. Para mais informações, consulte Limites no número de LROs.
Planeje o número de LROs que seu caso de uso exige. Se você precisar particionar grandes lotes de dados em várias LROs, tente manter o número de partições baixo.
Integridade referencial de FHIR
O fhirStores.import
método não considera a
disableReferentialIntegrity
do ambiente. Isso permite importar dados com dependências arbitrárias que não
exigem ordenação ou agrupamento, o que aumenta a capacidade de dados. Se os dados de entrada
contiver referências inválidas ou se alguns recursos do FHIR não forem importados, o FHIR
estado do repositório pode violar
integridade referencial.
Para usar fhirStores.import
, seu aplicativo cliente precisa
para garantir que as referências de recursos FHIR sejam válidas verificando o seguinte:
- Os dados e a formatação do recurso FHIR estão corretos
- Qualquer erro ocorrido durante a importação é gerenciado
Para aplicar a integridade referencial, use fhir.create
ou fhir.executeBundle
em vez de fhirStores.import
. Para mais
informações, consulte Importar dados do FHIR em vez de executar pacotes.
Notificações do Pub/Sub
Alguns métodos da API Cloud Healthcare enviam notificações do Pub/Sub para como a criação ou exclusão de um recurso de saúde. Para conferir uma lista de métodos que enviam notificações do Pub/Sub, consulte Como configurar notificações do Pub/Sub.
Os métodos de importação a seguir não enviam notificações do Pub/Sub:
Se partes do seu aplicativo exigirem uma notificação quando um a importação terminar, use outro método de notificação que possa listar os dados em durante a importação.
Limites de tratamento de erros
A API Cloud Healthcare pode não registrar todos os erros em uma LRO, especialmente se a LRO processar grandes volumes de dados e produzir muitos erros. Implementação uma maneira de rastrear o processamento e os erros da LRO separadamente. Para mais informações, consulte Como processar erros de recursos.
Indexação de dados e pesquisa
Podem ocorrer atrasos nos resultados da pesquisa devido à indexação assíncrona da pesquisa. Se um LRO criar ou atualizar um recurso do FHIR, pode levar mais tempo para que as mudanças fiquem disponíveis nos resultados da pesquisa.
Por exemplo, uma pesquisa de recursos de paciente em um armazenamento de FHIR pode não retornar todos os resultados imediatamente após uma operação de importação de FHIR.
Ordem de execução
As LROs são programadas com base na disponibilidade de recursos do Google Cloud. O pedido em que as LROs são executadas e concluídas podem não corresponder à ordem em que foram solicitados.
Evite solicitações de importação e exportação pequenas
Nesta seção, descrevemos as limitações da LRO ao processar pequenos volumes de dados.
LROs retornados das operações de importação e exportação ajudam a escalonar a capacidade de processamento de dados processando grandes quantidades de dados rapidamente e evitando picos de carga. Para armazenar pequenas quantidades de dados, use outra técnica em Práticas recomendadas de armazenamento de dados.
Limites para o número de LROs
A API Cloud Healthcare limita o número de LROs que podem ser executadas simultaneamente em um projeto do Google Cloud. O limite é baseado no seguinte:
- O tipo de LRO.
- A quantidade de recursos do Google Cloud alocados para o LRO. Isso se baseia do tamanho dos dados de entrada.
Se você executar muitas LROs, os limites de taxa da API Cloud Healthcare vão gerar erros e podem reduzir a taxa de transferência de LROs. A API Cloud Healthcare automaticamente preserva os recursos do Google Cloud para que o número de LROs permaneça dentro os limites de recursos.
LROs são processos em segundo plano. Portanto, se a carga interfira em processos de maior prioridade, como CRUD a API Cloud Healthcare, a API Cloud Healthcare pode reduzir a LRO e aumentar a capacidade de processamento. Isso garante que os processos de maior prioridade estejam disponíveis.
Alocação de recursos e overhead de limpeza
Quando uma LRO é iniciada, a API Cloud Healthcare aloca recursos. Isso pode levar vários minutos, porque a API Cloud Healthcare precisa fazer o seguinte:
- Iniciar um processo de controlador.
- Alocar workers de um pool.
- Determine o tamanho dos dados de entrada.
- Comece a alocar trabalho em grande escala.
Interromper e limpar um LRO também pode levar vários minutos.
Devido à sobrecarga, um LRO que processa uma pequena quantidade de dados pode passar a maior parte do tempo alocando pools de workers e limpando os recursos.
Se você tiver muitas dessas LROs, poderá encontrar uma taxa de transferência de dados menor, porque é mais provável que atenda aos limites de cota do seu projeto do Google Cloud.
Limites de solicitação de cota de LRO
Antes de solicitar mais cota de LRO, implemente o Práticas recomendadas para o gerenciamento de cotas. Se você ainda precisar de mais cota, entre em contato com o Google Cloud Customer Care. Para fazer uma solicitação, consulte Práticas recomendadas para solicitar cota adicional.
Talvez seja necessário aumentar a cota se os dados de entrada forem grandes. Por exemplo:
- Você está importando instâncias DICOM que têm vários petabytes (PB) de tamanho.
- Você está importando dezenas de bilhões de recursos do FHIR.
Status da LRO e estados de falha
Quando você inicia uma LRO, a resposta contém um ID exclusivo. É possível consultar o status da LRO pesquisando o ID. Depois que a LRO termina, ela tem um dos seguintes estados:
- Concluído sem erros
- Concluída com alguns erros
- Falha ao concluir, mas possivelmente produziu uma saída parcial antes da falha
O exemplo de JSON a seguir descreve a resposta retornada quando uma solicitação termina em:
{ "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 conferir o status de uma LRO, listar LROs e cancelar LROs, consulte Gerenciar operações de longa duração.
Gerenciar status de LRO e estados de falha
Para gerenciar o status de LRO e os estados de falha, siga estas práticas recomendadas:
- Consultar as LROs para saber o status e verificar quando elas forem concluídas. Para pesquisar uma LRO, chame repetidamente o
método
projects.locations.datasets.operations.get
até que a operação seja concluída. Use um recuo entre cada solicitação de pesquisa. Por exemplo, pesquise a cada 10 segundos. Quando a resposta contém"done": true
, o A LRO foi concluída. Depois que uma LRO for concluída, verifique se a resposta contém um campo
error
. Se isso acontecer, determine se a operação será repetida com base no seguinte:- O código de erro. Consulte Como solucionar problemas de LROs para códigos de erro e ações recomendadas.
- O número de novas tentativas que já ocorreram.
- O tempo entre o início da LRO e o momento em que o erro ocorreu. Por exemplo, se uma LRO que normalmente leva várias horas leva vários dias e não retornou um status de falha, talvez seja necessário que um humano intervenha. Para mais informações sobre quando a intervenção humana pode ser necessária, consulte Planejar estados de erro finais.
Para saber como repetir uma LRO, consulte Colocar uma LRO na fila.
Se você não estiver tentando a LRO novamente, consulte o campo
metadata.counter.failure
para ver se ocorreram erros na recursos específicos. Talvez seja possível processar os recursos individualmente. Para mais informações, consulte Como lidar com erros de recursos.
Processar erros de recursos
Uma LRO pode terminar com erros. Os erros na resposta da LRO seguem o modelo de erro do Google Cloud. A resposta da LRO inclui um link para o Cloud Logging para mais informações.
Detalhes do erro de LRO
Os erros de LRO no Cloud Logging têm as seguintes propriedades:
O registro de erros do Cloud Logging não contém o ID da LRO. Use os campos
operation.id
eoperation.producer
para encontrar o status e os erros da LRO. Por exemplo, as LROs invocadas pelo métodoprojects.locations.datasets.fhirStores.import
contêmimport_fhir
no campooperation.producer
.Se várias LROs tiverem os mesmos
operation.id
eoperation.producer
, use os carimbos de data/horacreateTime
eendTime
para identificar a LRO correta.Nem todos os erros de LRO estão disponíveis no Cloud Logging. O
metadata.counter.failure
pode exceder o número de erros reais registrados pelos seguintes motivos:- Limitações de cota do Cloud Logging
- Disponibilidade do serviço do Cloud Logging
- Limites de registro de LRO
Por exemplo, se uma LRO importar 10 milhões de recursos FHIR e 50% deles erros de formatação, apenas algumas centenas ou alguns milhares de erros podem ser registrados devido à limitação de taxa e às cotas do Cloud Logging.
O número de erros registrados também varia de acordo com o tempo a LRO é executada quando encontra altas taxas de erro. Se a LRO for executada lentamente, pode mostrar mais erros no Cloud Logging porque os erros foram distribuídos por muito tempo e não estavam sujeitas à limitação de taxa.
Efeitos da nova tentativa de uma LRO
Se uma LRO encontrar um erro e um aplicativo cliente tentar de novo automaticamente a operação com os mesmos dados, essa nova tentativa pode causar mais erros.
Considere um cenário em que uma LRO fhirStores.import
termina com erros
porque alguns dos recursos FHIR que ela tentou importar eram inválidos.
Tentar novamente a importação automaticamente com os mesmos dados pode
gerar muitos erros 409 ALREADY_EXISTS
porque alguns recursos do FHIR foram
importados na operação original. Se você consultar uma LRO e encontrar uma operação de criação com falha, não tente novamente automaticamente. Uma pessoa precisa analisar
os erros de 409 ALREADY_EXISTS
.
Se uma nova tentativa for bem-sucedida, o campo metadata.counter.failure
não incluirá
erros de operações anteriores. Isso pode causar uma contagem incorreta de erros porque
a resposta da nova tentativa não inclui erros das tentativas anteriores.
Tentar novamente uma LRO
Se você tiver um pipeline de processamento do lado do cliente que detecta erros de LRO, não use o Cloud Logging. Como mostrado em Detalhes do erro de LRO, os registros de erros do Cloud Logging para LROs são incompletos e não confiáveis. Use o técnicas nas seções a seguir.
Tentar novamente as operações de importação
Para detectar dados que não foram importados, compare os dados importados na API Cloud Healthcare com os dados de origem no Cloud Storage. É possível importar dados usando os seguintes métodos:
projects.locations.datasets.fhirStores.import
projects.locations.datasets.dicomStores.import
projects.locations.datasets.hl7V2Stores.import
Use um identificador exclusivo, como um número de registro médico (MRN, na sigla em inglês) para um recurso FHIR Patient, para comparar os dados.
Consulte Efeitos da repetição de uma LRO para saber as etapas a serem seguidas e tentando uma operação de importação.
Executar novamente uma importação pode recriar recursos excluídos anteriormente. Considere este cenário:
- Você tenta importar 1.000.000 de recursos FHIR. 50.000 recursos falhar devido a erros de formatação.
- Você passa vários dias corrigindo os erros de formatação. Durante esse período, um paciente solicita a remoção dos registros dele.
- Se você executar a importação novamente, corre o risco de recriar os dados do paciente que que você excluiu.
Repetir operações de exportação
Para detectar os dados que não foram exportados para o BigQuery, escreva um script para comparar IDs exclusivos nos dados de origem com os dados exportados.
É possível exportar dados para o BigQuery usando os seguintes métodos:
projects.locations.datasets.fhirStores.export
projects.locations.datasets.dicomStores.export
projects.locations.datasets.hl7V2Stores.export
Enfileirar e gerenciar LROs
Se você executa LROs que processam grandes volumes de dados para integração ou em cronograma, implemente as seguintes técnicas de enfileiramento de LRO:
- Limite as LROs simultâneas a um número pequeno, como
5
. Você pode ajustar esse limite dependendo do tamanho e dos tipos de LROs que você executa. - Monitore a conclusão da LRO. Se ocorrerem erros, reprograme a LRO ou resolva o separadamente no pipeline de processamento.
Resolva automaticamente os erros em Como lidar com erros de recursos quando possível.
Entenda o caso de uso das importações do FHIR para determinar se é necessário ignorar erros de
409 ALREADY_EXISTS
ou realizar operações CRUD separadas para resolvê-los. Conforme mostrado nos detalhes do erro da LRO, alguns erros409 ALREADY_EXISTS
podem não ser registrados no Cloud Logging. Se seu aplicativo depende de registros de erros, use uma das técnicas em Tente fazer uma LRO novamente.Para resolver alguns erros, coloque em fila um LRO dos dados que encontraram os erros ou realizar operações CRUD.
Para resolver muitos erros, executar a LRO novamente pode ser a opção mais simples para garantir a consistência. Consulte Repetir operações de importação para saber os riscos de executar novamente uma importação em dados excluídos.
Detectar automaticamente se a intervenção humana é necessária para corrigir erros. Ter acesso a ferramentas e manuais operacionais para administradores de sistema. As tarefas para resolver erros podem incluir:
- Reprograme uma LRO.
- Reprograme um subconjunto de dados de uma LRO anterior.
- Examine os erros e resolva os elementos de dados individuais que encontraram erros. Essa tarefa só é possível é possível determinar que todos os erros na LRO foram registrados.
Determinar programações de LRO. Você pode programar LROs para evitar a execução em horários de pico, quando muitas operações CRUD estão em execução. Para mais informações, consulte Gerenciar a cota para maximizar a taxa de transferência de dados.
Monitorar e receber alertas
Crie e mantenha procedimentos para monitorar LROs e resolver alertas. Os alertas são causados principalmente por problemas de status de LRO e de enfileiramento. Os procedimentos devem abordar as seguintes situações:
- LROs que tentam novamente mais vezes do que o configurado.
- São problemas que exigem intervenção humana para resolver um subconjunto de erros. Por exemplo, se uma LRO falhar e o cliente não conseguir resolver os erros, provavelmente será necessária uma intervenção humana. Consulte Enfileirar e gerenciar LROs para mais informações sobre como resolver problemas que exigem intervenção humana.
- Filas que excedem um tamanho ou aumentam muito rapidamente.
- Requisitos da política não atendidos, como um problema de permissões ou uma configuração incorreta.
- Verificações de consistência que mostram problemas sistêmicos em várias LROs. Você pode ter várias LROs de desidentificação que esperam os conjuntos de dados de origem e destino. tenham o mesmo número de recursos FHIR. Se houver uma discrepância que cresce com o tempo, isso pode indicar dados não processados.
- Problemas de cota de LRO. Para mais informações, consulte Gerenciar a cota para maximizar a taxa de transferência de dados e Práticas recomendadas para gerenciamento de cota.