Saltar para o conteúdo
Comece grátis
Voltar ao blogue

Web scraping com Ruby: guia passo a passo com código funcional

Raluca PenciucÚltima atualização em 24 min read
Web scraping com Ruby: guia passo a passo com código funcional
Resumo: O Ruby faz a extração de dados da Web utilizando o Faraday para HTTP, o Nokogiri para a análise de CSS e XPath e um pequeno conjunto de threads para garantir a concorrência. Este guia mostra como criar um scraper que rastreia um catálogo de exercícios com 1 000 livros, convertendo-o para CSV e JSON, faz novas tentativas de forma educada, lida com uma página em JavaScript com o Ferrum e chama uma API de scraping a partir do mesmo código.

A extração de dados da Web com Ruby requer três componentes: o Faraday obtém a página, o Nokogiri analisa o HTML com seletores CSS ou XPath e um conjunto fixo de threads obtém várias páginas de uma só vez sem sobrecarregar o site. Irá criar um scraper do início ao fim. Este recolhe todos os livros de books.toscrape.com, um catálogo de treino público, segue a paginação, processa páginas em simultâneo, repete as solicitações com limitação de taxa da forma correta e grava os resultados em CSV e JSON. Em seguida, irá lidar com uma página renderizada em JavaScript (quotes.toscrape.com/js/) de três formas diferentes, iniciar sessão num formulário de prática com o Mechanize e chamar uma API de scraping a partir do mesmo código do Faraday.

O código destina-se ao Ruby 3.4 ou mais recente e às versões das gems indicadas na tabela abaixo.

O Ruby é adequado para o web scraping?

Sim. O Ruby dispõe de gems maduras para cada etapa de um scraper: o Faraday para obter páginas, o Nokogiri para as analisar, o Ferrum para controlar o Chrome headless e o Mechanize para formulários e sessões. O código mantém-se conciso e legível, e integra-se naturalmente quando a sua aplicação já funciona em Ruby ou Rails. O Python possui um ecossistema de scraping mais vasto e mais ferramentas para navegadores.

Escolha o Ruby quando:

  • A sua aplicação, equipa ou fila de tarefas já estiver a funcionar em Ruby ou Rails, e quiser que o scraper faça parte da mesma base de código.
  • Preferir um scraper legível com algumas gems bem conhecidas, em vez de um grande framework.

Escolha Python quando:

  • Precisas de uma biblioteca ou ferramenta de navegador que não tenha equivalente em Ruby. O nosso guia sobre web scraping com Python aborda essa abordagem.
  • A sua equipa trabalha principalmente em notebooks de dados e pretende que o scraper esteja junto à análise.

De que gems Ruby precisas para o web scraping?

Precisas de um cliente HTTP e de um analisador de HTML. O Faraday e o Nokogiri cobrem ambas as funções, e algumas pequenas gemas adicionam tentativas de repetição, saída em CSV e um navegador quando uma página o requer.

Tarefa

Gema

Versão verificada em novembro de 2026

Quando utilizar

Cliente HTTP

faraday

2.15.1

Opção predefinida, com middleware para novas tentativas e erros

Novas tentativas

faraday-retry

2.4.0

Novas tentativas com backoff. Defina os códigos de estado manualmente

Cliente HTTP (alternativa)

httparty

0.24.3

Pedidos rápidos e pontuais. Analisa respostas JSON por si

Análise de HTML

nokogiri

1.19.7

CSS e XPath, pré-compilados para plataformas comuns

CSV

csv

3.3.7

Gem incluída desde o Ruby 3.4, por isso adicione-a ao seu Gemfile

JSON

json

Gem predefinida

JSON.pretty_generate para ficheiros legíveis

Concorrência

Thread + Queue

Biblioteca padrão

Um conjunto limitado de trabalhadores

Chrome sem interface gráfica

ferrum

0.20.1

Controla o Chrome através do protocolo DevTools

Automação do navegador (alternativa)

selenium-webdriver + capybara

4.52.0 e 3.40.0

Multinavegador, baseado no WebDriver

Formulários e sessões

mechanize

2.14.2

Cookies, links e envio de formulários

Estrutura de rastreamento

kimurai

2.2.0 (lançado em janeiro de 2026)

Spiders e motores de navegação numa única estrutura

Testes

minitest + webmock

6.0.6 e 3.34.0

Testes de analisador offline com pedidos simulados

A versão mais recente do Watir data de agosto de 2023, pelo que se recomenda utilizar o Ferrum ou o Selenium em código novo. Para comparar analisadores HTML em Ruby para além do Nokogiri, consulte o nosso guia sobre bibliotecas Ruby para a análise de HTML e XML.

Como configurar um projeto de web scraping em Ruby

Um projeto de scraping em Ruby requer o Ruby 3.4 ou mais recente, o Bundler e um ficheiro Gemfile que fixe as gems acima referidas. A configuração requer apenas alguns comandos.

Primeiro, instale o Ruby se não tiver uma versão atual e, em seguida, verifique-a:

ruby -v

O Ruby 4.0 é a série estável atual, e a versão 3.4 também funciona. O Ruby 3.3 recebe apenas correções de segurança, e o Ruby 3.2 chegou ao fim do ciclo de vida em abril de 2026.

Cria o projeto e um ficheiro Gemfile:

mkdir book_scraper && cd book_scraper
bundle init

Substitua o Gemfile gerado por este:

# frozen_string_literal: true

source "https://rubygems.org"

ruby ">= 3.4"

gem "faraday", "~> 2.15"
gem "faraday-retry", "~> 2.4"
gem "nokogiri", "~> 1.19"
gem "csv", "~> 3.3"

group :browser do
  gem "ferrum", "~> 0.20"
end

group :test do
  gem "minitest", "~> 6.0"
  gem "webmock", "~> 3.34"
