Procesos de trabajo de cola

Los procesos de trabajo de cola procesan elementos de colas de trabajo usando pestañas de navegador concurrentes. Cada proceso obtiene su propia pestaña, extrae elementos de la cola, ejecuta un script sobre cada uno y confirma o aborta el resultado.

Concepto

1. Usted pone elementos de trabajo en cola: URL, registros de datos o tareas
2. Los procesos extraen elementos y los procesan, cada uno en su propia pestaña de navegador
3. Su script por elemento llama a g.worker.getContext() para obtener el elemento, hace su trabajo y luego llama a g.queue.commit() o g.queue.abort()

El panel Workers muestra pools activos, conteos procesados, fallos, profundidad de cola y controles para pausar o detener trabajo.

Dos formas de definir procesos

Declarativa: queues.json

Cree un archivo queues.json en la raíz de su espacio de trabajo:

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

Campo	Requerido	Predeterminado	Descripción
queue	Sí	—	Nombre de la cola que procesar
script	Sí	—	Ruta del script relativa a la raíz del espacio de trabajo
concurrency	No	1	Número de procesos concurrentes, es decir pestañas
throttle	No	60	Máximo de extracciones por minuto por proceso
layout	No	—	Disposición de pestañas: horizontal, vertical o quad
clearTabs	No	false	Cierra todas las pestañas existentes antes de empezar
requiresWorkflowEnvelope	No	false	Exige que cada elemento de cola lleve metadatos del registro de trazabilidad antes de ejecutarse

Inicie un pool declarado desde la Queue Console, el panel ligero Queues o herramientas MCP.

Programática: g.workers.start()

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

  // Start workers
  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() es fire-and-forget: los procesos se ejecutan de forma independiente del script lanzador.

Script por elemento

Cada proceso ejecuta su script una vez por elemento de cola. El script debe:

1. Llamar a g.worker.getContext() para obtener el elemento y el ID de pestaña
2. Hacer su trabajo
3. Llamar a g.queue.commit() o g.queue.abort()

scripts/scrape-page.js

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

  // Navigate in this worker's tab
  await g.nav.navigateToUrl(item.data.url, { browserTabId: tabId });
  await g.dom.waitForDomStable({ browserTabId: tabId });

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

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

  // Mark complete
  g.queue.commit(item.id);
}

No hay confirmación automática: debe confirmar o abortar explícitamente cada elemento.

Manejo de fallos

Si su script aborta un elemento y este superó su maxRetries, el elemento pasa a la cola de rechazos (dead_{queueName}). Puede inspeccionar y reintentar elementos rechazados:

const deadItems = g.queue.deadLetter("pages");
g.log("Failed items: " + deadItems.length);

// Retry a specific item
g.queue.retry("pages", deadItems[0].deadLetterId);

Controlar procesos

Método	Descripción
g.workers.stop()	Detiene todos los procesos
g.workers.stop("pages")	Detiene procesos de una cola específica
g.workers.pause()	Pausa la extracción de cola; los elementos en curso terminan
g.workers.resume()	Reanuda la extracción
g.workers.status()	Obtiene el estado de todos los pools

El estado devuelve un array de instantáneas de pool:

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

Gestión de pestañas

Los procesos crean automáticamente una pestaña de navegador por proceso concurrente. La opción layout las organiza:

• horizontal — pestañas lado a lado
• vertical — pestañas apiladas
• quad — cuadrícula 2x2, para 4 procesos

Defina clearTabs: true para cerrar todas las pestañas existentes antes de empezar.

Limitación de ritmo

El ajuste throttle controla la rapidez con la que cada proceso extrae elementos de cola. Un valor de 30 significa que cada proceso espera al menos 2 segundos entre extracciones. Con concurrency: 3 y throttle: 30, el pool procesa hasta 90 elementos por minuto en total.

Monitorización y operaciones

Cada ejecución de elemento de proceso aparece como una tarea en el panel Task Manager, con duración en vivo y botones de parada.

Para operaciones diarias sobre colas, use la Queue Console. Muestra conteos de colas, elementos pendientes, colas de rechazos, contenidos seleccionados, estado de procesos, controles run-one/start/stop y enlaces a elementos del Workflow Ledger cuando los contenidos de cola contienen metadatos de flujo.

Si un script de proceso falla después de tomar un elemento, Guida aborta la toma cuando es posible para que el elemento no quede atascado. Detener una tarea Run One o un pool debe detener trabajo futuro y devolver el trabajo de cola en curso a un estado inspeccionable.

Cuando los elementos de cola están vinculados a elementos del registro, las rutas de reintento de cola y run-one primero aseguran que el elemento del registro sea reclamable. Si Guida no puede reconciliar el elemento de cola y el estado del registro, muestra un error orientado al operador en lugar de crear trabajo de cola destinado a fallar.

Para colas pertenecientes a un flujo, defina requiresWorkflowEnvelope: true en queues.json o g.workers.start(). Guida rechaza entonces procesar elementos de cola salvo que su contenido incluya una envoltura de flujo con workflowName, runId, itemId y itemKey.

Esto es útil para crawls largos donde el trabajo de cola y la verdad del Workflow Ledger deben permanecer sincronizados. El trabajo tomado pero inválido se bloquea y se mueve a un estado de fallo inspeccionable en lugar de repetir reintentos sin salida.

Para grandes canalizaciones que abarcan varias carpetas de flujo, colas, pools de procesos y etapas del registro, modele la intención de nivel operador en Flujos de trabajo. La Workflow Control Console puede mostrar qué cola o proceso necesita atención y abrir la Queue Console sobre la evidencia relevante.

Revisión manual

Para colas que requieren juicio humano, las vistas de modo Review proporcionan botones de acción, atajos de teclado y revisión multipestaña. Vea Colas y revisión.

Siguientes pasos

• Colas y revisión — operar colas, inspeccionar contenidos y revisar elementos
• Workflow Ledger — inspeccionar estado duradero de flujos e historial de recuperación
• Flujos de trabajo — describir operaciones de nivel operador y traspasos cola/registro
• Poner URL en cola y procesarlas — ejemplo completo de poner, procesar y confirmar elementos de trabajo
• Ejecutar procesos de trabajo en paralelo — iniciar varios procesos de navegador desde un script
• Referencia de API — g.queue.* — operaciones de cola
• Referencia de API — g.workers.* — métodos de gestión de procesos
• Espacios de trabajo — configuración del espacio de trabajo para queues.json