Esta página descreve como criar tarefas e colocá-las em filas de envio. Quando quiser processar uma tarefa, tem de criar um novo objeto de tarefa e colocá-lo numa fila. Pode especificar explicitamente o serviço e o controlador que processam a tarefa e, opcionalmente, transmitir dados específicos da tarefa ao controlador. Também pode ajustar a configuração da tarefa, como agendar uma hora no futuro em que deve ser executada ou limitar o número de vezes que quer que a tarefa seja repetida se falhar.
Criar uma nova tarefa
Para criar e colocar uma tarefa na fila, chame a função taskqueue.add().
O código seguinte cria uma tarefa que segmenta o serviço denominado worker
e invoca o respetivo controlador definindo o URL /update-counter
:
Em alternativa, pode criar um objeto Task e chamar o respetivo método add().
Especificar o serviço de trabalho
Quando uma tarefa é removida da respetiva fila, o serviço Task Queue envia-a para um serviço de trabalho. Cada tarefa tem um alvo e um URL, que determinam que serviço e controlador vão realizar a tarefa em última instância.
target
O destino especifica o serviço que vai receber o pedido HTTP para realizar a tarefa. É uma string que especifica um serviço/versão/instância numa das formas canónicas. Os formulários mais usados são:
service
version.service
instance.version.service
A string de destino é adicionada antes do nome do domínio da sua app. Existem três formas de definir o destino de uma tarefa:
Declare o destino quando construir a tarefa. Pode definir o destino explicitamente através do parâmetro
target
na função taskqueue.add(). Consulte o exemplo acima.Inclua uma diretiva
target
quando definir uma fila no elementoqueue.yaml
, como na definição dequeue-blue
. Todas as tarefas adicionadas a uma fila com umtarget
usam esse destino, mesmo que tenha sido atribuído um destino diferente à tarefa no momento da criação.Se não for especificado nenhum destino de acordo com qualquer um dos dois métodos anteriores, o destino da tarefa é a versão do serviço que a coloca na fila. Tenha em atenção que, se colocar uma tarefa em fila a partir do serviço e da versão predefinidos desta forma, e a versão predefinida mudar antes da execução da tarefa, esta é executada na nova versão predefinida.
url
O url
seleciona um dos controladores no serviço de destino, que vai
realizar a tarefa.
O url
deve corresponder a um dos padrões de URL do controlador no serviço de destino. O url
pode incluir parâmetros de consulta se o método especificado na tarefa for GET
ou PULL
. Se não for especificado nenhum url
, é usado o URL predefinido
/_ah/queue/[QUEUE_NAME]
, onde [QUEUE_NAME]
é o nome da fila da tarefa.
Transmitir dados ao controlador
Pode transmitir dados ao controlador como parâmetros de consulta no URL da tarefa, mas
apenas se o método especificado na tarefa for GET
ou PULL
.
payload
, que envia dados de tarefas no corpo do pedido HTTP.params
Estas três chamadas são equivalentes:
taskqueue.add(method=GET, url='/update-counter?key=blue', target='worker')
taskqueue.add(url='/update-counter', params={'key': 'blue'}, target='worker')
taskqueue.add(url='/update-counter', payload="{'key': 'blue'}", target='worker')
Atribuir um nome a uma tarefa
Quando cria uma nova tarefa, o App Engine atribui-lhe um nome único por predefinição. No entanto, pode atribuir o seu próprio nome a uma tarefa através do parâmetro name
. Uma vantagem de atribuir os seus próprios nomes de tarefas é que as tarefas com nome são
desduplicadas, o que significa que pode usar nomes de tarefas para
garantir
que uma tarefa só é adicionada uma vez. A remoção de duplicados continua durante 9 dias após a conclusão ou a eliminação da tarefa.
Tenha em atenção que a lógica de remoção de duplicados introduz uma sobrecarga de desempenho significativa, o que resulta num aumento das latências e, potencialmente, das taxas de erro associadas a tarefas com nome. Estes custos podem aumentar significativamente se os nomes das tarefas forem sequenciais, como com as datas/horas. Assim, se atribuir os seus próprios nomes, recomendamos que use um prefixo bem distribuído para os nomes das tarefas, como um hash dos conteúdos.
Se atribuir os seus próprios nomes às tarefas, tenha em atenção que o comprimento máximo do nome é de 500 carateres e que o nome pode conter letras maiúsculas e minúsculas, números, sublinhados e hífenes.
taskqueue.add(url='/url/path', name='first-try')
Adicionar tarefas de forma assíncrona
Por predefinição, as chamadas que adicionam tarefas a filas são síncronas. Na maioria dos cenários, as chamadas síncronas funcionam bem. Adicionar uma tarefa a uma fila é normalmente uma operação rápida. Existe uma pequena percentagem de operações de adição de tarefas que podem demorar significativamente mais tempo, mas o tempo médio para adicionar uma tarefa é inferior a 5 ms.
Não é possível processar em lote operações de tarefas adicionadas a filas diferentes. Por isso, a API Task Queue também oferece chamadas assíncronas que lhe permitem adicionar estas tarefas em paralelo, minimizando ainda mais esta latência. Isto é útil se estiver a criar uma aplicação extremamente sensível à latência que precise de realizar várias operações de adição de tarefas a diferentes filas ao mesmo tempo.
Se quiser fazer chamadas assíncronas para uma fila de tarefas, use os métodos assíncronos fornecidos pela classe Queue e um objeto RPC. Chame get_result()
no objeto RPC
devolvido para forçar a conclusão do pedido. Quando adiciona tarefas de forma assíncrona numa transação, deve chamar get_result()
no objeto RPC
antes de confirmar a transação para garantir que o pedido foi concluído.
Colocar tarefas em fila em transações do Cloud Datastore
Pode colocar uma tarefa em fila como parte de uma transação do Datastore, de modo que a tarefa só seja colocada em fila (e seja garantido que é colocada em fila) se a transação for confirmada com êxito. As tarefas adicionadas numa transação são consideradas parte da mesma e têm o mesmo nível de isolamento e consistência.
Uma aplicação não pode inserir mais de cinco tarefas transacionais em filas de tarefas durante uma única transação. As tarefas transacionais não podem ter nomes especificados pelo utilizador.
O seguinte exemplo de código demonstra como inserir tarefas transacionais numa fila de envio como parte de uma transação do Datastore:
from google.appengine.api import taskqueue
from google.appengine.ext import ndb
@ndb.transactional
def do_something_in_transaction():
taskqueue.add(url='/path/to/my/worker', transactional=True)
#...
do_something_in_transaction()
Usar a biblioteca de tarefas diferidas em vez de um serviço de trabalho
Configurar um controlador para cada tarefa distinta (conforme descrito nas secções anteriores) pode ser complicado, tal como serializar e desserializar argumentos complexos para a tarefa, especialmente se tiver muitas tarefas diversas, mas pequenas, que quer executar na fila. O SDK Python inclui uma biblioteca (google.appengine.ext.deferred
) que expõe uma função simples que lhe permite ignorar todo o trabalho de configuração de processadores de tarefas dedicados e serialização e desserialização dos seus parâmetros.
Para usar esta biblioteca, tem de adicionar o deferred
incorporado a app.yaml
. Para mais informações, consulte a secção Controladores incorporados da referência app.yaml
.
Para usar a biblioteca deferred
, basta transmitir a função e os respetivos argumentos a
deferred.defer()
:
import logging
from google.appengine.ext import deferred
def do_something_expensive(a, b, c=None):
logging.info("Doing something expensive!")
# Do your work here
# Somewhere else
deferred.defer(do_something_expensive, "Hello, world!", 42, True)
A biblioteca deferred
agrupa a chamada de função e os respetivos argumentos e, em seguida, adiciona-os à fila de tarefas. Quando a tarefa é executada, a biblioteca deferred
executa do_something_expensive("Hello, world!", 42, True)
.
Trabalhar com tarefas numa aplicação multi-inquilino
Por predefinição, as filas de envio usam o espaço de nomes atual, conforme definido no gestor de espaços de nomes no momento em que a tarefa é criada. Se a sua aplicação usar a funcionalidade multi-inquilino, consulte a API Namespaces Python 2.
O que se segue?
- Saiba como criar processadores de tarefas.