end

O ~> pins aceitam versões secundárias, mas não a próxima versão principal. O Ferrum encontra-se num :browser grupo porque apenas a secção de JavaScript precisa dele. Instale tudo:

bundle install

O scraper encontra-se em lib/book_scraper.rb, e os pequenos scripts em scripts/ o chamam. Execute cada um com bundle exec ruby scripts/<name>.rb.

Por que é que require "csv" falhar?

require "csv" falhar?

Desde o Ruby 3.4, o csv é uma gem incluída no pacote, em vez de ser uma gem predefinida, pelo que, no Bundler, só é carregado se estiver listado no seu Gemfile. Sem ele, bundle exec é exibido este aviso:

warning: csv used to be loaded from the standard library, but is not part of the default gems since Ruby 3.4.0.
You can add csv to your Gemfile or gemspec to fix this error.

Em seguida, interrompe-se com cannot load such file -- csv (LoadError). A gem "csv", "~> 3.3" linha no Gemfile acima resolve o problema. Fora ruby script.rb fora do Bundler ainda encontra o csv, razão pela qual o erro muitas vezes só aparece quando um projeto passa a ter um Gemfile.

Como enviar o seu primeiro pedido HTTP com o Faraday

O Faraday envia a solicitação e devolve uma resposta com um estado, cabeçalhos e corpo. Comece com uma linha no irb para confirmar se o site responde:

require "faraday"
Faraday.get("https://books.toscrape.com/").status # => 200

Um scraper a sério precisa de uma ligação reutilizável que identifique o teu cliente, pare de esperar por servidores lentos, sinalize erros em caso de respostas falhadas e tente novamente quando o servidor te pedir para abrandar. Aprende a definir cabeçalhos de pedido realistas antes de fazer scraping em sites que os verificam.

Cria lib/book_scraper.rb e inicie o módulo:

# frozen_string_literal: true

require "faraday"
require "faraday/retry"
require "nokogiri"
require "uri"
require "csv"
require "json"

module BookScraper
  START_URL = "https://books.toscrape.com/catalogue/page-1.html"
  USER_AGENT = "BookScraper/1.0 (+mailto:you@example.com)"
  RATINGS = { "One" => 1, "Two" => 2, "Three" => 3, "Four" => 4, "Five" => 5 }.freeze

  module_function

  # One reusable Faraday connection: timeouts, retries, and errors for non-2xx.
  def client
    Faraday.new(headers: { "User-Agent" => USER_AGENT }) do |f|
      f.options.open_timeout = 5
      f.options.timeout = 15
      f.response :raise_error # outer: raises once retries are used up
      f.request :retry,
                max: 3,
                interval: 0.5,
                backoff_factor: 2,
                interval_randomness: 0.5,
                retry_statuses: [429, 500, 502, 503, 504],
                max_interval: 30 # wait no longer than this per retry
    end
  end

  def fetch(conn, url)
    response = conn.get(url)
    # No charset in Content-Type, so Faraday returns binary; tag it UTF-8 for string methods
    response.body.force_encoding(Encoding::UTF_8)
  end

Eis o que cada parte faz:

  • O User-Agent dá um nome ao seu scraper e fornece um endereço de contacto, para que os proprietários dos sites possam contactá-lo. Substitua you@example.com por um endereço real.
  • open_timeout e timeout limite o tempo de espera para a ligação (5 segundos) e para a leitura (15 segundos), para que uma página lenta não bloqueie a execução.
  • raise_error transforma respostas 4xx e 5xx em exceções, tais como Faraday::ResourceNotFound, para que uma página em falta seja claramente identificada como falha.
  • retry repete as tentativas para respostas com limitação de taxa e de erro do servidor, aumentando gradualmente os tempos de espera. A secção sobre repetições explica cada opção e por que razão a ordem destas duas linhas é importante.

O fetch método devolve o corpo marcado como UTF-8. Quando o cabeçalho Content-Type não contém nenhum conjunto de caracteres, como neste site, o Faraday devolve uma cadeia binária (ASCII-8BIT). O Nokogiri continua a ler o meta-conjunto de caracteres da página, mas as suas próprias verificações de cadeias de caracteres não o fazem. Chamar include?("£") no corpo binário gera Encoding::CompatibilityError: incompatible character encodings: BINARY (ASCII-8BIT) and UTF-8. Marcar o corpo com force_encoding resolve esse problema. A documentação do Faraday aborda adaptadores, middleware e opções de ligação com mais detalhe.

Como analisar HTML com o Nokogiri

O Nokogiri transforma uma cadeia de caracteres HTML num documento que pode ser pesquisado com seletores CSS ou XPath. css retorna todas as correspondências, at_css retorna a primeira, [] lê um atributo e text lê o conteúdo.

No site books.toscrape.com, cada livro está num article.product_pod cartão. Teste o seletor em irb antes de criar qualquer coisa com base nele:

doc = Nokogiri::HTML(Faraday.get("https://books.toscrape.com/catalogue/page-1.html").body)
doc.css("article.product_pod").size # => 20

Vinte cartões correspondem, um por livro. A mesma consulta em XPath é doc.xpath("//article[@class=\"product_pod\"]"). O CSS é mais curto para marcação baseada em classes, enquanto o XPath consegue corresponder com base no texto e percorrer a árvore. Se estiver a escolher entre seletores CSS ou XPath, a nossa comparação aborda as vantagens e desvantagens, e o tutorial de pesquisa do Nokogiri aborda consultas mistas. Testar em irb primeiro significa que um seletor com erros custa apenas alguns segundos, em vez de uma execução de 50 páginas que grava um ficheiro vazio.

Como extrair dados estruturados para hashes Ruby

