Ruby - Firecrawl Docs

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

gem install firecrawl-sdk

Note

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_envdoc = 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.markdownputs "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.markdownputs 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.markdownend

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_concurrencyputs "Concurrency: #{concurrency.concurrency}/#{concurrency.max_concurrency}"credits = client.get_credit_usageputs "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é.