Configurar filas do Cloud Tasks

Nesta página, descrevemos como configurar filas do Cloud Tasks usando o comando gcloud da Google Cloud CLI.

Visão geral

A configuração de uma fila do Cloud Tasks pode ser feita durante a criação dela ou posteriormente. A configuração será aplicada a todas as tarefas nessa fila.

Observação :o comando create tem um conjunto de sinalizações opcionais idênticas às do comando update descrito abaixo.

Veja três aspectos básicos para configurar as filas:

• Roteamento
• Limites de taxas
• parâmetros de tentativa

Roteamento no nível da fila

A configuração do roteamento no nível da fila substitui o roteamento definido no nível da tarefa. Isso é útil se você quiser usar o Cloud Tasks como um buffer na frente do serviço de destino ou se precisar alterar o roteamento para todas as tarefas em uma fila.

O roteamento no nível da fila se aplica a:

• Tarefas que estão atualmente na fila
• Tarefas que são adicionadas à fila depois que o roteamento no nível da fila é definido

Limitações

O roteamento no nível da fila não é compatível com as chaves de criptografia gerenciadas pelo cliente (CMEK) do Cloud Key Management Service (Cloud KMS). Se a CMEK estiver ativada, não será possível:

• Criar tarefas em uma fila que tenha roteamento no nível da fila
• Aplicar roteamento no nível da fila

Configurar o roteamento no nível da fila para tarefas HTTP

Aplicar roteamento no nível da fila

É possível configurar uma fila para substituir o roteamento no nível da tarefa ao criar a fila ou ao atualizá-la. Para configurar o roteamento no nível da fila, defina o parâmetro uriOverride da fila como sua rota preferida. Se você estiver aplicando o roteamento no nível da fila como uma atualização de uma fila atual, pause a fila antes de aplicar as alterações e aguarde um minuto após a aplicação das alterações para retomar a fila. Pode levar até um minuto para que a nova configuração entre em vigor. Portanto, aguardar a retomada da fila ajuda a evitar que as tarefas sejam enviadas com a configuração antiga.

Atualizar ou remover o roteamento no nível da fila

1. Pausar a fila.

   Console

   Para pausar a fila usando o console do Google Cloud:

   1. Abra a página de filas do Cloud Tasks no console.

      Acessar a página de filas do Cloud Tasks

   2. Selecione o nome da fila que você quer pausar e clique em Pausar fila.

   3. Confirme a ação.

   gcloud

   gcloud tasks queues pause QUEUE_ID
   

   Substitua QUEUE_ID pelo ID da fila.

2. Atualize ou remova o roteamento no nível da fila.

   • Para atualizar o roteamento no nível da fila, defina o parâmetro uriOverride como a rota atualizada.

   • Para remover o roteamento no nível da fila usando a API REST ou RPC:

     • API REST: envie uma solicitação patch para a fila com um payload vazio e o parâmetro updateMask definido como httpTarget.

     • API RPC:envie um updateQueueRequest para a fila com um payload vazio e o parâmetro update_mask definido como http_target.

   O exemplo a seguir usa a API REST para atualizar as tarefas do host para:

   curl -X PATCH -d @- -i \
   -H "Authorization: Bearer ACCESS_TOKEN" \
   -H "Content-Type: application/json" \
   "https://cloudtasks.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID?updateMask=httpTarget.uriOverride" << EOF
   {
   "httpTarget": {"uriOverride":{"host":"NEW_HOST"}}
   }
   EOF
   

   Substitua:

   • PROJECT_ID: o ID do projeto do Google Cloud. Para isso, execute o seguinte no seu terminal:

     gcloud config get-value project

   • LOCATION: o local da fila.
   • QUEUE_ID: o ID da fila.

   • ACCESS_TOKEN: seu token de acesso. Para isso, execute o seguinte no seu terminal:

     1. gcloud auth application-default login

     2. gcloud auth application-default print-access-token

   • NEW_HOST: o novo host para onde sua fila será roteada.

3. Aguarde um minuto.

   Pode levar até um minuto para que a nova configuração entre em vigor. Portanto, aguardar a retomada da fila ajuda a evitar que as tarefas sejam enviadas com a configuração antiga.

4. Retome a fila.

   Console

   Para retomar a fila usando o console do Google Cloud:

   1. Abra a página de filas do Cloud Tasks no console.

      Acessar a página de filas do Cloud Tasks

   2. Selecione o nome da fila que você quer pausar e clique em Retomar fila.

   3. Confirme a ação.

   gcloud

   gcloud tasks queues resume QUEUE_ID
   

   Substitua QUEUE_ID pelo ID da fila.