Transforme cada cartão num hash com valores tipados: um título do tipo String, um preço do tipo Float, uma classificação do tipo Integer, um indicador de disponibilidade do tipo booleano e um URL absoluto. Os valores tipados permitem ordenar, filtrar e exportar de forma organizada. Adicione parse_books ao módulo:

  def parse_books(html, page_url)
    doc = Nokogiri::HTML(html)
    doc.css("article.product_pod").map do |card|
      link = card.at_css("h3 a")
      rating_class = card.at_css("p.star-rating")["class"].split.last
      {
        title: link["title"],
        price: card.at_css("p.price_color").text.delete("^0-9.").to_f,
        rating: RATINGS.fetch(rating_class, nil),
        in_stock: card.at_css("p.availability").text.include?("In stock"),
        url: URI.join(page_url, link["href"]).to_s
      }
    end
  end

Por que razão foi construído desta forma:

  • O título provém do atributo title , porque o texto visível é truncado no caso de títulos longos.
  • delete("^0-9.") mantém apenas os dígitos e o ponto decimal, pelo que £51.77 torna-se 51.77 antes de to_f.
  • A classificação está associada a um nome de classe como star-rating Three, que o RATINGS hash mapeia para um Integer.
  • URI.join resolve ligações relativas com base no URL da página, pelo que cada linha contém um URL completo.

Experimente na primeira página com scripts/first_page.rb:

require_relative "../lib/book_scraper"

conn = BookScraper.client
html = BookScraper.fetch(conn, BookScraper::START_URL)
books = BookScraper.parse_books(html, BookScraper::START_URL)

puts "books on page 1: #{books.size}"
puts JSON.pretty_generate(books.first(2))
puts "next: #{BookScraper.next_page_url(html, BookScraper::START_URL)}"

A última linha utiliza next_page_url, que irá adicionar na próxima secção. Assim que estiver implementado, o script apresenta:

books on page 1: 20
[
  {
    "title": "A Light in the Attic",
    "price": 51.77,
    "rating": 3,
    "in_stock": true,
    "url": "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html"
  },
  {
    "title": "Tipping the Velvet",
    "price": 53.74,
    "rating": 1,
    "in_stock": true,
    "url": "https://books.toscrape.com/catalogue/tipping-the-velvet_999/index.html"
  }
]
next: https://books.toscrape.com/catalogue/page-2.html

Como lidar com a paginação em Ruby

Para paginar, leia o link «seguinte» em cada página, resolva-o para um URL completo e continue até que o link desapareça. Adicione um atraso entre páginas e um limite de páginas, para que um site em loop não mantenha o seu scraper a funcionar para sempre.

O catálogo marca a página seguinte com li.next a. Adicione estes dois métodos:

  def next_page_url(html, page_url)
    href = Nokogiri::HTML(html).at_css("li.next a")&.[]("href")
    href && URI.join(page_url, href).to_s
  end

  # Follow "next" links until there are none, with a delay and a page cap.
  def crawl(conn, start_url = START_URL, max_pages: 100, delay: 0.5)
    url = start_url
    books = []
    pages = 0
    while url && pages < max_pages
      html = fetch(conn, url)
      books.concat(parse_books(html, url))
      pages += 1
      url = next_page_url(html, url)
      sleep(delay) if url
    end
    [books, pages]
  end

Na última página não há nenhum link, pelo que o operador de navegação segura (&.) devolve nil e o ciclo termina. O max_pages: 100 cap protege-te de loops, e o meio segundo sleep protege o site contra picos de tráfego. Neste catálogo, crawl são visitadas 50 páginas e são devolvidos 1 000 livros, que a secção de exportação guarda em ficheiros.

Seguir links de página em página leva-o do scraping para o crawling. O nosso guia sobre scraping vs. crawling explica onde está a linha divisória.

Como fazer scraping de várias páginas em simultâneo em Ruby

Quando já conhece os URLs das páginas, um pequeno conjunto de threads recupera várias páginas de uma só vez. As threads do Ruby ajudam neste caso, porque o interpretador liberta o seu bloqueio global enquanto uma thread aguarda na rede. Um tamanho fixo do conjunto mantém a carga no site previsível.

Os URLs das páginas do catálogo seguem um padrão, por isso crie a lista antecipadamente e adicione-a crawl_concurrently ao módulo:

  # Fetch a known list of pages with a fixed number of worker threads.
  def crawl_concurrently(urls, workers: 4)
    queue = Queue.new
    urls.each { |u| queue << u }
    queue.close
    results = Queue.new
    errors = Queue.new

    threads = Array.new(workers) do
      Thread.new do
        conn = client # one connection per thread
        while (url = queue.pop)
          begin
            results << parse_books(fetch(conn, url), url)
          rescue Faraday::Error => e
            errors << [url, e.class.name]
          end
        end
      end
    end
    threads.each(&:join)

    books = []
    books.concat(results.pop) until results.empty?
    failed = []
    failed << errors.pop until errors.empty?
    [books, failed]
  end

Como as peças se encaixam:

  • Um Queue encerra os trabalhadores de forma limpa. Depois de close, pop retornar as URLs restantes e, em seguida, nil, o que encerra cada ciclo, sem necessidade de valores sentinela. Consulte a documentação do Thread::Queue.
  • Cada thread estabelece a sua própria ligação, pelo que não é partilhado qualquer estado de ligação entre threads.
  • Os erros são detetados por página. O rescue regista o URL com falha e segue em frente, pelo que uma página com erros não interrompe o lote.
  • Queue é seguro para threads, pelo que os trabalhadores enviam os resultados sem necessidade de um mutex.

Execute-o em todas as 50 páginas, mais um URL que não existe, utilizando scripts/scrape_concurrently.rb:

require_relative "../lib/book_scraper"

urls = (1..50).map { |n| "https://books.toscrape.com/catalogue/page-#{n}.html" }
urls << "https://books.toscrape.com/catalogue/page-999.html" # this page doesn't exist

