Esta página foi traduzida pela API Cloud Translation.

Práticas recomendadas para operações de longa duração

Esta página descreve as práticas recomendadas para executar e gerir operações de longa duração (LROs) na Cloud Healthcare API. Para uma vista geral das LROs na Cloud Healthcare API, consulte o artigo Gerir operações de longa duração.

Propriedades do LRO

As secções seguintes aplicam-se aos métodos indicados em Métodos que devolvem um LRO.

Impacto na quota

As LROs não partilham a quota com os métodos de criação, leitura, atualização e eliminação (CRUD) da API Cloud Healthcare que consomem os seguintes tipos de quota:

A quota de LRO é calculada com base nas métricas fhir_store_lro_ops e dicom_store_lro_ops.

A Cloud Healthcare API limita o número de LROs que podem ser executados em simultâneo num Google Cloud projeto. Para mais informações, consulte o artigo Limites no número de LROs.

Débito de dados

Normalmente, os métodos LRO alcançam um débito de dados mais elevado do que os métodos CRUD equivalentes. Por exemplo, a importação de instâncias DICOM com dicomStores.import tem normalmente um desempenho superior ao do armazenamento das instâncias individualmente com dicomStores.storeInstances.

A execução de várias LROs em simultâneo pode não aumentar a taxa de transferência de dados devido às seguintes restrições, especialmente quando processa grandes volumes de dados:

Limitações de quota
Conflito de recursos
Outro tráfego que o seu Google Cloud projeto envia para a Cloud Healthcare API enquanto um LRO é executado

Para uma taxa de transferência de dados máxima ao executar LROs, considere o seguinte:

Normalmente, os pequenos lotes de importação e exportação têm um débito baixo devido aos custos gerais.
As LROs são executadas e consomem quotas separadamente de outras operações da Cloud Healthcare API.
Cada LRO tem um débito máximo.
As LROs concorrentes no mesmo recurso podem causar contenção de bloqueios.
A Cloud Healthcare API limita o número de LROs que podem ser executados em simultâneo num Google Cloud projeto. Para mais informações, consulte o artigo Limites no número de LROs.

Planeie o número de LROs que o seu exemplo de utilização requer. Se tiver de particionar grandes lotes de dados em vários LROs, tente manter o número de partições baixo.

Integridade referencial FHIR

O método fhirStores.import não considera a definição disableReferentialIntegrity. Isto permite-lhe importar dados com interdependências arbitrárias que não requerem ordenação nem agrupamento, o que aumenta a taxa de transferência de dados. Se os dados de entrada contiverem referências inválidas ou se alguns recursos FHIR não forem importados, o estado do repositório FHIR pode violar a integridade referencial.

Para usar a API fhirStores.import, a sua aplicação cliente tem de garantir que as referências de recursos FHIR são válidas verificando o seguinte:

Os dados e a formatação dos recursos FHIR estão corretos
Todos os erros que ocorrem durante a importação são geridos

Para aplicar a integridade referencial, use fhir.create ou fhir.executeBundle em vez de fhirStores.import. Para mais informações, consulte o artigo Importar dados FHIR vs. executar pacotes.

Notificações do Pub/Sub

Alguns métodos da Cloud Healthcare API enviam notificações do Pub/Sub para eventos clínicos, como a criação ou a eliminação de um recurso de cuidados de saúde. Para ver uma lista de métodos que enviam notificações do Pub/Sub, consulte o artigo Configurar notificações do Pub/Sub.

Os seguintes métodos de importação não enviam notificações do Pub/Sub:

Se partes da sua aplicação requerem uma notificação quando uma importação termina, use outro método de notificação que possa listar os dados na importação.

Limites de processamento de erros

A Cloud Healthcare API pode não registar todos os erros num LRO, especialmente se o LRO processar grandes volumes de dados e produzir muitos erros. Implemente uma forma de acompanhar o processamento e os erros da LRO separadamente. Para mais informações, consulte o artigo Processamento de erros de recursos.

Dados e indexação da pesquisa

