Passer au contenu principal

​
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

  1. Obtenez une clé API sur firecrawl.dev
  2. 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 :
OptionTypePar défautDescription
api_keyStringvariable d’environnement FIRECRAWL_API_KEYVotre clé d’API Firecrawl
api_urlStringhttps://api.firecrawl.dev (ou FIRECRAWL_API_URL)URL de base de l’API
timeoutInteger300Délai d’attente de la requête HTTP, en secondes
max_retriesInteger3Tentatives automatiques en cas d’échecs temporaires
backoff_factorFloat0.5Facteur 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é.