Criar tarefas

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, crie um objeto PushTask e chame o respetivo método add(). Pode adicionar a uma fila especificada em queue.yaml fornecendo um argumento de nome da fila a add(). Em alternativa, chamar add() sem argumentos adiciona a tarefa à fila predefinida.

Também pode adicionar tarefas em massa a uma fila através da PushQueue. No exemplo seguinte, são adicionados dois objetos PushTask a uma PushQueue através do método addTasks().

O seguinte exemplo de código mostra como adicionar uma única tarefa:

$task = new PushTask(
    '/worker',
    ['name' => 'john doe', 'action' => 'send_reminder']);
$task_name = $task->add();

O seguinte exemplo de código mostra como adicionar várias tarefas em simultâneo:

$task1 = new PushTask('/someUrl');
$task2 = new PushTask('/someOtherUrl');
$queue = new PushQueue();
$queue->addTasks([$task1, $task2]);

Quando usar PushTask e PushQueue, inclua estas declarações na parte superior do ficheiro PHP:

use google\appengine\api\taskqueue\PushTask;
use google\appengine\api\taskqueue\PushQueue;

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 quando cria a tarefa através do parâmetro de cabeçalho na matriz $options quando cria o objeto PushTask: 

    $task = new PushTask(
    '/worker',
    [],
    ['header' => "Host: versionHostname"]);

  • Inclua uma diretiva target quando definir uma fila no elemento queue.yaml, como na definição de queue-blue. Todas as tarefas adicionadas a uma fila com um target 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.

O construtor PushTask tem um argumento posicional para query_data. Os dados são normalmente um dicionário de pares de chave/valor. Se o método da tarefa for POST ou PUT, os dados são adicionados à carga útil do pedido HTTP. Se o método for GET, é adicionado ao URL como parâmetros de consulta.

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.

O que se segue?