Podem ocorrer atrasos nos resultados da pesquisa devido à indexação da pesquisa assíncrona. Se um LRO criar ou atualizar um recurso FHIR, pode demorar mais tempo até que as alterações estejam disponíveis nos resultados da pesquisa.

Por exemplo, uma pesquisa de recursos de pacientes numa loja FHIR pode não devolver todos os resultados imediatamente após uma operação de importação FHIR.

Ordem de execução

Os LROs são agendados com base na Google Cloud disponibilidade de recursos. A ordem em que os LROs são executados e terminam pode não corresponder à ordem em que foram pedidos.

Evite pedidos de importação e exportação pequenos

Esta secção descreve as limitações das LROs quando processam pequenos volumes de dados.

Os LROs devolvidos pelas operações de importação e exportação ajudam a dimensionar a taxa de transferência de dados processando grandes quantidades de dados rapidamente e evitando picos de carga. Para armazenar pequenas quantidades de dados, use outra técnica nas Práticas recomendadas para armazenar dados.

Limites no número de LROs

A Cloud Healthcare API limita o número de LROs que podem ser executados em simultâneo num Google Cloud projeto. O limite baseia-se no seguinte:

O tipo de LRO.
A quantidade de Google Cloud recursos atribuídos à LRO. Isto baseia-se no tamanho dos dados de entrada.

Se executar demasiadas LROs, a API Cloud Healthcare atinge os limites de taxa, produz erros e pode reduzir o débito das LROs. A Cloud Healthcare API conserva Google Cloud automaticamente os recursos para que o número de LROs permaneça dentro dos limites de recursos.

As LROs são processos em segundo plano. Por isso, se a carga das LROs interferir com processos de prioridade mais elevada, como operações CRUD, a Cloud Healthcare API pode reduzir o débito das LROs. Isto garante que os processos de prioridade mais elevada estão disponíveis.

Sobrecarga de limpeza e atribuição de recursos

Quando um LRO é iniciado, a Cloud Healthcare API atribui recursos. Este processo pode demorar vários minutos porque a Cloud Healthcare API tem de fazer o seguinte:

Inicie um processo de controlador.
Atribua trabalhadores a um grupo de trabalhadores.
Determinar o tamanho dos dados de entrada.
Comece a atribuir trabalho em grande escala.

A interrupção e a limpeza de uma LRO também podem demorar vários minutos.

Devido à sobrecarga, um LRO que processa uma pequena quantidade de dados pode passar a maior parte do tempo a atribuir pools de trabalhadores e a limpar recursos.

Se tiver muitas destas LROs, pode deparar-se com um débito de dados inferior porque é mais provável que atinja os limites de quota do projeto Google Cloud.

Limites para pedir quota de LRO

Antes de pedir mais quota de LRO, implemente as práticas recomendadas para a gestão de quotas. Se ainda precisar de mais quota, contacte o Google Cloud apoio ao cliente. Para fazer um pedido, consulte as Práticas recomendadas para pedir quota adicional.

Pode precisar de uma quota adicional se os seus dados de entrada forem grandes, por exemplo:

Está a importar instâncias DICOM com vários petabytes (PB).
Está a importar dezenas de milhares de milhões de recursos FHIR.

Estado da LRO e estados de falha

Quando inicia uma LRO, a resposta contém um ID exclusivo. Pode ver o estado de um LRO consultando o respetivo ID. Após a conclusão da operação de longa duração, esta tem um dos seguintes estados:

Concluída com êxito sem erros
Concluída com êxito com alguns erros
Não foi possível concluir a tarefa, mas é possível que tenha sido gerada uma saída parcial antes da falha

O exemplo JSON seguinte descreve a resposta devolvida quando um 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 obter o estado de uma LRO, listar LROs e cancelar LROs, consulte o artigo Gerir operações de longa duração.

Faça a gestão do estado da LRO e dos estados de falha

Para gerir o estado das LROs e os estados de falha, siga estas práticas recomendadas:

Envie sondagens aos LROs para saber o respetivo estado e verificar quando terminam. Para sondar um LRO, chame repetidamente o método projects.locations.datasets.operations.get até que a operação termine. Use um intervalo de tempo entre cada pedido de sondagem, como 10 segundos. Quando a resposta contém "done": true, o LRO terminou.
Após a conclusão de uma LRO, verifique se a resposta contém um campo error. Se o fizer, determine se deve repetir a operação com base no seguinte:
- O código de erro. Consulte o artigo Resolução de problemas de LROs para ver 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 a ocorrência do erro. Por exemplo, se uma operação de longa duração que normalmente demora várias horas demorar vários dias e não tiver devolvido um estado de falha, pode querer que um humano intervenha. Para mais informações sobre quando pode ser necessária intervenção humana, consulte o artigo Planeie os estados de erro finais.
Consulte o artigo Coloque um LRO em fila para ver informações sobre como repetir um LRO.
Se não estiver a repetir a LRO, consulte o campo metadata.counter.failure para ver se ocorreram erros em recursos específicos. Pode processar os recursos individualmente. Para mais informações, consulte o artigo Processar erros de recursos.

Processar erros de recursos

Uma LRO pode terminar com erros. Os erros na resposta LRO seguem o Google Cloud modelo de erro. A resposta da LRO inclui um link para o Cloud Logging para mais informações.

Detalhes do erro da LRO

Os erros de LRO no Cloud Logging têm as seguintes propriedades:

O registo de erros do Cloud Logging não contém o ID do LRO. Use os campos operation.id e operation.producer para encontrar o estado e os erros do LRO. Por exemplo, os LROs invocados a partir do método projects.locations.datasets.fhirStores.import contêm import_fhir no campo operation.producer.

Se vários LROs tiverem o mesmo operation.id e operation.producer, use as datas/horas createTime e endTime para identificar o LRO correto.
Nem todos os erros de LRO estão disponíveis no Cloud Logging. O campo metadata.counter.failure pode exceder o número de erros reais registados devido ao seguinte:
- Limitações de quota do Cloud Logging
- Disponibilidade do serviço Cloud Logging
- Limites de registos de LRO
Por exemplo, se um LRO importar 10 milhões de recursos FHIR e 50% deles tiverem erros de formatação, podem ser registados apenas algumas centenas ou alguns milhares de erros devido à limitação de taxa e às quotas do Cloud Logging.

O número de erros registados também varia consoante o tempo de execução do LRO quando encontra taxas de erro elevadas. Se a LRO for executada lentamente, pode apresentar mais erros no Cloud Logging porque os erros foram distribuídos ao longo de um longo período e não estavam sujeitos a limites de taxa.

Efeitos da repetição de uma LRO

Se uma LRO encontrar um erro e uma aplicação cliente tentar novamente a operação automaticamente com os mesmos dados, a nova tentativa pode causar mais erros.

Considere um cenário em que um fhirStores.importLRO termina com erros porque alguns dos recursos FHIR que tentou importar eram inválidos. A repetição automática da importação com os mesmos dados pode gerar muitos erros 409 ALREADY_EXISTS porque alguns recursos FHIR foram importados na operação original. Se consultar um LRO e encontrar uma operação de criação com falha, não repita automaticamente. Um humano deve rever os erros 409 ALREADY_EXISTS.

Se uma nova tentativa for bem-sucedida, o campo metadata.counter.failure não inclui erros de operações anteriores. Isto pode causar uma contagem de erros incorreta porque a resposta da nova tentativa bem-sucedida não inclui erros de tentativas anteriores.

Tente novamente uma LRO

Se tiver um pipeline de processamento do lado do cliente que deteta erros de LRO, não use o Cloud Logging. Conforme mostrado nos detalhes do erro do LRO, os registos de erros do Cloud Logging para LROs não são fiáveis nem estão completos. Em alternativa, use as técnicas nas secções seguintes.

Repita as operações de importação

Para detetar dados que não foram importados, compare os dados importados na API Cloud Healthcare com os respetivos dados de origem no Cloud Storage. Pode importar dados através dos seguintes métodos:

Use um identificador exclusivo, como um número de registo médico (MRN) para um recurso de paciente FHIR, para comparar os dados.

Consulte Efeitos da repetição de uma LRO para ver os passos a seguir quando repetir uma operação de importação.