books, failed = BookScraper.crawl_concurrently(urls, workers: 4)
puts "books: #{books.size}, failed: #{failed.inspect}"

A saída mostra todos os livros e a única página que falhou:

books: 1000, failed: [["https://books.toscrape.com/catalogue/page-999.html", "Faraday::ResourceNotFound"]]

Os resultados chegam na ordem em que as threads terminam, por isso, ordena-os se a ordem for importante. Mantém workers pequeno em sites que não são seus: o pool existe para limitar a carga.

Como repetir tentativas de pedidos falhados de forma educada

As predefinições do `faraday-retry` repetem apenas os tempos de espera e as falhas de ligação, sem espera entre tentativas e sem códigos de estado HTTP. Um erro 429 «Too Many Requests» ou um 503 «Service Unavailable» falha na primeira tentativa, a menos que configure o middleware manualmente.

Estas opções no client método fazem com que as tentativas funcionem:

  • retry_statuses: [429, 500, 502, 503, 504] indica ao middleware quais as respostas a tentar novamente. Sem isso, nenhuma é repetida.
  • max: 3 permite três tentativas após a primeira tentativa.
  • interval: 0.5, backoff_factor: 2, e interval_randomness: 0.5 começa com uma espera de meio segundo, duplica-a a cada vez e adiciona variação.
  • max_interval: 30 limita qualquer espera individual a 30 segundos.

Quando uma resposta repetida contém um Retry-After cabeçalho, o middleware aguarda durante o tempo que o servidor solicitar. Se essa espera for superior a max_interval, desiste imediatamente: um servidor que responde Retry-After: 120 recebe uma resposta imediata Faraday::TooManyRequestsError deste cliente. Lance max_interval se preferir aguardar. Apenas métodos idempotentes, como o GET, são repetidos, e um 404 nunca o é.

A ordem das duas linhas de middleware também é importante. Registe f.response :raise_error antes de f.request :retry. O Faraday executa o middleware registado em primeiro lugar no exterior, pelo que retry vê a resposta 429 ou 503 em bruto, tenta novamente e raise_error só é acionado depois de esgotadas as tentativas. Troque as duas linhas e raise_error transforma o 429 num Faraday::TooManyRequestsError antes retry alguma vez ver um código de estado, pelo que nada é repetido, mesmo com retry_statuses estiver definido.

Com esta configuração, um servidor que devolva 429 duas vezes e, em seguida, 200, fornece ao seu código um 200 normal. Um servidor que continue a devolver 503 recebe quatro pedidos; depois, o seu código recebe Faraday::ServerError. O README do faraday-retry lista todas as opções, incluindo retry_block para registar as tentativas.

Como guardar dados extraídos em CSV e JSON

Grave o CSV com uma lista explícita de cabeçalhos e o JSON com JSON.pretty_generate. Ambos mantêm os valores tipados da etapa de análise.

Adicione os métodos de exportação:

  HEADERS = %w[title price rating in_stock url].freeze

  def write_csv(books, path)
    CSV.open(path, "w", write_headers: true, headers: HEADERS) do |csv|
      books.each { |b| csv << b.values_at(*HEADERS.map(&:to_sym)) }
    end
  end

  def write_json(books, path)
    File.write(path, JSON.pretty_generate(books))
  end

values_at recupera os campos na HEADERS ordem, para que as linhas fiquem alinhadas com o cabeçalho, mesmo que adicione chaves posteriormente. Associe o rastreio e as exportações em scripts/scrape_books.rb:

require_relative "../lib/book_scraper"

books, pages = BookScraper.crawl(BookScraper.client)
BookScraper.write_csv(books, "output/books.csv")
BookScraper.write_json(books, "output/books.json")
puts "pages: #{pages}, books: #{books.size}"

Crie a pasta de saída e execute o script:

mkdir -p output
bundle exec ruby scripts/scrape_books.rb

O script apresenta pages: 50, books: 1000. output/books.csv tem uma linha de cabeçalho mais 1 000 linhas de dados, e começa assim:

title,price,rating,in_stock,url
A Light in the Attic,51.77,3,true,https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html

output/books.json contém os mesmos 1 000 registos como uma matriz de objetos. As notas de lançamento do Ruby 3.4 incluem o csv entre as gems que passaram a ser fornecidas de forma integrada, pelo que esta é a etapa em que surge uma linha em falta no Gemfile. Feche o módulo com um end após o último método.

Como testar um scraper em Ruby sem aceder ao site

Guarde uma página real como um fixture, simule o pedido com o WebMock e verifique a saída analisada. Estes testes são executados offline e detetam desvios nos seletores antes que uma tarefa agendada envie um CSV vazio.

Guarde a primeira página do catálogo:

mkdir -p test/fixtures
curl -o test/fixtures/page-1.html https://books.toscrape.com/catalogue/page-1.html

Em seguida, escreva test/book_scraper_test.rb:

require "minitest/autorun"
require "webmock/minitest"
require_relative "../lib/book_scraper"

class BookScraperTest < Minitest::Test
  PAGE = "https://books.toscrape.com/catalogue/page-1.html"

  def setup
    stub_request(:get, PAGE).to_return(status: 200, body: File.read(File.join(__dir__, "fixtures/page-1.html")))
  end

  def test_parses_twenty_books_with_typed_fields
    books = BookScraper.parse_books(BookScraper.fetch(BookScraper.client, PAGE), PAGE)
    assert_equal 20, books.size
    assert_equal "A Light in the Attic", books.first[:title]
    assert_in_delta 51.77, books.first[:price]
    assert_equal 3, books.first[:rating]
  end

  def test_finds_next_page
    html = BookScraper.fetch(BookScraper.client, PAGE)
    assert_equal "https://books.toscrape.com/catalogue/page-2.html", BookScraper.next_page_url(html, PAGE)
  end

  def test_retries_503_then_succeeds
    stub_request(:get, "https://example.test/flaky").to_return({ status: 503 }, { status: 200, body: "<p>ok</p>" })
    assert_equal 200, BookScraper.client.get("https://example.test/flaky").status
  end
