Ruby

Le SDK Ruby de Firecrawl est une surcouche de l'API Firecrawl qui vous permet de convertir facilement des sites web en Markdown.

Installation

Le SDK Ruby officiel est maintenu dans le monorepo Firecrawl, dans apps/ruby-sdk.

Pour installer le SDK Ruby de Firecrawl, ajoutez-le à votre projet :

Ajoutez-le à votre Gemfile :

gem "firecrawl-sdk", "~> 1.0"

Puis exécutez :

bundle install

Ruby 3.0 ou version ultérieure requis.

Utilisation

Obtenez une clé API sur firecrawl.dev
Définissez la clé API comme variable d’environnement nommée FIRECRAWL_API_KEY, ou passez-la directement avec Firecrawl::Client.new(api_key: ...)

Voici un exemple rapide avec l’API actuelle du SDK :

require "firecrawl"

client = Firecrawl::Client.from_env

doc = client.scrape(
  "https://firecrawl.dev",
  Firecrawl::Models::ScrapeOptions.new(formats: ["markdown"])
)

job = client.crawl(
  "https://firecrawl.dev",
  Firecrawl::Models::CrawlOptions.new(limit: 5)
)

puts doc.markdown
puts "Crawled pages: #{job.data&.size || 0}"

Scraping d’une URL

Pour extraire le contenu d’une seule URL, utilisez la méthode scrape.

doc = client.scrape(
  "https://firecrawl.dev",
  Firecrawl::Models::ScrapeOptions.new(
    formats: ["markdown", "html"],
    only_main_content: true,
    wait_for: 5000
  )
)

puts doc.markdown
puts doc.metadata["title"]

Extraction JSON

Extrayez du JSON structuré via le point de terminaison scrape en ajoutant un format json, avec un prompt et un schéma :

doc = client.scrape(
  "https://example.com/product",
  Firecrawl::Models::ScrapeOptions.new(
    formats: [
      {
        "type" => "json",
        "prompt" => "Extract the product name and price",
        "schema" => {
          "type" => "object",
          "properties" => {
            "name" => { "type" => "string" },
            "price" => { "type" => "number" }
          }
        }
      }
    ]
  )
)

puts doc.json

Lancer un crawl sur un site web

Pour lancer un crawl sur un site web et attendre son achèvement, utilisez crawl. Il interroge automatiquement l’état de la tâche jusqu’à ce qu’elle soit terminée.

job = client.crawl(
  "https://firecrawl.dev",
  Firecrawl::Models::CrawlOptions.new(
    limit: 50,
    max_discovery_depth: 3,
    scrape_options: Firecrawl::Models::ScrapeOptions.new(
      formats: ["markdown"]
    )
  )
)

puts "Status: #{job.status}"
puts "Progress: #{job.completed}/#{job.total}"

job.data&.each do |page|
  puts page.metadata["sourceURL"]
end

Démarrer un crawl

Démarrez une tâche sans attendre avec start_crawl.

response = client.start_crawl(
  "https://firecrawl.dev",
  Firecrawl::Models::CrawlOptions.new(limit: 100)
)

puts "Job ID: #{response.id}"

Vérifier l’état du crawl

Consultez la progression du crawl avec get_crawl_status.

status = client.get_crawl_status(response.id)
puts "Status: #{status.status}"
puts "Progress: #{status.completed}/#{status.total}"

Annuler un crawl

Annulez un crawl en cours à l’aide de cancel_crawl.

result = client.cancel_crawl(response.id)
puts result

Cartographier un site web

Découvrez les liens d’un site avec map.

data = client.map(
  "https://firecrawl.dev",
  Firecrawl::Models::MapOptions.new(
    limit: 100,
    search: "blog"
  )
)

data.links&.each do |link|
  puts "#{link["url"]} - #{link["title"]}"
end

Recherche sur le Web

Effectuez une recherche avec des paramètres facultatifs à l’aide de search.

results = client.search(
  "firecrawl web scraping",
  Firecrawl::Models::SearchOptions.new(limit: 10)
)