Configurar o roteamento no nível da fila para tarefas do App Engine

Para configurar o roteamento no nível da fila para tarefas do App Engine, defina o parâmetro appEngineRoutingOverride da fila como o serviço e a versão de sua preferência do App Engine.

Para configurar esse roteamento no nível de fila não padrão e substituir qualquer roteamento no nível da tarefa, use gcloud:

  gcloud tasks queues update QUEUE_ID\
      --routing-override=service:SERVICE,version:VERSION

Substitua:

• SERVICE: o serviço de worker do App Engine responsável pelo gerenciamento das tarefas.
• VERSION: a versão do app.

Por exemplo, se você configurar um serviço de worker SERVICE para processar todas as tarefas em uma fila, poderá rotear para esse serviço e a versão padrão:

  gcloud tasks queues update QUEUE_ID \
      --routing-override=service:SERVICE

Descreva a fila:

    gcloud tasks queues describe QUEUE_ID --location=LOCATION

Substitua:

• QUEUE_ID: o ID da fila (nome curto)
• LOCATION: o local da fila.

A saída será semelhante a esta:

appEngineRoutingOverride:
  host: SERVICE.PROJECT_ID.appspot.com
  service: SERVICE
name: projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID
rateLimits:
  maxBurstSize: 100
  maxConcurrentDispatches: 1000
  maxDispatchesPerSecond: 500.0
retryConfig:
  maxAttempts: 100
  maxBackoff: 3600s
  maxDoublings: 16
  minBackoff: 0.100s
state: RUNNING

Remover roteamento no nível da fila para destinos do App Engine

Quando o roteamento no nível da fila é removido, o roteamento no nível da tarefa se aplica às tarefas atualmente na fila e às adicionadas a ela no futuro. Para remover o roteamento no nível da fila, execute o seguinte comando:

  gcloud tasks queues update QUEUE_ID \
      --clear-routing-override

Definir limites de taxa

É possível definir a taxa máxima e o número de tarefas simultâneas que podem ser despachadas por uma fila.

  gcloud tasks queues update QUEUE_ID \
      --max-dispatches-per-second=DISPATCH_RATE \
      --max-concurrent-dispatches=MAX_RUNNING

Substitua:

• DISPATCH_RATE: a taxa de despacho (é a taxa em que os tokens do bucket são atualizados). Em condições em que há um fluxo relativamente constante de tarefas, isso é o equivalente à taxa em que as tarefas são despachadas.
• MAX_RUNNING: o número máximo de tarefas na fila que podem ser executadas de uma só vez.

Por exemplo, se você criou uma fila sem definir nenhum parâmetro, atualize o número máximo de tarefas simultâneas chamando:

  gcloud tasks queues update QUEUE_ID \
          --max-concurrent-dispatches=MAX_CONCURRENT_DISPATCHES

Describe a fila:

  gcloud tasks queues describe QUEUE_ID --location=LOCATION

Substitua:

• QUEUE_ID: o ID da fila (nome curto)
• LOCATION: o local da fila.

A saída precisa ser:

name: projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID
rateLimits:
  maxBurstSize: 100
  maxConcurrentDispatches: MAX_CONCURRENT_DISPATCHES
  maxDispatchesPerSecond: 500.0
retryConfig:
  maxAttempts: 100
  maxBackoff: 3600s
  maxDoublings: 16
  minBackoff: 0.100s
state: RUNNING

Como definir taxas de processamento usando comandos gcloud em comparação com queue.yaml

A abordagem da API Cloud Tasks para definir taxas de processamento de fila é um pouco diferente da abordagem usada no upload de arquivos queue.yaml, embora ambos os métodos resultem em filas usando o mesmo mecanismo subjacente.

Cuidado: Embora ambos os métodos possam ser usados para criar filas, é altamente recomendável usar o método do arquivo de configuração queue.yaml ou a API do Cloud Tasks para configurar suas filas, mas não ambos. Para mais informações sobre as armadilhas envolvidas, consulte Usar o gerenciamento de filas ou o arquivo enfileir.yaml.

Em ambos os casos, a fila usa o algoritmo de bucket de token para controlar a taxa de execução da tarefa. Cada fila nomeada tem um bucket que contém seus tokens.

Cada vez que o aplicativo executa uma tarefa, um token é removido do bucket. A fila continua processando tarefas até o esgotamento de tokens do bucket. O sistema recarrega o bucket com novos tokens continuamente com base na taxa max_dispatches_per_second especificada para a fila. Se a fila contiver tarefas a serem processadas e o bucket da fila contiver tokens, o sistema processará simultaneamente todas as tarefas em que houver tokens, até o valor max_concurrent_dispatches definido.

