Como migrar filas push para o Cloud Tasks (Go)

Antes de fazer upgrade para a versão mais recente do SDK dos serviços do App Engine, consulte a visão geral da migração.

Fazer upgrade para as bibliotecas de cliente do Cloud Tasks

Se você preferir abandonar os serviços incluídos legados, migre seu código para usar a API Cloud Tasks diretamente. Isso exige a refatoração do código do aplicativo.

Com o Cloud Tasks, é possível acessar o mesmo serviço acessado com a API RPC Task Queues. Isso significa que você não precisa para recriar filas e tarefas push atuais. No entanto, é necessário migrar o código que cria ou interage com filas ou tarefas push para usar a API Cloud Tasks.

É possível criar e interagir com filas push e tarefas push usando as APIs REST e RPC do Cloud Tasks, a biblioteca de cliente do Cloud Tasks, a Google Cloud CLI e o Google Cloud console. Nesta página, apresentamos exemplos que usam a CLI gcloud e a biblioteca de cliente do Cloud Tasks.

Recursos não disponíveis no Cloud Tasks

Para a migração das bibliotecas de cliente do Cloud Tasks, os seguintes recursos não estão disponíveis no Cloud Tasks:

  • Enfileirar tarefas em transações do Datastore
  • Usar a biblioteca de tarefas adiadas em vez de um serviço de worker
  • Trabalhar com tarefas em aplicativos com vários locatários
  • Simular com o servidor de desenvolvimento local
  • Como adicionar tarefas de maneira assíncrona

Como alternativa, se você fizer upgrade para o SDK mais recente, os recursos como tarefas adiadas, namespaces e simulação local serão compatíveis com o wrapper do SDK.

Preços e cotas

Migrar suas filas push para o Cloud Tasks pode afetar os preços e as cotas do seu aplicativo.

Preços

Revise os preços do Cloud Tasks para estimar o custo mensal antes da migração.

Assim como nas filas de tarefas, o envio de solicitações para o aplicativo do App Engine com um destino push do Cloud Tasks é sem custo financeiro. No entanto, ao contrário das filas de tarefas, o Cloud Tasks cobra pela operação realizada, como criar, excluir ou gerenciar tarefas. Isso pode levar a um custo mensal geral maior em comparação com a fila de tarefas complementar do App Engine.

Cotas

As solicitações do Cloud Tasks também são contabilizadas nas cotas de solicitações do App Engine.

Assim como as filas de tarefas, o Cloud Tasks tem cotas específicas do serviço. A migração para o Cloud Tasks provavelmente mudará suas cotas.

Antes de começar

As seções a seguir discutem as etapas de configuração que devem anteceder a migração de filas push para o Cloud Tasks.

Migrar filas pull

Para começar, migre as filas pull antes de seguir as instruções deste guia de migração de filas push. A migração de filas pull após a migração de filas push não é recomendada porque o uso obrigatório do arquivo queue.yaml provavelmente causará um comportamento inesperado no Cloud Tasks.

Como proteger a configuração da fila

Depois de iniciar o processo de migração para o Cloud Tasks, modificar o arquivo queue.yaml pode causar comportamento inesperado e não é recomendado. Proteja a configuração da fila contra modificações pelo arquivo queue.yaml seguindo estas etapas:

  1. Configure a CLI gcloud para omitir o arquivo queue.yaml em implantações futuras.

    Adicione o arquivo queue.yaml a um arquivo .gcloudignore. Para verificar se você já tem um arquivo .gcloudignore, execute o seguinte comando no terminal a partir do diretório de nível superior do aplicativo. Esse comando exibirá o nome do arquivo, se ele existir.

    ls -a | grep .gcloudignore

    Saiba mais sobre arquivos .gcloudignore lendo a referência de .gcloudignore.

  2. Restrinja as permissões no arquivo queue.yaml.

    Siga as práticas recomendadas descritas no nosso guia sobre como proteger a configuração da fila.

  3. Saiba mais sobre o Cloud Tasks e o arquivo queue.yaml (opcional).

    Quando você usa a API Cloud Tasks para gerenciar a configuração da fila, a implantação de um arquivo queue.yaml substitui a configuração definida pelo Cloud Tasks, o que pode causar um comportamento inesperado. Leia Como usar o gerenciamento de filas versus queue.yaml para saber mais.

