← Volver al blog

Escribir su primer script g.*

· 5 min de lectura ·
tutorial

Ya instaló Guida, hizo clic por algunas páginas y quizá miró los ajustes. ¿Y ahora qué? Este artículo le guía en la escritura de su primer script real: uno que navega a una página, extrae datos de ella y los guarda en un lugar útil.

No necesita experiencia previa en scripting. Si ya escribió algo de JavaScript, se sentirá cómodo. Si no, la API es lo bastante pequeña como para aprenderla mientras avanzamos.

Abrir el editor de scripts

Pulse Ctrl+N o vaya a File > New Script. Obtendrá una pestaña de editor vacía con IntelliSense ya conectado. Escriba g. y verá toda la superficie de la API: más de 160 métodos organizados en espacios de nombres como g.store, g.queue, g.search y otros.

Todos los scripts de Guida tienen la misma forma:

async function main() {
  // su codigo aqui
}

La palabra clave async importa: la mayoría de los métodos g.* son asíncronos porque hablan con un navegador activo. El runtime llama a main() por usted; basta con definirla y pulsar F5 para ejecutar.

Empecemos con algo simple. Iremos a Hacker News y esperaremos a que la página cargue:

async function main() {
  await g.nav.navigateToUrl("https://news.ycombinator.com");
  await g.dom.waitForDomStable();
}

g.nav.navigateToUrl() indica a la pestaña activa del navegador que cargue una URL. g.dom.waitForDomStable() espera hasta que el DOM deje de cambiar: no aparecen más elementos, no hay indicadores de carga ni contenido diferido todavía entrando. Juntos, son la base de cualquier script de automatización.

Ejecutelo con F5. Verá que la pestaña del navegador navega a Hacker News. El panel de consola inferior mostrará un mensaje de éxito.

Cómo funcionan los métodos g.*

Antes de seguir, hay una convención que debe conocer. Todos los métodos g.* devuelven su resultado directamente y lanzan una excepción si hay error.

await g.nav.navigateToUrl("https://example.com");

Si la operación tiene éxito, el valor devuelto contiene el resultado. Si falla, se lanza una excepción. Use try/catch para manejar errores:

try {
  const elements = await g.dom.getElements(".item", ["innerText"]);
  g.log("Found " + elements.length + " items");
} catch (e) {
  g.log("Couldn't find items: " + e.message);
  return;
}

g.log() escribe un mensaje en el panel Console.

Extraer datos de la página

Ahora hagamos algo útil. Tomaremos los títulos y enlaces de Hacker News:

async function main() {
  await g.nav.navigateToUrl("https://news.ycombinator.com");
  await g.dom.waitForDomStable();


  const items = await g.dom.getElements(
    ".titleline > a",
    ["innerText", "href"]
  );


  g.log("Found " + items.length + " stories");


  for (const item of items) {
    g.log(item.innerText);
  }
}

g.dom.getElements(selector, attributes) consulta el DOM y devuelve un array de objetos, cada uno con los atributos solicitados. Es como document.querySelectorAll(), pero devuelve datos estructurados en lugar de nodos DOM.

Al ejecutarlo, verá 30 títulos de historias registrados en la consola.

Guardar resultados en un espacio de trabajo

Registrar mensajes está bien para depuración, pero ¿qué ocurre si quiere conservar los datos? Para eso existen los espacios de trabajo y g.store.

Primero, abra un espacio de trabajo: File > Open Workspace, y después elija o cree una carpeta. Esto da a sus scripts un directorio de inicio y desbloquea almacenamiento persistente.

Ahora actualice el script para guardar cada historia:

async function main() {
  await g.nav.navigateToUrl("https://news.ycombinator.com");
  await g.dom.waitForDomStable();


  const items = await g.dom.getElements(
    ".titleline > a",
    ["innerText", "href"]
  );


  for (const item of items) {
    const key = item.innerText.substring(0, 80);
    g.store.put("stories", key, {
      title: item.innerText,
      url: item.href,
      scrapedAt: new Date().toISOString()
    });
  }


  const count = g.store.count("stories");
  g.log("Stored " + count + " stories");
}

g.store.put(collection, key, data) guarda un documento JSON en una colección con nombre. La clave es única dentro de la colección; si ejecuta el script de nuevo, las historias existentes se actualizan en lugar de duplicarse. Los datos se guardan en un archivo store.db dentro de la carpeta del espacio de trabajo.

Después de ejecutar, abra el panel Store para explorar las historias guardadas. También puede consultarlas desde otro script:

const results = g.store.search("stories", "rust");

Procesar la cola con procesos de trabajo

¿Y si quiere visitar la URL de cada historia y extraer más datos? Primero, encole las URL:

async function main() {
  const stories = g.store.list("stories");
  for (const doc of stories) {
    g.queue.enqueue("to-visit", {
      url: doc.data.url,
      title: doc.data.title
    });
  }


  const count = g.queue.count("to-visit");
  g.log("Queued " + count + " URLs to visit");
}

Ahora, en lugar de escribir un bucle manual de extracción de cola, use procesos de trabajo. Los procesos de trabajo abren varias pestañas de navegador y procesan elementos de cola en paralelo; cada pestaña ejecuta su script de forma independiente.

Cree un script por elemento en su espacio de trabajo en scripts/visit-story.js:

async function main() {
  const ctx = g.worker.getContext();


  await g.nav.navigateToUrl(ctx.item.data.url);
  await g.dom.waitForDomStable();


  const title = await g.dom.extractContent("h1");
  g.log("Visited: " + (title || ctx.item.data.title));


  g.queue.commit(ctx.item.id);
}

g.worker.getContext() entrega a cada proceso de trabajo su elemento de cola actual y el ID de pestaña. El script navega, extrae y llama a commit() para marcar el elemento como hecho. Si el script falla antes de confirmar, el elemento vuelve automáticamente a la cola.

Después lance los procesos de trabajo desde cualquier script o desde la consola:

async function main() {
  g.workers.start({
    queue: "to-visit",
    script: "scripts/visit-story.js",
    concurrency: 3,
    layout: "horizontal"
  });
}

Eso es todo. Guida abre 3 pestañas en paralelo, y cada una procesa elementos de la cola de forma independiente. El panel Workers muestra el progreso en vivo: elementos procesados, errores, profundidad de cola, y permite pausar o detener el grupo sin tocar código.

Qué sigue

Ya vio el flujo central: navegar, extraer, guardar, encolar, procesos de trabajo. Desde aquí puede explorar:

El editor de scripts tiene IntelliSense completo: escriba g. en cualquier lugar y deje que el autocompletado le guíe.