A carga desigual pode permitir o aumento significativo do número de tokens no bucket, o que pode levar a explosões de processamento quando uma sequência de solicitações é recebida. Nesse caso, sua fila pode apresentar uma taxa de despacho real que excede a taxa max_dispatches_per_second, consumindo recursos do sistema e competindo com solicitações de veiculação do usuário. Nos casos em que você usa filas para gerenciar taxas de despacho com base em SLAs relativamente lentos para serviços de downstream, isso pode gerar erros, como HTTP 429 (excesso de solicitações) ou 503 (serviço indisponível).

Ao usar qualquer método de API Cloud Tasks, você tem dois campos para definir a taxa de despacho da fila:

• max_dispatches_per_second
• max_concurrent_dispatches

Um terceiro campo, max_burst_size, é calculado pelo sistema com base no valor definido para max_dispatches_per_second.

Ao usar o método queue.yaml, você pode definir todos os três elementos:

• max_concurrent_requests, que é equivalente a max_concurrent_dispatches
• rate, que é equivalente a max_dispatches_per_second
• bucket_size, que é equivalente a max_burst_size

Na maioria dos casos, usar o método de API Cloud Tasks e permitir que o sistema defina max_burst_size produz uma taxa muito eficiente para o gerenciamento de bursts de solicitação. Em alguns casos, no entanto, especialmente quando a taxa desejada é relativamente lenta, usar o método queue.yaml para definir manualmente bucket_size com um valor baixo ou definir max_concurrent_dispatches com um valor baixo por meio da API Cloud Tasks pode lhe dar mais controle.

Definir parâmetros de tentativa

Se uma tarefa não for concluída com sucesso, o Cloud Tasks fará uma nova tentativa com a tarefa com retirada exponencial de acordo com os parâmetros que você configurou. Você pode especificar o número máximo de vezes para repetir as tarefas com falha na fila, definir um limite de tempo para tentar novamente e controlar o intervalo entre as tentativas.

  gcloud tasks queues update QUEUE_ID \
      --max-attempts=MAX_ATTEMPTS \
      --min-backoff=MIN_INTERVAL \
      --max-backoff=MAX_INTERVAL \
      --max-doublings=MAX_DOUBLINGS \
      --max-retry-duration=MAX_RETRY_DURATION

Substitua:

• MAX_ATTEMPTS: o número máximo de tentativas de uma tarefa, incluindo a primeira tentativa. Você pode permitir tentativas ilimitadas definindo essa sinalização como unlimited.
• MIN_INTERVAL: o tempo mínimo de espera entre novas tentativas. O valor precisa ser uma string que termine em "s", como 5s.
• MAX_INTERVAL: o tempo máximo de espera entre novas tentativas. O valor precisa ser uma string que termine em "s", como 5s.
• MAX_DOUBLINGS: o número máximo de vezes que o intervalo entre tentativas com falha da tarefa será duplicado antes do aumento se tornar constante.
• MAX_RETRY_DURATION: a quantidade máxima de tempo para repetir uma tarefa com falha, medida a partir de quando a tarefa foi tentada pela primeira vez. O valor precisa ser uma string que termine em "s", como 5s.

Observação :o Cloud Tasks só interrompe uma nova tentativa quando MAX_RETRY_DURATION e MAX_ATTEMPTS são atendidos. Depois que o tempo MAX_RETRY_DURATION tiver passado e a tarefa tiver sido tentada MAX_ATTEMPTS vezes, nenhuma outra tentativa será feita, e a tarefa será excluída.

Verifique se a fila foi configurada com sucesso:

    gcloud tasks queues describe QUEUE_ID --location=LOCATION

Substitua:

• QUEUE_ID: o ID da fila (nome curto)
• LOCATION: o local da fila.

Observação: no console, os nomes de exibição dos parâmetros são um pouco diferentes dos nomes das sinalizações. A flag --max-attempts se torna Max attempts, --min-backoff se torna Min backoff e assim por diante.

A seguir

• Saiba como criar tarefas de destino HTTP.
• Saiba mais sobre a criação de tarefas do App Engine.
• Saiba mais sobre como configurar o Cloud Logging.
• Saiba mais sobre o gerenciamento de filas na referência da API RPC.
• Saiba mais sobre o gerenciamento de filas na referência da API REST.
• Consulte a lista completa de comandos gcloud do Cloud Tasks.