Autenticar o aplicativo na API Cloud Tasks

Você precisa autenticar o aplicativo na API Cloud Tasks. Nesta seção, discutimos a autenticação para dois casos de uso diferentes.

Para desenvolver ou testar seu aplicativo localmente, recomendamos usar uma conta de serviço. Para instruções sobre como configurar uma conta de serviço e conectá-la ao aplicativo, consulte Como receber e fornecer credenciais de conta de serviço manualmente.

Para implantar o aplicativo no App Engine, não é preciso fornecer autenticação. As Application Default Credentials (ADC, na sigla em inglês) inferem detalhes de autenticação de aplicativos do App Engine.

Importar as bibliotecas de cliente do Cloud

Para usar a biblioteca de cliente do Cloud Tasks com o aplicativo do App Engine:

  1. Faça o download da dependência da biblioteca de cliente do Cloud Tasks:

    go get cloud.google.com/go/cloudtasks/apiv2

  2. Importe as dependências da biblioteca de cliente do Cloud Tasks nos arquivos responsáveis por criar e enfileirar suas tarefas:

    import (
  "context"
  "fmt"

  cloudtasks "cloud.google.com/go/cloudtasks/apiv2"
  taskspb "cloud.google.com/go/cloudtasks/apiv2/cloudtaskspb"
)

Criar e gerenciar filas

Nesta seção, descrevemos como criar e gerenciar filas usando a API Cloud Tasks.

Com o Cloud Tasks, você não usa um arquivo queue.yaml para criar ou gerenciar filas. Em vez disso, use a API Cloud Tasks. Não é recomendado usar um arquivo queue.yaml e a API Cloud Tasks, mas isso pode ser inevitável na migração do Task Queues para o Cloud Tasks, dependendo do aplicativo. Leia Como usar o gerenciamento de filas versus queue.yaml para saber mais sobre as práticas recomendadas.

Criar filas

Leia esta seção se o aplicativo criar filas de maneira programática ou se você quiser criar filas adicionais a partir da linha de comando.

No Cloud Tasks, os nomes de fila têm o formato projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID. A LOCATION_ID parte do nome da fila corresponde a uma Google Cloud região. A parte QUEUE_ID do nome da fila é equivalente ao campo name da fila de tarefas. O nome da fila é gerado durante a criação da fila com base no projeto, na região e no QUEUE_ID que você especificar.

Em geral, o local da fila (ou seja, a região) precisa ser o mesmo da região do aplicativo. As duas exceções a essa regra são aplicativos que usam a região europe-west e aplicativos que usam a região us-central. No Cloud Tasks, essas regiões são chamadas de europe-west1 e us-central1, respectivamente.

É possível especificar a configuração de fila opcional durante a criação da fila, mas você também pode fazer isso atualizando a fila depois de criá-la.

Você não precisa recriar as filas atuais. Em vez disso, migre o código que interage com as filas atuais lendo as partes relevantes deste guia.

Reutilizar nomes de fila

Aguarde sete dias após a exclusão de uma fila para criar uma com o mesmo ID de fila no mesmo projeto e local (ou seja, região).

O exemplo a seguir cria duas filas usando o Cloud Tasks. A primeira fila tem o ID queue-blue e está configurada para enviar todas as tarefas para a versão v2 do serviço task-module a uma taxa de 5/s. A segunda fila tem o ID queue-red e envia tarefas a uma taxa de 1/s. Ambos são criados no projeto com o ID do projeto no local us-central1. Esse é o equivalente no Cloud Tasks à criação de filas no Task Queues.

