Referência de queue.yaml

ID da região

O REGION_ID é um código abreviado que a Google atribui com base na região que seleciona quando cria a sua app. O código não corresponde a um país ou uma província, embora alguns IDs de regiões possam parecer semelhantes aos códigos de países e províncias usados frequentemente. Para apps criadas após fevereiro de 2020, REGION_ID.r está incluído nos URLs do App Engine. Para apps existentes criadas antes desta data, o ID da região é opcional no URL.

Saiba mais acerca dos IDs de regiões.

OK

O ficheiro de configuração queue.yaml é usado para criar e configurar quase todas as filas de tarefas (push ou pull) que a sua app usa. Todas as apps do App Engine incluem uma fila de envio pré-configurada automaticamente denominada default. Embora não crie a fila default, pode adicionar outras filas ou alterar a configuração da fila default através do ficheiro queue.yaml.

Para configurar filas de envio, pode usar os métodos queue.yaml ou Queue Management do Cloud Tasks, mas não ambos em simultâneo. A combinação do método de carregamento queue.yaml com métodos de gestão de filas pode produzir resultados inesperados e não é recomendada.

Para configurar filas de obtenção, tem de usar o ficheiro queue.yaml.

Aviso: o carregamento de um ficheiro queue.yaml através da CLI gcloud abaixo da versão 332.0.0 usa uma interface descontinuada para o serviço. A partir de 2022-09-20, as tentativas de usar o método de carregamento podem falhar com erros do servidor. Para resolver este problema, certifique-se de que a API Cloud Tasks está ativada no seu projeto e que a CLI gcloud está atualizada, pelo menos, para a versão 332.0.0.

Exemplo

Segue-se um exemplo básico que define uma fila com nome e substitui a taxa de processamento predefinida:

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

Segue-se 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 predefinida.

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 ficheiro queue.yaml é um ficheiro YAML cuja diretiva raiz é queue. Esta diretiva contém zero ou mais filas com nome. Cada definição de fila pode especificar os seguintes elementos:

Elemento	Descrição
bucket_size (filas de envios)	Opcional. Uma fila de tarefas usa o algoritmo de token bucket para controlar a taxa de execução de tarefas. Cada fila com nome tem um contentor de tokens que contém tokens, até ao máximo especificado pelo valor bucket_size. Sempre que a sua aplicação executa uma tarefa, é removido um token do depósito. Continua a processar tarefas na fila até que o bucket da fila fique sem tokens. O App Engine volta a encher o contentor com novos tokens continuamente com base na taxa que especificou para a fila. O tamanho do contentor limita a velocidade de processamento da fila quando existem muitas tarefas na fila e a taxa é elevada. O valor máximo do tamanho do grupo é 500. Isto permite-lhe ter uma taxa elevada para que o processamento comece pouco depois de uma tarefa ser colocada em fila, mas ainda assim limitar a utilização de recursos quando muitas tarefas são colocadas em fila num curto período de tempo. Se não especificar bucket_size para uma fila, o valor predefinido é 5. Recomendamos que defina este valor para um valor superior, uma vez que o tamanho predefinido pode ser demasiado pequeno para muitos exemplos de utilização. Por exemplo, pode determinar o tamanho do seu grupo com base na taxa de processamento. Para mais informações sobre este elemento, consulte a descrição comparativa de max_burst_size na referência da API Cloud Tasks.
max_concurrent_requests (filas de envios)	Opcional. Define o número máximo de tarefas que podem ser executadas em simultâneo a partir da fila especificada. O valor é um número inteiro. Por predefinição, o limite é de 1000 tarefas por fila. O limite superior recomendado é de 5000 tarefas por fila. Tenha em atenção que as filas podem aumentar lentamente quando são criadas pela primeira vez ou se estiverem inativas durante algum tempo. Restringir o número de tarefas simultâneas dá-lhe mais controlo sobre a taxa de execução da fila e pode impedir que demasiadas tarefas sejam executadas em simultâneo. Também pode evitar a contenção da base de dados e disponibilizar recursos para outras filas ou processamento online. Para mais informações sobre este elemento, consulte a descrição comparativa de max_concurrent_dispatches na referência da API Cloud Tasks.
mode	Opcional. Identifica o modo de fila. Esta definição é predefinida como push, que identifica uma fila como uma fila de envio. Se quiser usar filas de obtenção, defina o modo como pull.
name	Obrigatório. O nome da fila. Este é o nome que especifica quando liga para o número QueueFactory.getQueue(). Um nome de fila pode conter letras maiúsculas e minúsculas, números e hífenes. O comprimento máximo do nome de uma fila é de 100 carateres. Todas as apps têm uma fila de envio denominada predefinição. Esta fila tem uma taxa predefinida de 5 tarefas por segundo. Tenha em atenção que esta fila predefinida não é apresentada no Google Cloud console até ser usada ou configurada pela primeira vez. Pode configurar a fila predefinida, incluindo a alteração da taxa predefinida, definindo uma fila denominada "predefinição" no ficheiro queue.yaml.
rate (filas de envios)	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 ou d para dias. Por exemplo, o valor 5/m indica que as tarefas vão ser processadas a uma taxa de 5 vezes por minuto. O valor máximo de rate é 500/s. Se o número for 0 (como 0/s), a fila é considerada "pausada" e nenhuma tarefa é processada. Para mais informações sobre este elemento, consulte a descrição comparativa de max_dispatches_per_second na referência da API Cloud Tasks.
retry_parameters	Opcional. Configura as tentativas de repetição para tarefas falhadas em filas de envio. Esta adição permite-lhe especificar o número máximo de vezes para repetir tarefas com falhas numa fila específica. Também pode definir um limite de tempo para as tentativas e controlar o intervalo entre tentativas. Os parâmetros de nova tentativa podem conter os seguintes subelementos: task_retry_limit O número de tentativas. Por exemplo, se 0 for especificado e a tarefa falhar, a tarefa não é repetida. Se 1 for especificado e a tarefa falhar, a tarefa é repetida uma vez. Se este parâmetro não for especificado, a tarefa é repetida indefinidamente. Se task_retry_limit for especificado com task_age_limit, a tarefa é repetida até serem atingidos ambos os limites. task_age_limit (filas de envios) O limite de tempo para repetir uma tarefa com falha, medido a partir do 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 ou 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 este parâmetro não for especificado, a tarefa é repetida indefinidamente. Se for especificado com task_retry_limit, o App Engine tenta novamente a tarefa até atingir ambos os limites. min_backoff_seconds (filas de envios) O número mínimo de segundos a aguardar antes de tentar novamente uma tarefa após a falha. O valor predefinido é 0.1. max_backoff_seconds (filas de envios) O número máximo de segundos a aguardar antes de tentar novamente uma tarefa após a falha. O valor predefinido é 3600. max_doublings (filas de envios) O número máximo de vezes que o intervalo entre as novas tentativas de tarefas falhadas é duplicado antes de o aumento se tornar constante. A constante é: 2**max_doublings * min_backoff_seconds. O valor predefinido é 16.
target (filas de envios)	Opcional. Uma string que atribui um nome a um serviço/versão, uma versão de front-end ou um back-end, no qual executar todas as tarefas colocadas em fila nesta fila. O valor predefinido é a string vazia. A string é anteposta ao nome do domínio da sua app quando constrói o pedido HTTP para uma tarefa. Por exemplo, se o ID da app for my-app e definir o destino como my-version-dot-my-service, o nome do anfitrião do URL é definido como my-version-dot-my-service-dot-my-app.REGION_ID.r.appspot.com. Se o destino não for especificado, as tarefas são invocadas na mesma versão da aplicação em que foram colocadas na fila. Assim, se colocar uma tarefa em fila a partir da versão da aplicação predefinida sem especificar um destino na fila, a tarefa é invocada na versão da aplicação predefinida. Tenha em atenção que, se a versão da aplicação predefinida mudar entre o momento em que a tarefa é colocada na fila e o momento em que é executada, a tarefa é executada na nova versão predefinida. Se estiver a usar serviços juntamente com um ficheiro de envio, o pedido HTTP da sua tarefa pode ser intercetado e reencaminhado para outro serviço.

Os seguintes elementos podem ser especificados para todas as filas numa app:

Elemento

Descrição

total_storage_limit

Opcional. Uma string que substitui o limite de armazenamento da quota predefinido que está disponível para o armazenamento de taskqueue (100 M). Por exemplo: total_storage_limit: 1.2G queue: - name: fooqueue Esta quota faz parte da quota de armazenamento total da aplicação (incluindo a quota da base de dados e do armazenamento de blobs). Se não for especificado nenhum sufixo, o número que especificar é interpretado como bytes. São suportados os seguintes sufixos: B (bytes) K (kilobytes) M (megabytes) G (gigabytes) T (terabytes) Se total_storage_limit exceder o armazenamento total em disco disponível para uma aplicação, o limite é limitado ao armazenamento disponível.

Implementar o ficheiro de configuração da fila

O ficheiro queue.yaml deve residir no diretório raiz ou no diretório que define o serviço predefinido.

Para implementar o ficheiro de configuração da fila, execute o seguinte comando:

gcloud app deploy queue.yaml

Eliminar filas

Para eliminar uma fila:

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

2. Carregue a alteração para o ficheiro queue.yaml.

   gcloud app deploy queue.yaml

3. Elimine a fila na Google Cloud consola, selecione a fila e clique em Eliminar fila:

   Aceda à página Filas de tarefas

Se eliminar uma fila da Google Cloud consola, tem de aguardar 7 dias antes de a recriar com o mesmo nome.