メインコンテンツへスキップ

​
インストール

公式の Ruby SDK は、Firecrawl のモノレポ内の apps/ruby-sdk で管理されています。 Firecrawl Ruby SDK をインストールするには、プロジェクトに追加します。
Gemfile に追加します。
gem "firecrawl-sdk", "~> 1.0"
次に、以下を実行します。
bundle install
Ruby 3.0 以降が必要です。

​
使い方

  1. firecrawl.dev でAPIキーを取得します
  2. APIキーを FIRECRAWL_API_KEY という名前の環境変数に設定するか、Firecrawl::Client.new(api_key: ...) に直接渡します
以下は、現在のSDKのAPIで使える簡単な例です。 
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}"

​
URL をスクレイピングする

1 つの URL をスクレイピングするには、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"]

​
JSON抽出

プロンプトとスキーマを含むjson形式を指定することで、scrapeエンドポイントから構造化されたJSONを抽出できます。 
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

​
Web サイトをクロールする

Web サイトをクロールし、完了まで待機するには、crawl を使用します。ジョブが完了するまで自動的にポーリングします。 
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

​
クロールを開始する

start_crawl を使用して、結果を待たずにジョブを開始します。 
response = client.start_crawl(
  "https://firecrawl.dev",
  Firecrawl::Models::CrawlOptions.new(limit: 100)
)

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

​
クロールのステータスを確認する

get_crawl_statusでクロールの進行状況を確認します。 
status = client.get_crawl_status(response.id)
puts "Status: #{status.status}"
puts "Progress: #{status.completed}/#{status.total}"

​
クロールのキャンセル

実行中のクロールは、cancel_crawl でキャンセルできます。 
result = client.cancel_crawl(response.id)
puts result

​
Web サイトをマッピングする

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

​
Web 検索

search を使うと、任意の設定で検索できます。 
results = client.search(
  "firecrawl web scraping",
  Firecrawl::Models::SearchOptions.new(limit: 10)
)

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

​
バッチスクレイピング

batch_scrape で複数のURLを並列にスクレイピングします。 
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 を使ってAIエージェントを実行します。 
result = client.agent(
  Firecrawl::Models::AgentOptions.new(
    prompt: "Find the pricing plans for Firecrawl and compare them"
  )
)

puts result.data
構造化された出力に JSON schema を使用する場合: 
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

​
使用状況 & メトリクス

同時実行数と残りのクレジットを確認できます: 
concurrency = client.get_concurrency
puts "Concurrency: #{concurrency.concurrency}/#{concurrency.max_concurrency}"

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

​
Browser

Ruby SDK には、ブラウザサンドボックスのヘルパーが含まれています。

​
スクレイピングに紐づいたインタラクティブセッション

スクレイピングジョブ ID を使って、同じリプレイコンテキスト内で後続のブラウザコードを実行できます。
  • interact(...) は、スクレイピングに紐づいたブラウザセッションでコードを実行し、初回使用時にそのセッションを初期化します。
  • stop_interactive_browser(...) は、作業が完了したらインタラクティブセッションを明示的に停止します。
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"]}"

​
設定

Firecrawl::Client.new では、次のオプションを指定できます。
オプション型デフォルト説明
api_keyStringFIRECRAWL_API_KEY env varFirecrawl APIキー
api_urlStringhttps://api.firecrawl.dev (または FIRECRAWL_API_URL)API のベース URL
timeoutInteger300HTTP リクエストのタイムアウト (秒)
max_retriesInteger3一時的な障害発生時の自動再試行
backoff_factorFloat0.5指数バックオフの係数 (秒)
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
)

​
エラーハンドリング

SDK は 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
Firecrawl APIキーが必要なAIエージェントですか？自動オンボーディングの手順は、firecrawl.dev/agent-onboarding/SKILL.mdをご覧ください。