gcloud

A CLI gcloud infere o projeto e o local a partir da configuração da CLI gcloud.

gcloud tasks queues create queue-blue \
    --max-dispatches-per-second=5 \
    --routing-override=service:task-module,version:v2
 
gcloud tasks queues create queue-red \
    --max-dispatches-per-second=1

Saiba mais na referência do Cloud Tasks Como criar uma fila do Cloud Tasks queue.

Definir a taxa de processamento da fila

A tabela a seguir lista os campos que são diferentes das Filas de tarefas para o Cloud Tasks.

Campo no Task Queues Campo no Cloud Tasks Descrição
rate max_dispatches_per_second A taxa máxima na qual as tarefas são enviadas de uma fila
max_concurrent_requests max_concurrent_dispatches O número máximo de tarefas simultâneas que podem ser enviadas da fila
bucket_size max_burst_size

O Cloud Tasks calcula uma propriedade get-only max_burst_size que limita a velocidade de processamento das tarefas na fila com base no valor de max_dispatches_per_second. O campo permite que a fila tenha uma taxa alta. Assim, o processamento começará logo depois que uma tarefa for colocada na fila, mas ainda limitará o uso de recursos quando muitas tarefas estiverem na fila em um curto período.

Para filas do App Engine que foram criadas ou atualizadas usando um arquivo, max_burst_size é inicialmente igual a bucket_size. No entanto, se a fila for transmitida posteriormente para um update comando usando qualquer interface do Cloud Tasks, max_burst_size será redefinido com base no valor de max_dispatches_per_second, independentemente de max_dispatches_per_second ser atualizado.

total_storage_limit Obsoleto no Cloud Tasks No momento, o Cloud Tasks não é compatível com a configuração de um limite de armazenamento personalizado

É possível definir a taxa de processamento da fila ao criá-la ou atualizá-la depois. O exemplo abaixo usa o Cloud Tasks para definir a taxa de processamento de uma fila chamada queue-blue já criada. Se queue-blue foi criado ou configurado usando um arquivo queue.yaml, o seguinte exemplo redefinemax_burst_size com base no valor max_dispatches_per_second de 20. Esse é o equivalente no Cloud Tasks à definição da taxa de processamento de filas no Task Queues.

gcloud

gcloud tasks queues update queue-blue \
    --max-dispatches-per-second=20 \
    --max-concurrent-dispatches=10

Saiba mais em Definir limites de taxa.

Desativar e retomar filas

O Cloud Tasks usa o termo pausar da mesma forma que o Task Queues usa o termo desativar. Pausar uma fila interrompe a execução das tarefas até que a fila seja retomada. No entanto, é possível continuar adicionando tarefas a uma fila pausada. O Cloud Tasks usa o termo retomar da mesma forma que o Task Queues.

O exemplo a seguir pausa uma fila com o ID queue1. Esse é o equivalente no Cloud Tasks a desativar filas no Task Queues.

gcloud

gcloud tasks queues pause queue1

Saiba mais na referência do Cloud Tasks Como pausar filas.

Excluir filas

Depois de excluir uma fila, aguarde sete dias antes de criar uma fila com o mesmo nome. Considere limpar todas as tarefas de uma fila e reconfigurar a fila, se não puder esperar sete dias.

O exemplo a seguir exclui a fila com o ID queue1 Esse é o equivalente no Cloud Tasks à exclusão de filas no Task Queues.

gcloud

gcloud tasks queues delete queue1

Saiba mais na referência do Cloud Tasks Como excluir filas.

Criar e gerenciar tarefas

Nesta seção, descrevemos como criar e gerenciar tarefas usando a API Cloud Tasks.

Criar tarefas

A tabela a seguir lista os campos que são diferentes das Filas de tarefas para o Cloud Tasks.

