Como usar o gerenciamento de filas e o queue.yaml

Nesta página, explicamos as diferenças entre o uso da API Cloud Tasks para gerenciar filas e o uso do upload de um arquivo queue.yaml ou queue.xml do Cloud Tasks para atingir os mesmos fins. Além disso, você verá algumas das dificuldades encontradas ao mesclar mecanismos e como lidar com problemas comuns.

Introdução

Na Cloud Tasks API, há uma interface independente do App Engine para o serviço de Fila de Tarefas do App Engine. Como parte dessa interface, ele fornece a capacidade de gerenciar filas, inclusive por meio do console ou do comando gcloud. As filas que são criadas pela API Cloud Tasks são acessíveis a partir do App Engine SDK e vice-versa. Para manter a compatibilidade, é possível usar o arquivo de configuração usado pelo SDK do App Engine, queue.yaml, para criar e configurar filas a serem usadas por meio da API Cloud Tasks. No entanto, combinar a configuração por meio de arquivo com a configuração por meio da API Cloud Tasks pode produzir consequências inesperadas.

Armadilhas da combinação de queue.yaml com os métodos de gerenciamento de filas do Cloud Tasks

Para o serviço subjacente, os arquivos queue.yaml são definitivos. O upload de um queue.yaml que omite filas existentes no projeto, independentemente de como foram criadas, faz com que essas filas sejam desativadas ou pausadas. Portanto, se você usar a API Cloud Tasks para chamar CreateQueue ou UpdateQueue e, em seguida, fizer upload de um arquivo queue.yaml que os omita, as filas criadas nas chamadas do Cloud Tasks serão desativadas.

Pense no seguinte cenário:

  1. Chame CreateQueue para criar uma fila chamada "cloud-task-queue".
  2. Faça o upload de um arquivo queue.yaml com o seguinte conteúdo:

    queue:
    - name: queue-yaml-queue
    

Qual é o estado atual das filas neste projeto? A fila denominada "cloud-tasks-queue" e todas as filas anteriores estão no estado DISABLED, e a fila chamada "queue-yaml-queue" está no estado RUNNING.

Esse comportamento poderá ser inesperado se você criar filas por meio da API do Cloud Tasks. Nas instruções a seguir, você verá como retomar uma fila desativada.

Da mesma forma, se uma fila for desativada na API Cloud Tasks, mas depois aparecer em um arquivo queue.yaml enviado, essa fila será retomada.

Se uma fila for excluída com o método DeleteQueue e depois aparecer em um arquivo queue.yaml, o upload de queue.yaml poderá falhar porque os nomes de fila não poderão ser reutilizados por vários dias após a exclusão.

Práticas recomendadas

Se você for novo no Cloud Tasks ou no App Engine, use a API Cloud Tasks exclusivamente para gerenciar suas filas e evite o uso de queue.yaml e queue.xml em conjunto. Os usuários têm mais opções para a criação, atualização e exclusão de filas ao usarem os métodos de gerenciamento do Cloud Tasks.

No entanto, se você já for um usuário queue.yaml ou queue.xml, considere mudar para métodos de gerenciamento de filas se entender as armadilhas da combinação de queue.yaml com os métodos de gerenciamento de filas do Cloud Tasks.

Para ajudar a aplicar o uso de apenas um método de configuração, use grupos e permissões para controlar o acesso às atividades de gerenciamento de filas. Consulte Como proteger a configuração da fila para ver instruções.

Depuração

Você pode inspecionar os Registros de auditoria das atividades do administrador do seu projeto para recuperar o histórico das mudanças na configuração da fila, incluindo criações, atualizações e exclusões:

    gcloud logging read \
      'protoPayload.methodName=
       (com.google.appengine.legacy.queue_created OR
        com.google.appengine.legacy.queue_updated OR
        google.cloud.tasks.v2.CloudTasks.CreateQueue OR
        google.cloud.tasks.v2.CloudTasks.UpdateQueue OR
        google.cloud.tasks.v2.CloudTasks.DeleteQueue)'

Por exemplo, se uma fila existente for desativada por um upload de queue.yaml, uma mensagem "Fila desativada '[QUEUE_NAME]'" será exibida no registro de auditoria por meio do método com.google.appengine.legacy.queue_updated.

Como retomar uma fila desativada por um upload de queue.yaml

Se você misturar queue.yaml com os métodos de gerenciamento de filas do Cloud Tasks , fazer o upload de um arquivo queue.yaml poderá acidentalmente desativar uma fila criada por meio da API Cloud Tasks.

Para retomar a fila, você pode chamar ResumeQueue na fila ou adicioná-la a queue.yaml e fazer o upload. Se você já tiver definido um processamento personalizado rate na configuração de queue.yaml para a fila, ResumeQueue redefinirá a fila para o rate padrão. Isso é refletido no campo maxDispatchesPerSecond da resposta a ResumeQueue.

Cotas

Se você usar queue.yaml para criar suas filas, poderá, por padrão, criar um máximo de 100 filas. As filas criadas usando a API Cloud Tasks têm um padrão máximo de 1.000 filas. Como em outros casos, a combinação de métodos queue.yaml e da API Cloud Tasks pode produzir resultados inesperados. Por exemplo, suponha que você crie algumas filas usando queue.yaml e receba um aumento de cota para, por exemplo, 2.000. Se posteriormente você usar o método da API Cloud Tasks para criar mais filas, sairá dos erros de cota. Para corrigir isso, registre uma solicitação por meio de Editar cotas na página Cotas do Console do Cloud.

Informações adicionais sobre os métodos de gerenciamento de filas do Cloud Tasks

Configuração de filas e atraso da inicialização de filas

As mudanças na configuração de filas podem levar vários minutos. Por exemplo, depois de chamar CreateQueue ou UpdateQueue, vários minutos podem passar antes que você possa chamar CreateTask nessa fila com êxito.

Cloud Tasks e a fila do App Engine default

A fila do App Engine chamada "padrão" recebe tratamento especial no SDK do App Engine e na API Cloud Tasks.

Se a fila default ainda não existir, ela será criada nas seguintes situações:

  1. Quando uma tarefa é adicionada pela primeira vez à fila default usando o SDK do App Engine.
  2. Quando um arquivo queue.yaml que especifica uma fila default é enviado.
  3. Quando CreateQueue ou UpdateQueue é chamado para criar a fila default.

Para preservar a compatibilidade com o App Engine, o Cloud Tasks impõe as seguintes restrições:

  1. Se uma fila chamada "default" é criada, ela precisa ser uma fila do App Engine.
  2. Depois de criada, os usuários não podem excluir a fila default.

Na API Cloud Tasks, o seguinte também se aplica à fila default:

  1. A API Cloud Tasks não cria automaticamente a fila default ou qualquer outra fila.
  2. Assim como qualquer outra fila, chamar GetQueue na fila default resulta em um erro não encontrado se a chamada for feita antes da criação da fila.
  3. Da mesma forma, a fila default não aparece na saída de ListQueues antes de ser criada.
  4. A configuração da fila default pode ser alterada com a chamada UpdateQueue.

A seguir