end

Execute os testes:

bundle exec ruby test/book_scraper_test.rb

A linha de resumo diz 3 runs, 6 assertions, 0 failures, 0 errors, 0 skips. Os dois primeiros testes verificam o analisador e a paginação. O terceiro simula um erro 503 seguido de um 200 e verifica se o cliente devolve o 200; por isso, falha se alguém alterar a ordem do middleware ou eliminar retry_statuses. O WebMock também bloqueia chamadas de rede reais, pelo que a ausência de um stub aparece como um erro evidente.

Como extrair páginas renderizadas em JavaScript em Ruby

O Faraday e o Nokogiri só veem o HTML que o servidor envia. Se a página construir o seu conteúdo com JavaScript no navegador, esse conteúdo não estará presente na resposta. Verifique primeiro e, em seguida, opte pela solução mais simples: dados incorporados, depois um navegador sem interface gráfica e, por fim, uma API gerida.

Como verificar se uma página necessita de JavaScript

Recupere a página e conte os elementos que espera encontrar. quotes.toscrape.com/js/ mostra 10 citações num navegador. Conte-as no HTML bruto:

require "faraday"
require "nokogiri"
require "json"
url = "https://quotes.toscrape.com/js/"
html = Faraday.get(url, nil, "User-Agent" => "BookScraper/1.0").body.force_encoding("UTF-8")
puts "div.quote in raw HTML: #{Nokogiri::HTML(html).css('div.quote').size}"
# The page ships its data in an inline script: var data = [ ... ];
json = html[/var data = (\[.*?\]);/m, 1]
quotes = JSON.parse(json).map do |q|
  { text: q["text"], author: q.dig("author", "name"), tags: q["tags"] }
end
puts "quotes from embedded JSON: #{quotes.size}"
puts JSON.pretty_generate(quotes.first)

A primeira linha da saída é div.quote in raw HTML: 0: as citações não constam do HTML do servidor. Pode verificar o mesmo no navegador. A opção «Ver Código-fonte» mostra o HTML do servidor, enquanto o painel «Elementos» das DevTools mostra a página após a execução do JavaScript.

Extraia primeiro o JSON incorporado

Muitas páginas JavaScript enviam os seus dados num script embutido e renderizam-nos no navegador. Ler esses dados diretamente é mais leve e mais robusto do que executar um navegador. A segunda metade do script acima faz isso: a expressão regular captura o array atribuído a var datae JSON.parse transforma-o em hashes Ruby.

O script, em seguida, apresenta:

quotes from embedded JSON: 10
{
  "text": "“The world as we have created it is a process of our thinking. It cannot be changed without changing our thinking.”",
  "author": "Albert Einstein",
  "tags": [
    "change",
    "deep-thoughts",
    "thinking",
    "world"
  ]
}

São as 10 citações, com as tags, e sem precisar de um navegador. A mesma ideia aplica-se quando uma página carrega os seus dados a partir de uma API: localize a resposta JSON no separador «Rede» das Ferramentas do Desenvolvedor e solicite essa URL com o Faraday.

Renderize a página com o Ferrum

Quando os dados só existem após a execução do JavaScript, renderize a página no Chrome sem interface gráfica. O Ferrum controla o Chrome diretamente através do protocolo DevTools, pelo que não é necessário instalar nem manter sincronizado nenhum ficheiro binário de controlador. Requer o Chrome ou o Chromium no seu PATHou um caminho na BROWSER_PATH variável de ambiente.

require "ferrum"
require "nokogiri"
browser = Ferrum::Browser.new(headless: true, timeout: 30)
begin
  page = browser.create_page
  page.go_to("https://quotes.toscrape.com/js/")
  page.wait_for_selector(css: "div.quote") # Ferrum 0.19+
  doc = Nokogiri::HTML(page.body)
  quotes = doc.css("div.quote").map do |q|
    { text: q.at_css("span.text").text, author: q.at_css("small.author").text }
  end
  puts "rendered div.quote: #{quotes.size}"
  puts quotes.first
ensure
  browser.quit
end

Guarde-o como scripts/ferrum_quotes.rb e execute-o com bundle exec ruby scripts/ferrum_quotes.rb. Ele exibe rendered div.quote: 10 seguido da primeira citação. wait_for_selector bloqueia até que as aspas existam, o que é melhor do que um sleep. page.body retorna o HTML renderizado, pelo que o código Nokogiri é o mesmo que para uma página estática, e ensure fecha o Chrome mesmo quando algo falha.

Cada instância do navegador utiliza memória real e CPU, por isso mantenha a concorrência dos navegadores baixa e renderize apenas as páginas que necessitem disso. A página do projeto Ferrum documenta cliques, digitação e capturas de ecrã.

Selenium, Capybara e outras opções de navegador

O selenium-webdriver funciona através do WebDriver, pelo que é a escolha certa quando precisas do Firefox ou de código compatível com vários navegadores, e o Capybara acrescenta uma DSL mais intuitiva para clicar e preencher campos. O Cuprite é um driver do Capybara construído sobre o Ferrum, útil se já escreves código Capybara. O Kimurai integra navegadores e o Nokogiri numa estrutura completa, abordada mais adiante. Se precisares de renderização, tempos de espera e capturas de ecrã e preferires renderizar páginas sem executar navegadores nos teus próprios servidores, um navegador alojado tira-te esse trabalho das mãos.

Como enviar formulários e manter sessões com o Mechanize