A nova execução de uma importação pode recriar recursos que eliminou anteriormente. Considere o seguinte cenário:

Tenta importar 1 000 000 de recursos FHIR. 50 000 recursos falham devido a erros de formatação.
Passa vários dias a corrigir os erros de formatação. Durante esse período, um paciente pede-lhe que remova os respetivos registos.
Se executar novamente a importação, corre o risco de recriar os dados do paciente que eliminou.

Tente novamente as operações de exportação

Para detetar dados que não foram exportados para o BigQuery, escreva um script para comparar IDs únicos nos dados de origem com os dados exportados.

Pode exportar dados para o BigQuery através dos seguintes métodos:

Coloque em fila e faça a gestão de LROs

Se executar LROs que processam grandes volumes de dados para integração ou de forma regular, implemente as seguintes técnicas de colocação em fila de LROs:

Limite as LROs concorrentes a um número pequeno, como 5. Pode ajustar este limite consoante a dimensão e os tipos de LROs que executa.
Monitorize a conclusão da LRO. Se ocorrerem erros, reagende a LRO ou resolva os erros separadamente no pipeline de processamento.
Resolver automaticamente os erros em Como processar erros de recursos sempre que possível.
- Compreenda o exemplo de utilização das importações FHIR para determinar se deve ignorar os erros 409 ALREADY_EXISTS ou realizar operações CRUD separadas para resolver os erros. Conforme mostrado nos detalhes do erro LRO, alguns erros 409 ALREADY_EXISTS podem não ser registados no Cloud Logging. Se a sua aplicação depender de registos de erros, use uma das técnicas em Tentar novamente uma LRO.
- Para resolver alguns erros, coloque numa fila um LRO mais pequeno para os dados que encontraram os erros ou execute operações CRUD separadas.
- Para resolver muitos erros, a nova execução da LRO pode ser a opção mais simples para garantir a consistência. Consulte o artigo Voltar a tentar operações de importação para conhecer os riscos de voltar a executar uma importação em dados eliminados.
Detetar automaticamente se é necessária intervenção humana para resolver erros. Deve ter ferramentas e manuais de procedimentos operacionais para os administradores de sistemas. As tarefas para resolver erros podem incluir o seguinte:
- Reagende uma LRO.
- Volte a agendar um subconjunto de dados de uma LRO anterior.
- Examine os erros e resolva os elementos de dados individuais que encontraram erros. Esta tarefa só é possível se puder determinar que todos os erros no LRO foram registados.
Determinar horários de LRO. Pode agendar LROs para evitar a execução durante as horas de pico, quando muitas operações CRUD estão em execução. Para mais informações, consulte o artigo Faça a gestão da quota para maximizar o débito de dados.

Monitorize e receba alertas

Criar e manter procedimentos para monitorizar LROs e resolver alertas. Os alertas são causados principalmente pelos estados de LRO e por problemas de colocação em fila. Os procedimentos devem abordar as seguintes situações:

LROs que tentam novamente sem êxito mais vezes do que o configurado.
Problemas que requerem intervenção humana para resolver um subconjunto de erros. Por exemplo, se uma LRO falhar e o cliente não conseguir resolver os erros, é provável que seja necessária a intervenção humana. Consulte o artigo Colocar em fila e gerir LROs para mais informações sobre como resolver problemas que requerem intervenção humana.
Filas que excedem um determinado comprimento ou crescem demasiado rapidamente.
Os requisitos da política não estão a ser cumpridos, como um problema de autorizações ou uma configuração incorreta.
Verificações de consistência que mostram problemas sistémicos em várias LROs. Pode ter vários LROs de desidentificação que esperam que o conjunto de dados de origem e o conjunto de dados de destino tenham o mesmo número de recursos FHIR. Se existir uma discrepância que aumente ao longo do tempo, pode indicar dados não processados.
Problemas de quota de LRO. Para mais informações, consulte os artigos Faça a gestão da quota para maximizar o débito de dados e Práticas recomendadas para a gestão de quotas.

Práticas recomendadas para operações de longa duração Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.