Configurar roteamento, limites e novas tentativas de fila

O Cloud Tasks permite gerenciar a execução de tarefas definindo o roteamento, a limitação de taxa de envio e o comportamento de repetição no nível da fila. É possível definir essas configurações ao criar uma fila ou atualizar uma existente.

Tanto gcloud tasks queues create quanto gcloud tasks queues update usam as mesmas flags para definir parâmetros de fila, enquanto gcloud tasks queues update também aceita flags --clear-* para redefinir parâmetros para os padrões.

A configuração da autenticação no nível da fila substitui a autenticação no nível da tarefa. Para mais informações, consulte Usar tarefas de destino HTTP com tokens de autenticação.

Configurar o 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 mudar o roteamento de todas as tarefas em uma fila.

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

  • Tarefas que estão na fila
  • Tarefas adicionadas à fila depois que o roteamento no nível da fila foi 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 fazer o seguinte:

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

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

É possível configurar uma fila para substituir o roteamento no nível da tarefa ao criar ou atualizar a fila. Para configurar o roteamento no nível da fila, defina o parâmetro uriOverride da fila como a rota preferencial. Por padrão (uriOverrideEnforceMode definido como ALWAYS), o roteamento no nível da fila substitui o roteamento no nível da tarefa. Também é possível definir uriOverrideEnforceMode como IF_NOT_EXISTS para que o roteamento no nível da fila seja aplicado somente quando uma tarefa não especificar os próprios componentes de URI.

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 mudanças e aguarde um minuto após aplicar as mudanças para retomar a fila.

  1. Pause a fila executando o seguinte comando:

    gcloud tasks queues pause QUEUE_ID \
    --location=LOCATION

    Substitua:

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

  2. Atualizar ou remover 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 ou transmita a flag --http-uri-override para gcloud tasks queues update.

    • Para remover o roteamento no nível da fila:

      • Google Cloud CLI: execute gcloud tasks queues update com a flag --clear-http-uri-override:
      gcloud tasks queues update QUEUE_ID \
    --location=LOCATION \
    --clear-http-uri-override

      • API REST: envie uma solicitação patch para a fila com um objeto JSON vazio ({}) e o parâmetro de consulta updateMask definido como httpTarget.uriOverride (ou httpTarget para limpar todas as configurações de destino HTTP no nível da fila).

      • API RPC: envie um UpdateQueueRequest para o Queue com queue.name especificado, http_target.uri_override não definido e o parâmetro update_mask definido como http_target.uri_override (ou http_target para limpar todas as configurações de destino HTTP no nível da fila).

    O exemplo a seguir usa a API REST para atualizar o host para o qual as tarefas são roteadas:

    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:

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

      gcloud auth application-default login
gcloud auth application-default print-access-token

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

      gcloud config get-value project

    • LOCATION: o local da fila.

    • NEW_HOST: o novo host para o qual você quer que a fila seja encaminhada.

  3. Aguarde um minuto.

    Pode levar até um minuto para que a nova configuração entre em vigor. Aguardar para retomar a fila ajuda a evitar que as tarefas sejam enviadas com a configuração antiga.

  4. Retome a fila executando o seguinte comando:

    gcloud tasks queues resume QUEUE_ID \
    --location=LOCATION

  5. Verifique se a fila foi configurada corretamente executando o seguinte comando:

    gcloud tasks queues describe QUEUE_ID \
    --location=LOCATION

    A saída precisa conter a substituição de roteamento httpTarget que você definiu.

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 do App Engine de sua preferência.

  1. Configure o roteamento no nível da fila e substitua qualquer roteamento no nível da tarefa:

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

    Substitua:

    • QUEUE_ID: o ID da fila (nome curto).
    • LOCATION: o local da fila.
    • SERVICE: o serviço de worker do App Engine responsável pelo processamento de tarefas.
    • VERSION: a versão do app.

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

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

  2. Verifique se a fila foi configurada corretamente executando o seguinte comando:

    gcloud tasks queues describe QUEUE_ID \
    --location=LOCATION

    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

  3. Para remover o roteamento no nível da fila, execute o seguinte comando:

    gcloud tasks queues update QUEUE_ID \
    --location=LOCATION \
    --clear-routing-override

    Quando o roteamento no nível da fila é removido, o roteamento no nível da tarefa é aplicado às tarefas na fila e às tarefas adicionadas à fila no futuro.

Definir limites de taxa

A limitação de taxa determina a taxa máxima de estado estável em que as tarefas podem ser enviadas por uma fila ativa, independentemente de o envio ser uma primeira tentativa de tarefa ou uma nova tentativa.

  1. Defina a taxa máxima e o número de tarefas simultâneas que podem ser enviadas por uma fila executando o seguinte comando:

    gcloud tasks queues update QUEUE_ID \
    --location=LOCATION \
    --max-dispatches-per-second=DISPATCH_RATE \
    --max-concurrent-dispatches=MAX_CONCURRENT_DISPATCHES

    Substitua:

    • QUEUE_ID: o ID da fila (nome curto).
    • LOCATION: o local da fila.
    • DISPATCH_RATE: a taxa de envio. Essa é a taxa em que os tokens no bucket são atualizados. Em condições em que há um fluxo relativamente constante de tarefas, isso equivale à taxa em que as tarefas são enviadas.
    • MAX_CONCURRENT_DISPATCHES: 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 parâmetros, é possível atualizar o número máximo de tarefas simultâneas executando o seguinte comando:

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

  2. Verifique se a fila foi configurada corretamente executando o seguinte comando:

    gcloud tasks queues describe QUEUE_ID \
    --location=LOCATION

    A saída será semelhante a esta:

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