O Mechanize funciona como um navegador simples sem JavaScript. Armazena cookies, segue redirecionamentos e preenche e submete formulários, o que é adequado para inícios de sessão e fluxos de várias etapas em sites renderizados pelo servidor.

O site de treino tem um formulário de início de sessão em quotes.toscrape.com/login que aceita qualquer nome de utilizador e palavra-passe. Adicione gem "mechanize", "~> 2.14" ao seu Gemfile, execute bundle installe inicie sessão:

require "mechanize"

agent = Mechanize.new
agent.user_agent = "BookScraper/1.0 (+mailto:you@example.com)"

page = agent.get("https://quotes.toscrape.com/login")
form = page.form_with(action: "/login")
form.username = "demo"
form.password = "demo"
home = agent.submit(form)

puts "logged in: #{!home.link_with(text: 'Logout').nil?}"
puts "quotes on page: #{home.search('div.quote').size}"

O script apresenta logged in: true e quotes on page: 10. form_with localiza o formulário pela sua ação; os campos ocultos, como o token CSRF, são enviados juntamente com ele, e o cookie de sessão permanece no armazenamento de cookies do agente para pedidos posteriores. search executa o Nokogiri, pelo que os mesmos seletores funcionam. Para inícios de sessão que dependem de JavaScript, utilize o Ferrum em vez disso. Automatize apenas os inícios de sessão em sites onde tenha uma conta e autorização.

Deve utilizar uma estrutura de web scraping em Ruby?

A maioria das tarefas não precisa de uma. O Faraday, o Nokogiri e um conjunto de threads dão conta de alguns sites com lógica personalizada, e mantém-se o controlo total. Uma estrutura compensa quando se executam muitos spiders e se pretende agendamento, motores de navegador e pipelines num único local.

O Kimurai é a principal opção em Ruby. A versão 2.x está novamente a ser mantida e requer Ruby 3.2 ou mais recente. Antes de o adotar, tenha em conta dois aspetos:

  • Traz uma árvore de dependências extensa, incluindo Capybara, Selenium e Active Support.
  • Muitos tutoriais ainda se destinam ao Kimurai 1.x, por isso verifique se os exemplos correspondem à API da versão 2.x.

Faraday vs HTTParty

Ambos os clientes funcionam. O HTTParty é a forma mais rápida de efetuar um pedido pontual e analisa as respostas JSON, convertendo-as em hashes Ruby por si:

require "httparty"
require "nokogiri"

response = HTTParty.get(
  "https://books.toscrape.com/",
  headers: { "User-Agent" => "BookScraper/1.0 (+mailto:you@example.com)" },
  timeout: 15
)
doc = Nokogiri::HTML(response.body)
puts "status #{response.code}, books #{doc.css('article.product_pod').size}"

Isso imprime status 200, books 20. O Faraday requer mais configuração, mas o seu middleware mantém as tentativas de repetição, os tempos de espera e o tratamento de erros numa única ligação reutilizável. Utilize o HTTParty para scripts rápidos e o Faraday para scrapers que são executados de forma programada.

Quando é que o scraping DIY em Ruby atinge um limite?

O scraper deste guia funciona porque books.toscrape.com e quotes.toscrape.com são sites de treino criados para pedidos automatizados. Muitos sites de produção não o são. O mesmo código pode começar a falhar com respostas 403, páginas CAPTCHA, limites de taxa por IP, verificações de impressão digital do navegador ou conteúdo que varia consoante o país. Aumentar o número de threads não ajuda, porque estes limites dizem respeito a quem está a fazer a solicitação, e não à velocidade.

Sintoma

Causa provável

Solução «faça você mesmo»

Quando parar

Erro 403 (Acesso proibido) em todos os pedidos

O site bloqueia o seu cliente ou endereço IP

Envie cabeçalhos realistas, diminua o ritmo

O bloqueio persiste mesmo com taxas baixas

429 Demasiadas solicitações

Limite de taxa por IP ou por sessão

Menos trabalhadores, respeite Retry-After

Precisa de mais largura de banda do que um IP permite

Uma página CAPTCHA em vez de conteúdo

Detecção de bots

Reduza a taxa de pedidos, verifique os termos do site

Os CAPTCHAs aparecem no tráfego normal

Funciona num navegador, mas falha no Chrome sem interface gráfica

Verificações de impressão digital

Analise as opções de execução «headless»

Está a manter as atualizações do navegador

Conteúdo ou preços diferentes consoante a região

Respostas direcionadas geograficamente

Encaminhamento através de um IP nesse país

Precisa de muitos países

Cada correção «faça você mesmo» acrescenta infraestrutura para gerir e monitorizar: conjuntos de proxies, frotas de navegadores, filas de novas tentativas. O nosso guia sobre como evitar ser bloqueado aborda cabeçalhos, controlo de ritmo e proxies. A certa altura, faz mais sentido delegar a recuperação de dados e manter o seu código Ruby para a análise.

Como chamar a API do Scraper a partir de Ruby

A API do Scraper faz a recuperação da página por si, gere os proxies e as tentativas de recuperação e consegue executar JavaScript, enquanto o seu código Ruby mantém os mesmos passos do Faraday e do Nokogiri. Basta enviar um pedido GET com a sua chave de API e o URL de destino, e adicionar opções como render_js ou country apenas quando uma página as necessitar.

Adicione este método ao BookScraper módulo, antes do end:

  # Scraper API: same Faraday, the target goes in params and gets URL-encoded for you.
  def scraper_api(url, render_js: false, country: nil)
    api = Faraday.new(url: "https://api.webscrapingapi.com") do |f|
      f.options.timeout = 120
    end
    params = { api_key: ENV.fetch("WSA_API_KEY"), url: url }
    params[:render_js] = 1 if render_js
    params[:country] = country if country
    api.get("/v2", params)
  end

