.NET SDK | Firecrawl

インストール

公式の .NET SDK は、Firecrawl のモノレポ内の apps/dot-net-sdk で管理されています。 Firecrawl .NET SDK をインストールするには、NuGet パッケージを追加します。

.NET CLI
パッケージマネージャー
PackageReference

dotnet add package firecrawl-sdk

Install-Package firecrawl-sdk

<PackageReference Include="firecrawl-sdk" Version="1.0.0" />

.NET 8.0 以降が必要です。

使い方

firecrawl.devでAPIキーを取得します
APIキーを FIRECRAWL_API_KEY という環境変数に設定するか、FirecrawlClient のコンストラクターに渡します

以下は、現在のSDK APIでの簡単な例です。

using Firecrawl;
using Firecrawl.Models;

var client = new FirecrawlClient("fc-your-api-key");

// 単一ページをスクレイピング
var doc = await client.ScrapeAsync("https://firecrawl.dev",
    new ScrapeOptions { Formats = new List<object> { "markdown" } });

// Web サイトをクロール
var job = await client.CrawlAsync("https://firecrawl.dev",
    new CrawlOptions { Limit = 5 });

Console.WriteLine(doc.Markdown);
Console.WriteLine($"Crawled pages: {job.Data?.Count ?? 0}");

URLをスクレイピングする

単一のURLをスクレイピングするには、ScrapeAsyncメソッドを使用します。

using Firecrawl.Models;

var doc = await client.ScrapeAsync("https://firecrawl.dev",
    new ScrapeOptions
    {
        Formats = new List<object> { "markdown", "html" },
        OnlyMainContent = true,
        WaitFor = 5000
    });

Console.WriteLine(doc.Markdown);
Console.WriteLine(doc.Metadata?["title"]);

JSON抽出

JsonFormat を使用して、/scrape エンドポイントで構造化された JSON を抽出します。

using Firecrawl.Models;

var jsonFmt = new JsonFormat
{
    Prompt = "Extract the product name and price",
    Schema = new Dictionary<string, object>
    {
        ["type"] = "object",
        ["properties"] = new Dictionary<string, object>
        {
            ["name"] = new Dictionary<string, object> { ["type"] = "string" },
            ["price"] = new Dictionary<string, object> { ["type"] = "number" }
        }
    }
};

var doc = await client.ScrapeAsync("https://example.com/product",
    new ScrapeOptions
    {
        Formats = new List<object> { jsonFmt }
    });

Console.WriteLine(doc.Json);

Web サイトのクロール

Web サイトをクロールして完了を待つには、CrawlAsync を使用します。このメソッドは、ポーリングとページネーションを自動的に処理します。

using Firecrawl.Models;

var job = await client.CrawlAsync("https://firecrawl.dev",
    new CrawlOptions
    {
        Limit = 50,
        MaxDiscoveryDepth = 3,
        ScrapeOptions = new ScrapeOptions
        {
            Formats = new List<object> { "markdown" }
        }
    });

Console.WriteLine($"Status: {job.Status}");
Console.WriteLine($"Progress: {job.Completed}/{job.Total}");

if (job.Data != null)
{
    foreach (var page in job.Data)
    {
        Console.WriteLine(page.Metadata?["sourceURL"]);
    }
}

クロールを開始する

StartCrawlAsync を使用すると、待たずにジョブを開始できます。

using Firecrawl.Models;

var start = await client.StartCrawlAsync("https://firecrawl.dev",
    new CrawlOptions { Limit = 100 });

Console.WriteLine($"Job ID: {start.Id}");

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

GetCrawlStatusAsync でクロールの進行状況を確認します。

var status = await client.GetCrawlStatusAsync(start.Id!);
Console.WriteLine($"Status: {status.Status}");
Console.WriteLine($"Progress: {status.Completed}/{status.Total}");

クロールをキャンセルする

実行中のクロールは CancelCrawlAsync でキャンセルできます。

var result = await client.CancelCrawlAsync(start.Id!);
Console.WriteLine(result);

Web サイトのマッピング

MapAsync で Web サイト内のリンクを見つけます。

using Firecrawl.Models;

var data = await client.MapAsync("https://firecrawl.dev",
    new MapOptions
    {
        Limit = 100,
        Search = "blog"
    });

if (data.Links != null)
{
    foreach (var link in data.Links)
    {
        Console.WriteLine(link);
    }
}

Webを検索

任意の検索設定を指定して、SearchAsync で検索します。

using Firecrawl.Models;

var results = await client.SearchAsync("firecrawl web scraping",
    new SearchOptions
    {
        Limit = 10,
        Location = "US"
    });

if (results.Web != null)
{
    foreach (var hit in results.Web)
    {
        Console.WriteLine($"{hit.Title} - {hit.Url}");
    }
}

バッチスクレイプ

BatchScrapeAsync を使用すると、複数のURLを並列でスクレイピングできます。このメソッドは、ポーリングとページネーションを自動的に処理します。

using Firecrawl.Models;

var urls = new List<string>
{
    "https://firecrawl.dev",
    "https://firecrawl.dev/blog"
};

var job = await client.BatchScrapeAsync(urls,
    new BatchScrapeOptions
    {
        Options = new ScrapeOptions
        {
            Formats = new List<object> { "markdown" }
        }
    });

if (job.Data != null)
{
    foreach (var doc in job.Data)
    {
        Console.WriteLine(doc.Markdown);
    }
}

