Processos de trabalho das filas

Processos de trabalho das filas processam itens de filas de trabalho usando guias de navegador concorrentes. Cada processo recebe sua própria guia, retira itens da fila, executa um script para cada item e confirma ou aborta o resultado.

Conceito

Você enfileira itens de trabalho, como URLs, registros de dados ou tarefas
Processos de trabalho retiram itens da fila e os processam, cada um em sua própria guia do navegador
Seu script por item chama g.worker.getContext() para obter o item, faz o trabalho e então chama g.queue.commit() ou g.queue.abort()

Painel de processos de trabalho mostrando um grupo job_checks ativo com 116 concluídos e 39 itens em fila

O painel de processos de trabalho mostra grupos ativos, contagens processadas, falhas, profundidade da fila e controles para pausar ou parar trabalho.

Duas formas de definir processos de trabalho

Declarativa: `queues.json`

Crie um arquivo queues.json na raiz do seu espaço de trabalho:

{
  "pools": [
    {
      "queue": "urls",
      "script": "scripts/process-url.js",
      "concurrency": 3,
      "throttle": 30,
      "layout": "horizontal",
      "clearTabs": true
    }
  ]
}

Campo	Obrigatório	Padrão	Descrição
`queue`	Sim	—	Nome da fila a processar
`script`	Sim	—	Caminho do script relativo à raiz do espaço de trabalho
`concurrency`	Não	1	Número de processos concorrentes (guias)
`throttle`	Não	60	Máximo de retiradas da fila por minuto por processo
`layout`	Não	—	Layout das guias: `horizontal`, `vertical` ou `quad`
`clearTabs`	Não	false	Fecha todas as guias existentes antes de iniciar
`requiresWorkflowEnvelope`	Não	false	Exige que cada item de fila carregue metadados do registro de rastreabilidade antes da execução

Inicie um grupo declarado pelo Queue Console, pelo painel leve Queues ou por ferramentas MCP.

Programática: `g.workers.start()`

async function main() {
  // Enfileirar algum trabalho
  for (let i = 1; i <= 100; i++) {
    g.queue.enqueue("pages", {
      url: "https://example.com/page/" + i
    });
  }

  // Iniciar processos de trabalho
  g.workers.start({
    clearTabs: true,
    layout: "horizontal",
    workers: [
      {
        queue: "pages",
        script: "scripts/scrape-page.js",
        concurrency: 4,
        throttle: { requestsPerMinute: 20 },
        requiresWorkflowEnvelope: false
      }
    ]
  });
}

g.workers.start() é disparado sem espera: os processos de trabalho rodam independentemente do script que os iniciou.

Script por item

Cada processo de trabalho executa seu script uma vez por item de fila. O script deve:

Chamar g.worker.getContext() para obter o item e o ID da guia
Fazer o trabalho
Chamar g.queue.commit() ou g.queue.abort()

async function main() {
  const ctx = g.worker.getContext();
  const { item, tabId, queueName } = ctx;

  // Navegar na guia deste processo de trabalho
  await g.nav.navigateToUrl(item.data.url, { browserTabId: tabId });
  await g.dom.waitForDomStable({ browserTabId: tabId });

  // Extrair dados
  const title = await g.dom.extractContent("h1", { browserTabId: tabId });

  // Armazenar resultado
  g.store.put("results", item.data.url, {
    title: title,
    scrapedAt: new Date().toISOString()
  });

  // Marcar como concluído
  g.queue.commit(item.id);
}

Não há commit automático: você precisa confirmar ou abortar cada item explicitamente.

Tratar falhas

Se seu script abortar um item e ele exceder maxRetries, o item vai para a fila de rejeitos (dead_{queueName}). Você pode inspecionar e tentar novamente itens rejeitados:

const deadItems = g.queue.deadLetter("pages");
g.log("Itens com falha: " + deadItems.length);

// Tentar novamente um item específico
g.queue.retry("pages", deadItems[0].deadLetterId);

