Referência do queue.yaml

ID da região

O REGION_ID é um código que o Google atribui com base na região selecionada ao criar o aplicativo. A inclusão de REGION_ID.r nos URLs do App Engine é opcional para aplicativos atuais e em breve será obrigatória para todos os aplicativos novos.

Para garantir uma transição tranquila, estamos atualizando lentamente o App Engine para usar códigos da região. Se ainda não tivermos atualizado seu projeto do Google Cloud, você não verá um ID da região para o aplicativo. Como o ID é opcional para os aplicativos atuais, não é necessário atualizar os URLs ou fazer outras alterações quando o ID da região está disponível para os aplicativos já existentes.

Saiba mais sobre IDs da região.

Os aplicativos que usam o SDK do App Engine para gerenciar filas de tarefas definem essas filas usando um arquivo de configuração chamado queue.yaml. Em aplicativos Java, esse arquivo é armazenado em qualquer lugar no diretório do código-fonte. Você pode usar queue.yaml para configurar filas push e filas pull. Esse arquivo de configuração é opcional para filas push, que têm uma fila padrão. As filas pull devem ser configuradas especificamente em queue.yaml.

Exemplo

Este é um exemplo básico que define uma fila nomeada e substitui a taxa de processamento padrão:

queue:
- name: my-push-queue
  rate: 1/s

Veja a seguir um exemplo mais complexo de uma configuração queue.yaml que demonstra a configuração do número de tentativas de tarefas e a modificação da taxa de processamento padrão.

queue:
- name: fooqueue
  rate: 1/s
  retry_parameters:
    task_retry_limit: 7
    task_age_limit: 2d
- name: barqueue
  rate: 1/s
  retry_parameters:
    min_backoff_seconds: 10
    max_backoff_seconds: 200
    max_doublings: 0
- name: bazqueue
  rate: 1/s
  retry_parameters:
    min_backoff_seconds: 10
    max_backoff_seconds: 200
    max_doublings: 3

Sintaxe

O arquivo queue.yaml é um YAML com a diretiva raiz queue. Essa diretiva contém zero ou mais filas nomeadas. Cada definição de fila pode especificar os seguintes elementos:

Elemento Descrição
<bucket-size> (filas push)

Opcional. Uma fila de tarefas 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 tokens até o máximo especificado pelo valor bucket_size. Sempre que o aplicativo executa uma tarefa, um token é removido do bucket. Você continua processando tarefas na fila até o bucket da fila ficar sem tokens. O App Engine recarrega continuamente o bucket com novos tokens com base na taxa especificada para a fila.

O tamanho do bucket limita com que velocidade a fila é processada quando há muitas tarefas na fila e a taxa é alta. O valor máximo do tamanho do bucket é 500. Isso permite ter uma taxa alta. Dessa maneira, o processamento começará logo depois que uma tarefa for colocada na fila, mas ainda limitará o uso de recursos quando muitas tarefas forem enfileiradas em um curto período.

Se você não especificar bucket_size para uma fila, o valor padrão será 5. Recomendamos defini-lo como um valor maior, porque o tamanho padrão pode ser muito pequeno para muitos casos de uso. O tamanho recomendado é a taxa de processamento dividida por cinco (taxa/5).

Para mais informações sobre esse elemento, consulte a descrição comparativa de max_burst_size

na referência da API Cloud Tasks.
<max-concurrent-requests> (filas push)

Opcional. Define o número máximo de tarefas que podem ser executadas simultaneamente a partir da fila especificada. O valor é um número inteiro. Por padrão, o limite é de 1.000 tarefas por fila. O limite máximo recomendado é de 5.000 tarefas por fila. Observe que as filas podem aumentar lentamente quando forem criadas pela primeira vez ou se estiverem inativas por um tempo.

A restrição do número de tarefas simultâneas dá mais controle sobre a taxa de execução da fila e pode evitar que muitas tarefas sejam executadas de uma só vez. Isso também pode impedir a contenção do armazenamento de dados e disponibilizar recursos para outras filas ou processamento on-line.

Para mais informações sobre esse elemento, consulte a descrição comparativa de max_concurrent_dispatches na referência da API Cloud Tasks.

<mode>

Opcional. Identifica o modo da fila. Essa configuração assume como padrão push, o que identifica uma fila como push. Se você quiser usar filas pull, defina o modo como pull.

<name>

Obrigatório. O nome da fila. Esse é o nome que você especifica ao chamar QueueFactory.getQueue().

Um nome de fila pode conter letras maiúsculas e minúsculas, números e hifens. O comprimento máximo de um nome de fila é de 100 caracteres.

Todos os apps têm uma fila push chamada padrão. Essa fila tem uma taxa predefinida de cinco tarefas por segundo, mas você pode alterar essa taxa por meio da definição de uma fila padrão em queue.yaml. Se você não configurar uma fila padrão no queue.yaml, a fila padrão não será exibida no Console do Google Cloud até ser usada pela primeira vez. É possível personalizar as configurações dessa fila definindo uma fila chamada default.

<rate> (filas push)

Obrigatório. Com que frequência as tarefas são processadas nesta fila. O valor é um número seguido por barra e uma unidade de tempo, no qual a unidade é s para segundos, m para minutos, h para horas ou d para dias. Por exemplo, o valor 5/m indica que as tarefas serão processadas a uma taxa de 5 vezes por minuto. O valor máximo para rate é 500/s.