Em seguida, chama-o a partir de scripts/scraper_api.rb e verifique o estado antes de analisar:

require_relative "../lib/book_scraper"

response = BookScraper.scraper_api("https://quotes.toscrape.com/js/", render_js: true, country: "us")

if response.status == 200
  doc = Nokogiri::HTML(response.body)
  puts "quotes via Scraper API: #{doc.css('div.quote').size}"
else
  puts "Scraper API returned #{response.status}: #{response.body[0, 200]}"
end

Defina a sua chave no shell e execute-o:

export WSA_API_KEY="your_api_key"
bundle exec ruby scripts/scraper_api.rb

Por que é que o código tem este aspeto:

  • O hash «params» codifica a URL de destino por si, por isso o seu :, /, ?, e & os caracteres não podem interromper o pedido. Colar a URL manualmente na string de consulta é um erro comum.
  • ENV.fetch falha rapidamente. Se a variável não estiver definida, o Ruby lança uma exceção KeyError: key not found: "WSA_API_KEY" antes de qualquer pedido ser enviado.
  • O tempo de espera é mais longo, porque a renderização demora mais tempo do que uma simples recuperação.
  • Esta ligação não tem middleware de repetição de tentativas. A API já repete as tentativas do seu lado, pelo que as repetições do cliente apenas repetiriam o trabalho.
  • O ramo de erro exibe o corpo. Com uma chave inválida, o script exibe Scraper API returned 401: {"error":"Invalid API key"}.

Com o HTTParty, a mesma chamada passa as opções como query:, o que as codifica da mesma forma. Mantenha a chave da API no lado do servidor: não a grave no código, não a inclua no código do cliente nem a imprima nos registos.

Erros comuns de scraping em Ruby e como corrigi-los

A maioria dos erros no scraping da Web com Ruby resulta da falta de uma gem, de uma configuração de repetição que não funciona, de uma incompatibilidade de codificação ou de conteúdo que não se encontra no HTML. Aqui estão cada um dos sintomas e a respetiva correção.

Erro ou sintoma

Causa

Solução

cannot load such file -- csv (LoadError)

O csv é uma gem integrada desde o Ruby 3.4

Adicione gem "csv" ao Gemfile

As respostas 429 ou 503 falham na primeira tentativa

As configurações predefinidas do faraday-retry não incluem códigos de estado

Defina retry_statuses

Faraday::TooManyRequestsError apesar de uma configuração de nova tentativa

raise_error registada após retry

Registar raise_error primeira

A tentativa de repetição desiste imediatamente num erro 429

Retry-After for maior do que max_interval

Aumentar max_interval ou abrandar

Encoding::CompatibilityError nas verificações de cadeias de caracteres

Corpo binário (sem conjunto de caracteres no Content-Type)

force_encoding("UTF-8")

Um seletor não devolve nada

Conteúdo renderizado por JavaScript ou um seletor incorreto

Verifique o HTML bruto e, em seguida, consulte a secção sobre JavaScript

Faraday::ResourceNotFound para uma página num lote

Um erro 404 gerado por raise_error

Rescue Faraday::Error por página

KeyError: key not found: "WSA_API_KEY"

A variável de ambiente não está definida

Exporte-a no seu shell ou gestor de segredos

URLs relativas na sua saída

Bruto href Valores

Resolva-os com URI.join

403 Proibido

Bloqueio

Abrande e, em seguida, consulte a secção «Faça você mesmo»

Quando um erro não constar na tabela, imprima o código de estado e as primeiras centenas de bytes do corpo da resposta. A maioria dos erros de scraping torna-se óbvia assim que se vê o que o servidor enviou.

Como fazer scraping de forma responsável com Ruby

Leia o ficheiro robots.txt do site, que segue o Protocolo de Exclusão de Robôs (RFC 9309), e ignore os caminhos que este proíbe para o seu agente de utilizador. Mantenha o conjunto de trabalhadores pequeno, adicione atrasos e respeite Retry-After quando o servidor lhe pedir para abrandar. Identifique o seu cliente com um User-Agent que inclua um endereço de contacto. Siga os termos de serviço do site e evite recolher dados pessoais, a menos que tenha uma base legal clara para o fazer. Para saber como abordamos esta questão, consulte as nossas práticas responsáveis de dados na Web.

FAQ

O Ruby é adequado para web scraping?

Sim. O Ruby dispõe de gems maduras para cada etapa: Faraday ou HTTParty para obter páginas, Nokogiri para analisar HTML com seletores CSS ou XPath, Ferrum para controlar o Chrome headless e Mechanize para formulários. O Python possui um ecossistema de scraping mais vasto e mais ferramentas para navegadores, mas o Ruby é a escolha natural quando a sua aplicação ou equipa já funciona com Ruby ou Rails.

Qual é a melhor biblioteca Ruby para web scraping?

A maioria dos scrapers em Ruby combina o Faraday para pedidos HTTP com o Nokogiri para a análise. Adicione o faraday-retry para novas tentativas, a gem csv para folhas de cálculo e a biblioteca JSON integrada para ficheiros JSON. Utilize o Ferrum quando uma página necessitar de um navegador real, o Mechanize para formulários e inícios de sessão e o Kimurai se pretender uma estrutura completa de rastreamento.

Devo usar o Faraday ou o HTTParty para web scraping?

Ambos funcionam. O HTTParty é a forma mais rápida de efetuar uma solicitação pontual e analisa as respostas JSON por si. O Faraday requer um pouco mais de configuração, mas cria uma ligação reutilizável com middleware, pelo que as tentativas de repetição, os tempos limite e o tratamento de erros ficam centralizados num único local. Para um scraper que funciona de forma programada, o middleware do Faraday costuma compensar.