results.web&.each do |result|
  puts "#{result["title"]} - #{result["url"]}"
end

Scraping par lots

Scrapez plusieurs URL en parallèle à l’aide de batch_scrape.

job = client.batch_scrape(
  ["https://firecrawl.dev", "https://firecrawl.dev/blog"],
  Firecrawl::Models::BatchScrapeOptions.new(
    options: Firecrawl::Models::ScrapeOptions.new(
      formats: ["markdown"]
    )
  )
)

job.data&.each do |doc|
  puts doc.markdown
end

Agent

Exécutez un agent propulsé par l’IA avec agent.

result = client.agent(
  Firecrawl::Models::AgentOptions.new(
    prompt: "Find the pricing plans for Firecrawl and compare them"
  )
)

puts result.data

À l’aide d’un schéma JSON pour une sortie structurée :

result = client.agent(
  Firecrawl::Models::AgentOptions.new(
    prompt: "Extract pricing plan details",
    urls: ["https://firecrawl.dev"],
    schema: {
      "type" => "object",
      "properties" => {
        "plans" => {
          "type" => "array",
          "items" => {
            "type" => "object",
            "properties" => {
              "name" => { "type" => "string" },
              "price" => { "type" => "string" }
            }
          }
        }
      }
    }
  )
)

puts result.data

Utilisation & métriques

Consultez la concurrence et les crédits restants :

concurrency = client.get_concurrency
puts "Concurrency: #{concurrency.concurrency}/#{concurrency.max_concurrency}"

credits = client.get_credit_usage
puts "Remaining credits: #{credits.remaining_credits}"

Browser

Le SDK Ruby inclut des fonctions utilitaires pour Browser Sandbox.

Session interactive liée à une tâche de scraping

Utilisez l’ID d’une tâche de scraping pour exécuter du code supplémentaire dans le navigateur, dans le même contexte rejoué :

interact(...) exécute du code dans la session de navigateur liée au scraping (et l’initialise lors de la première utilisation).
stop_interactive_browser(...) arrête explicitement la session interactive lorsque vous avez terminé.

scrape_job_id = "550e8400-e29b-41d4-a716-446655440000"

run = client.interact(
  scrape_job_id,
  "console.log(page.url());",
  language: "node",
  timeout: 60
)

puts run["stdout"]

deleted = client.stop_interactive_browser(scrape_job_id)
puts "Deleted: #{deleted["success"]}"

Configuration

Firecrawl::Client.new accepte les options suivantes :

Option	Type	Par défaut	Description
`api_key`	`String`	variable d’environnement `FIRECRAWL_API_KEY`	Votre clé d’API Firecrawl
`api_url`	`String`	`https://api.firecrawl.dev` (ou `FIRECRAWL_API_URL`)	URL de base de l’API
`timeout`	`Integer`	`300`	Délai d’attente de la requête HTTP, en secondes
`max_retries`	`Integer`	`3`	Tentatives automatiques en cas d’échecs temporaires
`backoff_factor`	`Float`	`0.5`	Facteur de backoff exponentiel, en secondes

client = Firecrawl::Client.new(
  api_key: "fc-your-api-key",
  api_url: "https://api.firecrawl.dev",
  timeout: 300,
  max_retries: 3,
  backoff_factor: 0.5
)

Gestion des erreurs

Le SDK lève des exceptions dans le module Firecrawl.

begin
  doc = client.scrape("https://example.com")
rescue Firecrawl::AuthenticationError => e
  puts "Auth failed: #{e.message}"
rescue Firecrawl::RateLimitError => e
  puts "Rate limited: #{e.message}"
rescue Firecrawl::JobTimeoutError => e
  puts "Job #{e.job_id} timed out after #{e.timeout_seconds}s"
rescue Firecrawl::FirecrawlError => e
  puts "Error (#{e.status_code}): #{e.message}"
end

Vous êtes un agent IA et vous avez besoin d’une clé API Firecrawl ? Consultez firecrawl.dev/agent-onboarding/SKILL.md pour obtenir les instructions d’onboarding automatisé.

On this page