冪等性キーを使ったバッチスクレイプ

重複したリクエストが処理されないようにするには、IdempotencyKey を渡します:

var job = await client.BatchScrapeAsync(urls,
    new BatchScrapeOptions
    {
        IdempotencyKey = "my-unique-key",
        Options = new ScrapeOptions
        {
            Formats = new List<object> { "markdown" }
        }
    });

使用状況 & メトリクス

並行実行数と残りのクレジットを確認:

using Firecrawl.Models;

var concurrency = await client.GetConcurrencyAsync();
Console.WriteLine($"Concurrency: {concurrency.Current}/{concurrency.MaxConcurrency}");

var credits = await client.GetCreditUsageAsync();
Console.WriteLine($"Remaining credits: {credits.RemainingCredits}");

非同期サポート

.NET SDK のすべてのメソッドは既定で非同期で、Task<T> を返します。協調的なキャンセルに対応するため、CancellationToken をサポートしています。

using Firecrawl.Models;

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));

var doc = await client.ScrapeAsync("https://example.com",
    new ScrapeOptions
    {
        Formats = new List<object> { "markdown" }
    },
    cancellationToken: cts.Token);

Console.WriteLine(doc.Markdown);

設定

FirecrawlClient コンストラクターは、以下のオプションをサポートしています。

Option	Type	Default	Description
`apiKey`	`string?`	`FIRECRAWL_API_KEY` env var	Firecrawl APIキー
`apiUrl`	`string?`	`https://api.firecrawl.dev` (or `FIRECRAWL_API_URL`)	API のベース URL
`timeout`	`TimeSpan?`	5 分	HTTP リクエストのタイムアウト
`maxRetries`	`int`	`3`	一時的な障害に対する自動再試行
`backoffFactor`	`double`	`0.5`	秒単位の指数バックオフ係数
`httpClient`	`HttpClient?`	`timeout` から構築	事前設定済みの HttpClient インスタンス

using Firecrawl;

var client = new FirecrawlClient(
    apiKey: "fc-your-api-key",
    apiUrl: "https://api.firecrawl.dev",
    timeout: TimeSpan.FromMinutes(5),
    maxRetries: 3,
    backoffFactor: 0.5);

カスタム HTTP クライアント

接続プーリング、プロキシ、メッセージハンドラー、その他の HttpClient 機能を制御するために、事前設定済みの HttpClient を渡せます。これを指定すると、timeout の設定は無視され、代わりにクライアント自体の設定が使用されます。

using Firecrawl;

var handler = new HttpClientHandler
{
    Proxy = new WebProxy("http://proxy.example.com:8080"),
    UseProxy = true
};

var httpClient = new HttpClient(handler)
{
    Timeout = TimeSpan.FromSeconds(60)
};

var client = new FirecrawlClient(
    apiKey: "fc-your-api-key",
    httpClient: httpClient);

環境変数による設定

コンストラクタのパラメータが省略されている場合、SDK は環境変数から設定を読み取ります。

// FIRECRAWL_API_KEY と FIRECRAWL_API_URL の環境変数を使用
var client = new FirecrawlClient();

エラーハンドリング

SDK は Firecrawl.Exceptions 以下に定義された特定の例外をスローします。

using Firecrawl.Exceptions;
using Firecrawl.Models;

try
{
    var doc = await client.ScrapeAsync("https://example.com");
}
catch (AuthenticationException ex)
{
    Console.Error.WriteLine($"Auth failed: {ex.Message}");
}
catch (RateLimitException ex)
{
    Console.Error.WriteLine($"Rate limited: {ex.Message}");
}
catch (JobTimeoutException ex)
{
    Console.Error.WriteLine($"Job {ex.JobId} timed out after {ex.TimeoutSeconds}s");
}
catch (FirecrawlException ex)
{
    Console.Error.WriteLine($"Error {ex.StatusCode}: {ex.Message}");
}

例外の階層:

Exception	HTTPコード	発生条件
`AuthenticationException`	401	APIキーが無効、または指定されていない
`RateLimitException`	429	リクエスト数が多すぎる
`JobTimeoutException`	—	非同期ジョブ (クロール/バッチスクレイプ) が時間内に完了しなかった
`FirecrawlException`	varies	その他すべてのAPIエラーのベース例外

一時的な障害 (408、409、502、その他の5xxエラー) は、例外がスローされる前に指数バックオフを使用して自動的に再試行されます。

Firecrawl APIキーが必要なAI agentですか？自動オンボーディング手順については、firecrawl.dev/agent-onboarding/SKILL.mdを参照してください。

全体像

公式

Documentation Index

​インストール

​使い方

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

​JSON抽出

​Web サイトのクロール

​クロールを開始する

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

​クロールをキャンセルする

​Web サイトのマッピング

​Webを検索

​バッチスクレイプ

​冪等性キーを使ったバッチスクレイプ

​使用状況 & メトリクス

​非同期サポート

​設定

​カスタム HTTP クライアント

​環境変数による設定

​エラーハンドリング

インストール

使い方

URLをスクレイピングする

JSON抽出

Web サイトのクロール

クロールを開始する

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

クロールをキャンセルする

Web サイトのマッピング

Webを検索

バッチスクレイプ

冪等性キーを使ったバッチスクレイプ

使用状況 & メトリクス

非同期サポート

設定

カスタム HTTP クライアント

環境変数による設定

エラーハンドリング