← Voltar ao blog

Escrevendo seu primeiro script g.*

· 5 min de leitura ·
tutorial

Você instalou o Guida, navegou por algumas páginas e talvez tenha dado uma olhada nas configurações. E agora? Este post mostra como escrever seu primeiro script real: um script que navega até uma página, extrai dados dela e salva tudo em um lugar útil.

Nenhuma experiência prévia com scripting é obrigatória. Se você já escreveu JavaScript, vai se sentir em casa. Se não, a API é pequena o bastante para aprender durante o caminho.

Abra o editor de scripts

Pressione Ctrl+N ou vá para File > New Script. Você verá uma guia de editor em branco com IntelliSense já configurado. Digite g. e verá toda a superfície da API: mais de 160 métodos organizados em namespaces como g.store, g.queue, g.search e outros.

Todo script no Guida tem o mesmo formato:

async function main() {
  // seu código aqui
}

A palavra-chave async importa: a maioria dos métodos g.* é assíncrona porque conversa com um navegador ativo. O runtime chama main() para você; basta defini-la e pressionar F5 para executar.

Vamos começar simples. Vamos abrir o Hacker News e esperar a página carregar:

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

g.nav.navigateToUrl() instrui a guia ativa do navegador a carregar uma URL. g.dom.waitForDomStable() espera até que o DOM pare de mudar: sem novos elementos aparecendo, sem indicadores de carregamento, sem conteúdo lazy-loaded ainda chegando. Juntos, eles são a base de qualquer script de automação.

Execute com F5. Você verá a guia do navegador navegar até o Hacker News. O painel Console na parte inferior mostrará uma mensagem de sucesso.

Como os métodos g.* funcionam

Antes de avançar, há uma convenção que você precisa conhecer. Todo método g.* retorna o resultado diretamente e lança erro em caso de falha.

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

Se a operação tiver sucesso, o valor retornado contém o resultado. Se falhar, uma exceção é lançada. Use try/catch para tratar erros:

try {
  const elements = await g.dom.getElements(".item", ["innerText"]);
  g.log("Encontrados " + elements.length + " itens");
} catch (e) {
  g.log("Não foi possível encontrar itens: " + e.message);
  return;
}

g.log() escreve uma mensagem no painel Console.

Extraia dados da página

Agora vamos fazer algo útil. Vamos capturar os títulos e links do 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("Encontradas " + items.length + " histórias");


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

g.dom.getElements(selector, attributes) consulta o DOM e retorna um array de objetos, cada um contendo os atributos solicitados. É como document.querySelectorAll(), mas retorna dados estruturados em vez de nós DOM.

Ao executar isso, você verá 30 títulos de histórias registrados no console.

Armazene resultados em um espaço de trabalho

Logs são bons para depuração, mas e se você quiser manter os dados? É para isso que servem os espaços de trabalho e g.store.

Primeiro, abra um espaço de trabalho: File > Open Workspace. Depois escolha ou crie uma pasta. Isso dá aos seus scripts um diretório-base e libera armazenamento persistente.

Agora atualize o script para salvar cada história:

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("Armazenadas " + count + " histórias");
}

g.store.put(collection, key, data) salva um documento JSON em uma coleção nomeada. A chave é única dentro da coleção: se você executar o script novamente, histórias existentes serão atualizadas em vez de duplicadas. Os dados são armazenados em um arquivo store.db dentro da pasta do espaço de trabalho.

Depois de executar, abra o painel Store para navegar pelas histórias salvas. Você também pode consultá-las a partir de outro script:

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

Processe a fila com workers

E se você quiser visitar a URL de cada história e extrair mais dados? Primeiro, enfileire as URLs:

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("Enfileiradas " + count + " URLs para visitar");
}

Agora, em vez de escrever um loop manual de retirada da fila, use workers. Workers abrem várias guias do navegador e processam itens da fila em paralelo: cada guia executa seu script de forma independente.

Crie um script por item no seu espaço de trabalho em 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("Visitado: " + (title || ctx.item.data.title));


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

g.worker.getContext() dá a cada worker o item atual da fila e o ID da guia. O script navega, extrai e chama commit() para marcar o item como concluído. Se o script falhar antes do commit, o item volta para a fila automaticamente.

Depois, inicie os workers a partir de qualquer script ou do console:

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

Pronto. O Guida abre 3 guias lado a lado, e cada uma processa itens da fila de forma independente. O painel Workers mostra progresso em tempo real: itens processados, erros, profundidade da fila. Ele também permite pausar ou parar o pool sem tocar no código.

Próximos passos

Você viu o fluxo central: navegar, extrair, armazenar, enfileirar, usar workers. A partir daqui, explore:

O editor de scripts tem IntelliSense completo: digite g. em qualquer lugar e deixe o preenchimento automático guiar você. Bom scripting.