> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firecrawl.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](https://github.com/firecrawl/firecrawl/tree/main/apps/ruby-sdk).
Pour installer le SDK Ruby de Firecrawl, ajoutez-le à votre projet :
Ajoutez-le à votre `Gemfile` :
```ruby theme={null}
gem "firecrawl-sdk", "~> 1.0"
```
Puis exécutez :
```bash theme={null}
bundle install
```
```bash theme={null}
gem install firecrawl-sdk
```
Ruby 3.0 ou version ultérieure requis.
## Utilisation
1. Obtenez une clé API sur [firecrawl.dev](https://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 :
```ruby theme={null}
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`.
```ruby theme={null}
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"]
```
Extrayez du JSON structuré via le point de terminaison `scrape` en ajoutant un format `json`, avec un prompt et un schéma :
```ruby theme={null}
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.
```ruby theme={null}
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`.
```ruby theme={null}
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`.
```ruby theme={null}
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`.
```ruby theme={null}
result = client.cancel_crawl(response.id)
puts result
```
### Cartographier un site web
Découvrez les liens d’un site avec `map`.
```ruby theme={null}
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`.
```ruby theme={null}
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`.
```ruby theme={null}
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`.
```ruby theme={null}
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 :
```ruby theme={null}
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 :
```ruby theme={null}
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é.
```ruby theme={null}
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 |
```ruby theme={null}
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`.
```ruby theme={null}
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](https://www.firecrawl.dev/agent-onboarding/SKILL.md) pour obtenir les instructions d’onboarding automatisé.