Se o número for 0 (como 0/s), a fila será considerada "pausada", e nenhuma tarefa será processada.

Para mais informações sobre esse elemento, consulte a descrição comparativa de max_dispatches_per_second na referência da API Cloud Tasks.

<retry-parameters>

Opcional. Configura tentativas de repetição de tarefas com falha em filas push. Essa adição permite especificar o número máximo de vezes em que tarefas com falha são repetidas em uma fila específica. Também é possível definir um limite de tempo para novas tentativas e controlar o intervalo entre elas.

Os parâmetros de repetição podem conter os seguintes subelementos:

<task-retry-limit>
O número de novas tentativas. Por exemplo, se o valor especificado for 0, a tarefa não será repetida em caso de falha. Se o valor for definido como 1 e a tarefa falhar, haverá uma nova tentativa. Se esse parâmetro não for especificado, a tarefa será repetida indefinidamente. Se task_retry_limit for especificado com task_age_limit, a tarefa será repetida até que ambos os limites sejam atingidos.
<task-age-limit> (filas push)
O limite de tempo para repetir uma tarefa com falha, desde o momento em que a tarefa foi executada pela primeira vez. O valor é um número seguido por uma unidade de tempo, no qual a unidade é s para segundos, m para minutos, h para horas ou d para dias. Por exemplo, o valor 5d especifica um limite de cinco dias depois da primeira tentativa de execução da tarefa. Se esse parâmetro não for especificado, a tarefa será repetida indefinidamente. Se especificado com task_retry_limit, o App Engine repetirá a tarefa até que ambos os limites sejam atingidos.
<min-backoff-seconds> (filas push)
O número mínimo de segundos para aguardar antes de repetir uma tarefa depois que ela falhar. O valor padrão é 0.1.
<max-backoff-seconds> (filas push)
O número máximo de segundos a aguardar antes de tentar uma tarefa novamente depois que ela falha. O valor padrão é 3600.
<max-doublings> (filas push)
O número máximo de vezes que o intervalo entre novas tentativas de tarefas com falhas será dobrado antes que o aumento se torne constante. A constante é: 2**max_doublings * min_backoff_seconds. O valor padrão é 16.
<target> (filas push)

Opcional. Uma string que nomeia um serviço/versão, uma versão de front-end ou um back-end, em que todas as tarefas enfileiradas são executadas. O valor padrão é a string vazia.

A sequência é anexada ao nome do domínio do seu aplicativo ao criar a solicitação HTTP para uma tarefa. Por exemplo, se o código do seu aplicativo for my-app e você definir o destino como my-version-dot-my-service, o nome do host do URL será definido como my-version-dot-my-service-dot-my-app.REGION_ID.r.appspot.com.

Se o destino não for especificado, as tarefas serão invocadas na mesma versão do aplicativo em que foram enfileiradas. Dessa maneira, se você tiver enfileirado uma tarefa da versão do aplicativo padrão sem especificar um destino na fila, a tarefa será invocada na versão padrão do aplicativo. Se a versão padrão do aplicativo mudar entre o momento em que a tarefa for enfileirada e o momento em que for executada, a tarefa será executada na nova versão padrão.

Se você estiver usando serviços com um arquivo de despacho, a solicitação HTTP da tarefa poderá ser interceptada e encaminhada para outro serviço.

Os seguintes elementos podem ser especificados para todas as filas em um aplicativo:

Elemento Descrição
<total-storage-limit>

Opcional. Uma string que substitui o limite de armazenamento da cota padrão disponível para armazenamento da fila de tarefas (100 M). Por exemplo:


<queue-entries>
  <total-storage-limit>1.2G</total-storage-limit>
  <queue>
    <name>fooqueue</name>
  </queue>
</queue-entries>

Esta cota faz parte da cota de armazenamento total do aplicativo (inclusive do armazenamento de dados e do armazenamento de blobs).

Se nenhum sufixo for especificado, o número definido por você será interpretado como bytes. Os sufixos abaixo são compatíveis:

  • B (bytes)
  • K (kilobytes)
  • M (megabytes)
  • G (gigabytes)
  • T (terabytes)

Se <total-storage-limit> exceder o armazenamento total disponível em disco para um aplicativo, o limite será bloqueado.

Como implantar o arquivo de configuração da fila

O arquivo queue.yaml pode residir em qualquer lugar no diretório do código-fonte.

Para implantar o arquivo de configuração da fila sem alterar a versão atual, use um dos comandos a seguir no diretório que contém o arquivo da fila, dependendo do seu ambiente:

gcloud

gcloud app deploy queue.yaml

Maven

mvn appengine:deployQueue queue.yaml

Gradle

gradle appengineDeployQueue queue.yaml

Ambiente de desenvolvimento integrado

Se você utiliza IntelliJ ou Eclipse, use o formulário de implantação para selecionar os arquivos de configuração individuais a serem implantados.

Como excluir filas

Para excluir uma fila:

  1. Remova a definição da fila do arquivo queue.yaml.

  2. Faça upload da alteração no arquivo queue.yaml.

    gcloud app deploy queue.yaml
    
  3. Exclua a fila do Console do Cloud, selecione a fila e clique em Excluir fila:

    Ir para a página Filas de tarefas

Se você excluir uma fila do Console do Cloud, precisará aguardar sete dias antes de recriar com o mesmo nome.