Controlar processos de trabalho

Método	Descrição
`g.workers.stop()`	Para todos os processos de trabalho
`g.workers.stop("pages")`	Para processos de trabalho de uma fila específica
`g.workers.pause()`	Pausa retiradas da fila; itens em andamento terminam
`g.workers.resume()`	Retoma retiradas da fila
`g.workers.status()`	Obtém status de todos os grupos

O status retorna um array de instantâneos de grupos:

{
  queue: string
  script: string
  concurrency: number
  activeWorkers: number
  processed: number
  failed: number
  remaining: number
  paused: boolean
}

Gerenciamento de guias

Processos de trabalho criam automaticamente uma guia do navegador por processo concorrente. A opção layout as organiza:

horizontal — guias lado a lado
vertical — guias empilhadas
quad — grade 2x2 para 4 processos

Use clearTabs: true para fechar todas as guias existentes antes de iniciar.

Throttling

A configuração throttle controla a velocidade com que cada processo retira itens da fila. Um valor de 30 significa que cada processo espera pelo menos 2 segundos entre retiradas. Com concurrency: 3 e throttle: 30, o grupo processa até 90 itens por minuto no total.

Monitoramento e operações

Cada execução de item por worker aparece como uma tarefa no painel Task Manager, com duração ao vivo e botões de parada.

Para operações diárias de fila, use o Queue Console. Ele mostra contagens de fila, itens pendentes, itens rejeitados, conteúdos selecionados, estado dos processos de trabalho, controles run-one/start/stop e links para itens do registro de rastreabilidade quando os conteúdos de fila contêm metadados de fluxo de trabalho.

Se um script de processo de trabalho falha depois de retirar um item, o Guida aborta a retirada quando possível para que o item não fique preso. Parar uma tarefa Run One ou grupo de processos deve interromper trabalho futuro e devolver trabalho em andamento a um estado inspecionável.

Quando itens de fila estão vinculados a itens do registro de rastreabilidade, caminhos de nova tentativa e run-one da fila primeiro garantem que o item do registro possa ser reivindicado. Se o Guida não consegue reconciliar o item de fila com o estado do registro, ele mostra erro voltado ao operador em vez de criar trabalho de fila que certamente falhará.

Para filas pertencentes a fluxos de trabalho, defina requiresWorkflowEnvelope: true em queues.json ou g.workers.start(). O Guida então se recusa a processar itens de fila cujo conteúdo não inclua um envelope de fluxo de trabalho com workflowName, runId, itemId e itemKey.

Isso é útil para rastreamentos longos em que trabalho em fila e verdade do registro de rastreabilidade precisam permanecer sincronizados. Trabalho inválido retirado da fila é bloqueado e movido para um estado de falha inspecionável em vez de circular por novas tentativas condenadas.

Para grandes fluxos que cruzam várias pastas de workflow, filas, grupos de processos de trabalho e estágios do registro, modele a intenção operacional em Fluxos de trabalho. O Workflow Control Console pode então mostrar qual fila ou processo precisa de atenção e abrir o Queue Console na evidência relevante.

Revisão manual

Para filas que precisam de julgamento humano, visões em modo de revisão oferecem botões de ação, atalhos de teclado e modo de revisão multi-guia. Veja Filas e revisão.

Próximos passos

Filas e revisão — opere filas, inspecione conteúdos e revise itens
Registro de rastreabilidade dos fluxos de trabalho — inspecione estado durável do fluxo de trabalho e histórico de recuperação
Fluxos de trabalho — descreva operações no nível do operador e passagens entre fila e registro
Enfileirar URLs e processá-las — exemplo completo de enfileirar, processar e confirmar itens de trabalho
Executar processos de trabalho em paralelo — iniciar vários processos de navegador a partir de um script
Referência da API — g.queue.* — operações de fila
Referência da API — g.workers.* — métodos de gerenciamento de processos de trabalho
Espaços de trabalho — configuração do espaço de trabalho para queues.json