Referência do queue.yaml

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

Exemplo

Veja a seguir 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 definição do número de tentativas da tarefa 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

queue.yaml é um arquivo YAML com uma 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 intervalo de token para controlar a taxa de execução da tarefa. Cada fila nomeada tem um intervalo de token que contém tokens até o máximo especificado pelo valor bucket_size. Sempre que o aplicativo executa uma tarefa, um token é removido do intervalo. Você continua processando tarefas na fila até o intervalo da fila ficar sem tokens. O App Engine recarrega continuamente o intervalo com novos tokens com base na taxa especificada para a fila.

O tamanho do intervalo limita com que velocidade a fila é processada quando há muitas tarefas na fila e a taxa é alta. O valor máximo do tamanho do intervalo é 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).

<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.

<mode>

Opcional. Identifica o modo da fila. Essa configuração assume push como padrão, o que identifica uma fila como fila push. Para 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 aplicativos têm uma fila push chamada "default". Essa fila tem uma taxa predefinida de 5 tarefas por segundo. Para alterar essa taxa, defina uma fila padrão em queue.yaml. Se você não configurar uma fila padrão no queue.yaml, ela não será exibida no Console do Google Cloud Platform até ser usada pela primeira vez. Para personalizar as configurações dessa fila, defina 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 de uma barra e uma unidade de tempo, em que a unidade é s para segundos, m para minutos, h para horas e d para dias. Por exemplo, o valor 5/m indica que as tarefas serão processadas em uma taxa de cinco vezes por minuto. O valor máximo de rate é 500/s.

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

<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>
Na verdade, este é um limite geral para o número máximo de tentativas de uma tarefa. Se for especificado 0 ou 1 e a tarefa falhar, ela não será repetida. Se ele for especificado com task_age_limit, a tarefa será repetida até ambos os limites serem alcançados. Se esse parâmetro não for especificado, a tarefa será repetida indefinidamente.
<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 de uma unidade de tempo, em que a unidade é s para segundos, m para minutos, h para horas e d para dias. Por exemplo, o valor 5d especifica um limite de cinco dias após a primeira tentativa de execução da tarefa. Se esse parâmetro não for especificado, a tarefa será repetida indefinidamente. Se task_retry_limit for especificado, o App Engine repetirá a tarefa até ambos os limites serem alcançados.
<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 para aguardar antes de repetir uma tarefa depois que ela falhar. O valor padrão é 3600.
<max-doublings> (filas push)
O número máximo de vezes em que o intervalo entre repetições de tarefas com falha dobrará antes do aumento ficar 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 string é acrescentada ao nome de domínio do app durante a criação da solicitação HTTP para uma tarefa. Por exemplo, se o código do app for my-app e você definir o destino como my-version.my-service, o nome do host do URL será definido como my-version.my-service.my-app.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 expedição, 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. São aceitos os seguintes sufixos:

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

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

Como implantar o arquivo de configuração de fila

O arquivo queue.yaml pode residir em qualquer lugar no diretório de 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ê usa o IntelliJ ou Eclipse, selecione os arquivos de configuração individuais a serem implantados por meio do formulário de implantação.

Como excluir filas

Para excluir uma fila, siga estas etapas:

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

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

    gcloud app deploy queue.yaml
    
  3. Exclua a fila no Console do GCP selecionando-a e clicando em Excluir fila:

    Acesse a página "Filas de tarefas"

Se excluir uma fila usando o Console do GCP, você precisará aguardar sete dias para recriar uma com o mesmo nome.

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Ambiente padrão do App Engine para Java