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

Nesta página, descrevemos as práticas recomendadas para executar e gerenciar aplicativos de segurança na nuvem (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 da LRO

As seções a seguir se aplicam aos métodos listados em Métodos que retornam uma LRO.

Impacto na cota

LROs não compartilham cota com a API Cloud Healthcare para criar, ler, atualizar e delete (CRUD) que consomem os seguintes tipos: da 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 processamento de dados à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 uma capacidade máxima de dados ao executar LROs, considere usar o seguinte:

  • Pequenos lotes de importação e exportação normalmente têm baixa capacidade de processamento devido à despesas gerais.
  • 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 necessários para seu caso de uso. 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 o disableReferentialIntegrity do ambiente. Isso permite importar dados com interdependências arbitrárias que não precisam exigem ordenação ou agrupamento, o que aumenta a capacidade de processamento dos 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 Como importar dados FHIR ou executar pacotes.

Notificações do Pub/Sub

Alguns métodos da API Cloud Healthcare enviam notificações do Pub/Sub para eventos, como a criação ou exclusão de um recurso de saúde. Para 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 Tratamento de erros de recursos.

Indexação de dados e pesquisa

Podem ocorrer atrasos nos resultados da pesquisa devido à indexação assíncrona da pesquisa. Se uma LRO criar ou atualizar um recurso FHIR, poderá levar mais tempo antes que elas sejam disponibilizadas nos resultados da pesquisa.

Por exemplo: uma pesquisa por recursos de pacientes em um repositório FHIR pode não retornar todos os resultados imediatamente após uma operação de importação 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.

Evitar pequenas solicitações de importação e exportação

Nesta seção, descrevemos as limitações da LRO ao processar pequenos volumes de dados.

As LROs retornadas 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 a LRO. Isso se baseia do tamanho dos dados de entrada.

Se você executar muitas LROs, os limites de taxa da API Cloud Healthcare, e pode reduzir a capacidade de processamento da LRO. 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.

Sobrecarga de alocação e limpeza de recursos

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:

  1. Inicie um processo de controle.
  2. Alocar workers de um pool.
  3. Determinar o tamanho dos dados de entrada.
  4. Comece a alocar trabalho em escala

Interromper e limpar uma LRO também pode levar vários minutos.

Devido à sobrecarga, uma LRO que processa uma pequena quantidade de dados pode gastar a maior parte do tempo alocando pools de workers e limpando mais recursos.

Se você tiver muitas dessas LROs, talvez encontre menor capacidade de processamento de dados porque é mais provável que você atenda ao Google Cloud limites de cota do projeto.

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 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 a LRO terminar, ela terá um destes estados:

  • Concluído sem erros
  • Concluído com alguns erros
  • Falha ao concluir, mas é possível que tenha gerado uma saída parcial antes de falhar

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 receber o status de uma LRO, liste LROs e cancele LROs, consulte Como 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:

  • Consulte as LROs para saber o status delas 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 quer repetir a operação 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 retornar um status de falha, pode ser necessário que uma pessoa interfira. Para mais informações sobre quando a intervenção humana pode ser necessária, consulte Planejar os 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 recursos específicos. Talvez seja possível processar os recursos individualmente. Para mais informações, consulte Como lidar com erros de recursos.

Gerenciar 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 o Campos operation.id e operation.producer para encontrar o status da LRO e erros. Por exemplo, LROs invocadas usando o método projects.locations.datasets.fhirStores.import contêm import_fhir no campo operation.producer.

    Se várias LROs tiverem os mesmos operation.id e operation.producer, use os carimbos de data/hora createTime e endTime 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 Cloud Logging
    • Limites de registro da 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 ele tentou importar eram inválidos. Tentar novamente de forma automática a importação com os mesmos dados pode gerar muitos erros 409 ALREADY_EXISTS porque alguns recursos FHIR foram importado na operação original. Se você consultar uma LRO e encontrar uma Create, não tente automaticamente. Uma pessoa deve revisar 409 ALREADY_EXISTS erro.

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ê tem um pipeline de processamento do lado do cliente que detecta LRO erros, não use o Cloud Logging. Conforme mostrado nos detalhes do erro da LRO, os registros de erro do Cloud Logging para LROs não são confiáveis e estão incompletos. Use o técnicas nas seções a seguir.

Repetir operações de importação

Para detectar dados com falha, compare os dados importados no API Cloud Healthcare aos dados de origem no Cloud Storage. É possível importar dados usando os seguintes métodos:

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

Consulte Efeitos da repetição de uma LRO para saber as etapas a serem seguidas uma operação de importação.

Executar novamente uma importação pode recriar recursos excluídos anteriormente. Considere no seguinte cenário:

  1. Você tenta importar 1.000.000 de recursos FHIR. 50.000 recursos falhar devido a erros de formatação.
  2. Você passou vários dias corrigindo os erros de formatação. Durante esse período, um paciente solicita a remoção dos registros dele.
  3. 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:

Adicione à fila e gerencie 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 LROs simultâneas a um pequeno número, 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 de FHIR para determinar se é preciso Ignorar 409 ALREADY_EXISTS erros ou executar CRUD separado para resolver os erros. Conforme mostrado nos detalhes do erro da LRO, alguns erros 409 ALREADY_EXISTS podem não ser registrados no Cloud Logging. Caso seu aplicativo dependa de registros de erros, use uma das técnicas 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 os riscos de uma nova importação nos dados excluídos.

  • Detecte automaticamente se é necessária intervenção humana para corrigir erros. Ter acesso a ferramentas e manuais operacionais para administradores de sistema. As tarefas para corrigir erros podem incluir:

    • Reprograme uma LRO.
    • Reprograme um subconjunto de dados de uma LRO anterior.
    • Examinar erros e resolver problemas elementos de dados que encontraram erros. Essa tarefa só é possível é possível determinar que todos os erros na LRO foram registrados.

  • Determinar programações de LRO. É possível programar LROs para evitar a execução em horários de pico quando muitas operações CRUD estão em execução. Para Para mais informações, consulte Gerenciar cota para maximizar a capacidade de processamento de dados.

Monitorar e receber alertas

Crie e mantenha procedimentos para monitorar LROs e resolver alertas. Alertas são causados principalmente por status de LRO e enfileiramento problemas. Os procedimentos devem abordar as seguintes situações:

  • LROs que tentam novamente mais vezes do que estão configuradas.
  • 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, uma intervenção humana provavelmente é necessário. Consulte Fila e gerenciamento de 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 cota para maximizar a capacidade de processamento de dados e Práticas recomendadas para o gerenciamento de cotas.