Campo no Task Queues Campo no Cloud Tasks Descrição
N/A app_engine_http_request Cria uma solicitação que visa um serviço do App Engine. Essas tarefas são chamadas de tarefas do App Engine.
method http_method Especifica o método da solicitação. por exemplo, POST
url relative_uri Especifica o gerenciador de tarefas. Observe a diferença na letra final: i para identificador uniforme de recursos em vez de l para localizador uniforme de recursos
target app_engine_routing Opcional. Especifica service, version e instance do App Engine para uma tarefa do App Engine. Se não for definido, o serviço, a versão e a instância padrão serão usados.

O exemplo a seguir cria uma tarefa que roteia para o gerenciador /update_counter no serviço padrão do App Engine. Esse é o equivalente do Cloud Tasks à criação de tarefas nas filas de tarefas.

gcloud

gcloud tasks create-app-engine-task \
    --queue=default \
    --method=POST \
    --relative-uri=/update_counter \
    --routing=service:worker \
    --body-content=10

Saiba mais na referência do Cloud Tasks Como criar tarefas do App Engine.

Especificar o serviço de destino e o roteamento

A especificação do serviço, da versão e da instância de destino do App Engine para tarefas do App Engine é opcional. Por padrão, as tarefas do App Engine são encaminhadas para o serviço, a versão e a instância que são o padrão no momento em que a tarefa é tentada.

Defina a propriedade app_engine_routing da tarefa durante a criação dela para especificar um serviço, uma versão ou uma instância diferente do App Engine.

Para encaminhar todas as tarefas de uma determinada fila para o mesmo serviço, versão e instância do App Engine, defina a propriedade app_engine_routing_override na fila.

Saiba mais na referência do Cloud Tasks Configurar roteamento.

Transmitir dados para o gerenciador

Assim como no Task Queues, é possível transmitir dados para o gerenciador de duas maneiras usando o Cloud Tasks. Você pode transmitir dados como parâmetros de consulta no URI relativo ou transmiti-los no corpo da solicitação usando os métodos HTTP POST ou PUT.

O Cloud Tasks usa o termo corpo da mesma forma que o Task Queues usa o termo payload. No Cloud Tasks, o tipo de conteúdo padrão do corpo é octet-stream, e não texto simples. É possível definir o tipo de conteúdo do body especificando-o no cabeçalho.

O exemplo a seguir transmite uma chave para o gerenciador /update_counter de duas maneiras diferentes. Esse é o equivalente no Cloud Tasks à transmissão de dados para o gerenciador no Task Queues.

gcloud

gcloud tasks create-app-engine-task \
    --queue=default \
    --method=GET  \
    --relative-uri=/update_counter?key=blue \
    --routing=service:worker
 
gcloud tasks create-app-engine-task \
    --queue=default \
    --method=POST \
    --relative-uri=/update_counter \
    --routing=service:worker \
    --body-content="{'key': 'blue'}"

Especificar o nome da tarefa

A especificação do nome da tarefa é opcional. Se você não especificar o nome da tarefa, o Cloud Tasks criará um para você, gerando um ID da tarefa e inferindo o projeto e o local (isto é, a região) com base na fila especificada durante a criação da tarefa.

Os nomes das tarefas têm o formato projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID. A parte TASK_ID do nome da tarefa é equivalente ao campo name da tarefa no Task Queues.

Reutilizar nomes de tarefas

Você precisa aguardar antes de reutilizar o nome de uma tarefa. O tempo que você precisa aguardar varia conforme a fila que envia a tarefa foi criada no Cloud Tasks ou no Task Queues.

Para tarefas em filas que foram criadas usando o Task Queues (incluindo a fila padrão), você precisa aguardar cerca de nove dias após a tarefa original ter sido excluída ou executada. Para tarefas em filas que foram criadas usando o Cloud Tasks, você precisa aguardar aproximadamente uma hora após a tarefa original ter sido excluída ou executada.

O exemplo a seguir cria uma tarefa com TASK_ID definido como first-try e o adiciona à fila padrão. Este é o equivalente no Cloud Tasks à nomeação de tarefas no Task Queues.