O Nokogiri consegue extrair páginas renderizadas em JavaScript?

Não. O Nokogiri analisa o HTML que o servidor envia e nunca executa JavaScript, pelo que o conteúdo criado no navegador não consta da resposta. Verifica primeiro o HTML bruto e, em seguida, procura os dados num script incorporado ou numa solicitação JSON que a página efetue. Se esses dados só existirem após a renderização, usa o Ferrum ou o Selenium para carregar a página.

É possível fazer web scraping com Ruby on Rails?

Sim. Coloque o scraper numa classe Ruby simples ou num objeto de serviço e, em seguida, execute-o a partir de uma tarefa em segundo plano com o Active Job, para que os pedidos web nunca fiquem à espera de um rastreio. Armazene os resultados com o Active Record, agende execuções recorrentes com o seu backend de tarefas e mantenha o código HTTP e de análise testável fora do Rails com fixtures HTML guardados.

O Kimurai continua a ser um bom framework de web scraping em Ruby?

O Kimurai 2.x voltou a ser mantido e requer Ruby 3.2 ou mais recente, pelo que é uma opção quando se pretendem spiders, motores de navegador e pipelines numa única estrutura. Envolve uma vasta árvore de dependências, incluindo Capybara e Selenium. Para tarefas mais pequenas, o Faraday, o Nokogiri e um conjunto de threads proporcionam-lhe os mesmos resultados com menos componentes.

Como posso evitar ser bloqueado ao fazer scraping com Ruby?

Identifique o seu cliente com um User-Agent claro, mantenha a concorrência baixa, adicione atrasos entre páginas e tente novamente em caso de respostas 429 e 503, respeitando o Retry-After. Respeite o ficheiro robots.txt e os termos do site. Sites com CAPTCHAs, identificação por impressão digital ou limites de taxa por IP podem ainda assim bloquear um scraper que se comporte bem, e é aí que a rotação de IPs ou uma API de scraping gerida ajudam.

O que fazer a seguir

Já dispõe de um scraper em Ruby testado que obtém, analisa, pagina, executa páginas em simultâneo, repete tentativas de forma educada e exporta dados limpos. Alguns passos adicionais tornam-no pronto para produção:

  • Execute-o a partir de uma tarefa em segundo plano. No Rails, envolva o rastreio num Active Job e agende-o, para que nenhuma solicitação web fique à espera de um rastreio.
  • Adicione um limite de taxa por anfitrião, para que cada trabalhador partilhe um orçamento de pedidos, em vez de depender apenas de intervalos de espera e do tamanho do pool.
  • Renderize apenas onde for necessário. Mantenha o Faraday para páginas estáticas e JSON incorporado, e envie apenas as páginas que necessitem de JavaScript para o Ferrum.
  • Transfira a recuperação de dados quando os blocos começarem. Assim que passar mais tempo com proxies e CAPTCHAs do que com a análise, transfira a etapa de recuperação para uma API gerida e mantenha o resto do seu código Ruby.

Mantém o teu código Ruby, ignora os blocos

Aponte o mesmo cliente Faraday para a API do Scraper e receba a página renderizada, a partir do país que escolher, sem ter de executar navegadores ou proxies por conta própria. Comece com 5 000 pedidos gratuitos. Não há créditos adicionais para renderização de JavaScript ou segmentação geográfica, e os pedidos falhados não são faturados.

Consulte os preços da API do Scraper

Sobre o autor

Raluca Penciuc, Desenvolvedor Full-Stack @ WebScrapingAPI

Raluca Penciuc

Desenvolvedor Full-Stack

Raluca Penciuc é programadora Full Stack na WebScrapingAPI, onde desenvolve scrapers, aperfeiçoa estratégias de evasão e procura formas fiáveis de reduzir a deteção nos sites-alvo.

Web Scraping com AWS Lambda: Guia para Python e Java 2026
Guias

Web Scraping com AWS Lambda: Guia para Python e Java 2026

TL;DR: Resumo: A extração de dados da Web com o AWS Lambda funciona melhor quando cada invocação é curta, delimitada e pode ser repetida de forma independente. Comece com HTTP direto, AWS SAM e S3 e, só depois, adicione SQS, contentores, renderização no navegador, proxies ou uma camada de recuperação gerida, apenas quando a carga de trabalho demonstrar que precisa deles.

Suciu Dan32 min read
Ler artigo
Como utilizar o GoSpider: rastrear, limpar URLs e extrair dados
Guias

Como utilizar o GoSpider: rastrear, limpar URLs e extrair dados

TL;DR: Resumo: O GoSpider é um rastreador de linha de comandos destinado a descobrir URLs, não um extrator completo de dados estruturados. Este guia sobre como utilizar o GoSpider mostra como realizar um rastreio limitado, gerir resultados de forma organizada, fazer a transferência de dados do Colly para CSV e seguir um percurso de diagnóstico para respostas 403 ou páginas que exijam renderização em JavaScript.

Suciu Dan23 min read
Ler artigo
Como fazer o Scrape Redfin: Guia Python para Dados de Propriedade
Guias

Como fazer o Scrape Redfin: Guia Python para Dados de Propriedade

TL;DR: A Redfin expõe pontos de extremidade de API ocultos que retornam JSON estruturado para listagens de propriedades, tornando possível ignorar totalmente a análise HTML frágil. Este guia orienta-o na construção de um scraper Python que extrai dados de aluguer e venda, pesquisa por localização, monitoriza novas listagens através de sitemaps XML e exporta resultados limpos para CSV ou JSON.

Suciu Dan14 min read
Ler artigo

Comece a construir

Pronto para expandir a sua recolha de dados?

Junte-se a mais de 2.000 empresas que utilizam a WebScrapingAPI para extrair dados da Web à escala empresarial, sem quaisquer custos de infraestrutura.