Métodos para definir taxas de processamento de filas

É possível definir as taxas de processamento de filas usando a API Cloud Tasks ou fazendo upload de um arquivo queue.yaml. Os dois métodos resultam em filas que usam o mesmo mecanismo subjacente.

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

Cada vez que o aplicativo executa uma tarefa, um token é removido do bucket. A fila continua processando tarefas até que o bucket fique sem tokens. O sistema reabastece o bucket com novos tokens continuamente com base na taxa max_dispatches_per_second especificada para a fila. Se a fila contiver tarefas para processar e o bucket da fila contiver tokens, o sistema processará simultaneamente tantas tarefas quanto houver tokens, até o valor de max_concurrent_dispatches que você definiu.

Em uma fila ativa que já está aquecida, uma carga desigual pode permitir que o número de tokens no bucket aumente significativamente, o que pode levar a picos de processamento quando um pico de solicitações chega. Nesse caso, uma fila ativa pode ter uma taxa de envio real que excede temporariamente a taxa de max_dispatches_per_second, consumindo recursos do sistema e competindo com solicitações de exibição do usuário. Se você usar filas para gerenciar taxas de envio com base em SLAs relativamente lentos para serviços downstream, essas intermitências poderão levar a erros, como HTTP 429 (Too Many Requests) ou HTTP 503 (Service Unavailable). No entanto, se uma fila for recém-criada, retomada recentemente ou ficar inativa por vários minutos, ela entrará em um estado frio ou inativo e aumentará gradualmente em direção a max_dispatches_per_second em vez de intermitência imediata. Para mais informações sobre o aumento de fila fria ou inativa, consulte Aumento inicial da fila.

  • Ao usar qualquer método da API Cloud Tasks, você tem dois campos para definir a taxa de envio 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. Para mais informações, consulte Mensagens do RateLimits.

  • Ao usar o método queue.yaml, é possível definir 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 da API Cloud Tasks e permitir que o sistema defina max_burst_size produz uma taxa muito eficiente para gerenciar picos de solicitação. No entanto, em alguns casos, principalmente quando a taxa necessária é relativamente lenta, usar o método queue.yaml para definir manualmente bucket_size como um valor pequeno ou definir max_concurrent_dispatches como um valor pequeno usando a API Cloud Tasks pode oferecer mais controle.

Definir parâmetros de tentativa

Se uma tarefa não for concluída, o Cloud Tasks vai tentar novamente com uma espera exponencial de acordo com os parâmetros que você definiu. Depois que uma tarefa é executada, ela é removida da fila. Em todos os casos, o limite de retenção máxima de tarefas também se aplica.

Se quiser, especifique uma configuração de nova tentativa no nível da tarefa que substitua a configuração de nova tentativa no nível da fila para a tarefa. Para mais informações, consulte Definir parâmetros de repetição para uma tarefa.

  1. Especifique o número máximo de vezes que as tarefas com falha na fila serão repetidas, defina um limite de tempo para as tentativas e controle o intervalo entre elas executando o seguinte comando:

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

    Substitua:

    • QUEUE_ID: o ID da fila (nome curto).
    • LOCATION: o local da fila.
    • MAX_ATTEMPTS: o número máximo de tentativas para uma tarefa, incluindo a primeira. Para permitir novas tentativas ilimitadas, defina como -1. MAX_RETRY_DURATION ainda se aplica mesmo que MAX_ATTEMPTS seja atingido ou definido como -1.
    • MAX_RETRY_DURATION: o tempo máximo para tentar novamente uma tarefa com falha, medido a partir da primeira tentativa. O valor precisa ser uma string que termina em "s", como 5s. Para especificar uma duração ilimitada, defina como 0s. MAX_ATTEMPTS ainda se aplica mesmo que MAX_RETRY_DURATION seja atingido ou definido como 0s.
    • MIN_INTERVAL: o tempo mínimo de espera entre as tentativas. O valor precisa ser uma string que termina em "s", como 5s.
    • MAX_INTERVAL: o tempo máximo de espera entre as tentativas. O valor precisa ser uma string que termina em "s", como 5s.

    • MAX_DOUBLINGS: o número máximo de vezes que o intervalo entre as novas tentativas de tarefas com falha é duplicado antes que o aumento se torne constante. O intervalo de repetição de uma tarefa começa em MIN_INTERVAL, dobra MAX_DOUBLINGS vezes, aumenta linearmente e, por fim, repete em intervalos de MAX_INTERVAL até MAX_ATTEMPTS vezes.

      Por exemplo, se MIN_INTERVAL for 10s, MAX_INTERVAL for 300s e MAX_DOUBLINGS for 3, o intervalo de repetição vai dobrar 3 vezes, aumentar linearmente em 2^3 * 10s e, em seguida, tentar novamente em intervalos de MAX_INTERVAL até que a tarefa tenha sido tentada MAX_ATTEMPTS vezes: 10s, 20s, 40s, 80s, 160s, 240s, 300s, 300s e assim por diante.

Para mais detalhes sobre os parâmetros, consulte a referência de recursos RetryConfig.

  1. Verifique se a fila foi configurada corretamente executando o seguinte comando:

    gcloud tasks queues describe QUEUE_ID \
    --location=LOCATION

    A saída precisa conter os parâmetros retryConfig que você definiu:

    retryConfig:
  maxAttempts: MAX_ATTEMPTS
  maxBackoff: MAX_INTERVAL
  maxDoublings: MAX_DOUBLINGS
  maxRetryDuration: MAX_RETRY_DURATION
  minBackoff: MIN_INTERVAL

A seguir