gcloud

A CLI gcloud cria o nome da tarefa inferindo o projeto e o local da configuração.

gcloud tasks create-app-engine-task first-try \
    --queue=default \
    --method=GET \
    --relative-uri=/url/path

Repetir tarefas com falha

É possível definir a configuração de repetição de tarefas em filas durante a criação ou atualizando a fila. A tabela a seguir lista o campo "Filas de tarefas" e o campo correspondente do Cloud Tasks.

Campo no Task Queues Campo no Cloud Tasks
task_retry_limit max_attempts
task_age_limit max_retry_duration
min_backoff_seconds min_backoff
max_backoff_seconds max_backoff
max_doublings max_doublings

Usar parâmetros de repetição específicos da tarefa

Os parâmetros de repetição específicos da tarefa configurados no Task Queues funcionam no Cloud Tasks. No entanto, não é possível editá-los ou defini-los em novas tarefas. Para alterar os parâmetros de repetição de uma tarefa que tenha parâmetros de repetição específicos, recrie a tarefa com uma fila do Cloud Tasks que tenha os parâmetros de repetição desejados.

O exemplo a seguir demonstra vários cenários de novas tentativas:

  • Em fooqueue, as tarefas são repetidas até sete vezes e por até dois dias a partir da primeira tentativa de execução. Depois que ambos os limites são atingidos, elas falham permanentemente.
  • Em barqueue, o Google App Engine tenta repetir tarefas, aumentando o intervalo linearmente entre cada nova tentativa até atingir a espera máxima e repetindo indefinidamente no intervalo máximo. Assim, os intervalos entre solicitações são de 10s, 20s, 30s, ..., 190s, 200s, 200s e assim por diante.
  • Em bazqueue, o intervalo de repetição começa em 10s, depois duplica três vezes, aumenta linearmente e, finalmente, repete indefinidamente no intervalo máximo. Dessa forma, os intervalos entre solicitações são: 10s, 20s, 40s, 80s, 160s, 240s, 300s, 300s ...

Este é o equivalente do Cloud Tasks à repetição de tarefas no Task Queues.

gcloud

Ao definir opções que especifiquem um número de segundos, você precisa incluir s após o número inteiro (por exemplo, 200s, e não 200).

gcloud tasks queues create fooqueue \
    --max-attempts=7 \
    --max-retry-duration=172800s  #2*60*60*24 seconds in 2 days
 
gcloud tasks queues create barqueue \
    --min-backoff=10s \
    --max-backoff=200s \
    --max-doublings=0
 
gcloud tasks queues create bazqueue \
    --min-backoff=10s \
    --max-backoff=300s \
    --max-doublings=3

Saiba mais na referência do Cloud Tasks Definir parâmetros de repetição.

Excluir tarefas de uma fila

Ao excluir uma tarefa, aguarde nove dias antes de criá-la com o mesmo nome se ela estava em uma fila criada usando um arquivo queue.yaml ou uma hora, se ela estava em uma fila criada usando o Cloud Tasks.

O exemplo a seguir exclui a tarefa com o ID de tarefa foo da fila com o ID de fila queue1. Esse é o equivalente no Cloud Tasks à exclusão de tarefas no Task Queues.

gcloud

O projeto e o local da tarefa são inferidos do projeto padrão da CLI gcloud.

gcloud tasks delete foo --queue=queue1

Para saber mais, leia a referência do Cloud Tasks Como excluir uma tarefa de uma fila.

Limpar tarefas

O exemplo a seguir limpa todas as tarefas da fila com o ID da fila queue1. Este é o equivalente no Cloud Tasks à limpeza de tarefas no Task Queues.

gcloud

O projeto e o local da fila são inferidos do projeto padrão da CLI gcloud.

gcloud tasks queues purge queue1

Saiba mais na referência do Cloud Tasks Como limpar todas as tarefas de uma fila.

A seguir