")
print("キャンセル済み:", ok)
```
### ウェブサイトをマッピングする
`map` を使って、ウェブサイトから URL の一覧を生成します。オプションで、サブドメインの除外やサイトマップの利用など、マッピングの挙動をカスタマイズできます。
```python Python theme={null}
res = firecrawl.map(url="https://firecrawl.dev", limit=10)
print(res)
```
### WebSockets を使ったウェブサイトのクロール
WebSockets でウェブサイトをクロールするには、`start_crawl` でジョブを開始し、`watcher` ヘルパーで購読します。ジョブ ID を指定して watcher を作成し、`start()` を呼び出す前にハンドラー (例: page、completed、failed) を登録します。
```python Python theme={null}
import asyncio
from firecrawl import AsyncFirecrawl
async def main():
firecrawl = AsyncFirecrawl(api_key="fc-YOUR-API-KEY")
# 最初にクロールを開始
started = await firecrawl.start_crawl("https://firecrawl.dev", limit=5)
# 終了ステータスまで更新（スナップショット）を監視
async for snapshot in firecrawl.watcher(started.id, kind="crawl", poll_interval=2, timeout=120):
if snapshot.status == "completed":
print("完了", snapshot.status)
for doc in snapshot.data:
print("DOC", doc.metadata.source_url if doc.metadata else None)
elif snapshot.status == "failed":
print("エラー", snapshot.status)
else:
print("ステータス", snapshot.status, snapshot.completed, "/", snapshot.total)
asyncio.run(main())
```
Firecrawl の /crawl および batch scrape の各エンドポイントは、追加のデータがある場合に `next` URL を返します。Python SDK はデフォルトで自動ページネーションを行い、すべてのドキュメントを集約します。この場合、`next` は `None` になります。自動ページネーションを無効化したり、ページネーションの動作を制御するための上限を設定することも可能です。
`get_crawl_status` または `get_batch_scrape_status` を呼び出す際のページネーション動作を制御するには、`PaginationConfig` を使用します。
```python Python theme={null}
from firecrawl.v2.types import PaginationConfig
```
| オプション | 型 | デフォルト | 説明 |
| --------------- | ------ | ------ | ----------------------------------------------------------------- |
| `auto_paginate` | `bool` | `True` | `True` の場合、すべてのページを自動的に取得して結果を集約します。1 ページずつ取得するには `False` に設定します。 |
| `max_pages` | `int` | `None` | 指定したページ数を取得したら終了します (`auto_paginate=True` の場合にのみ適用されます) 。 |
| `max_results` | `int` | `None` | 指定したドキュメント数を収集したら終了します (`auto_paginate=True` の場合にのみ適用されます) 。 |
| `max_wait_time` | `int` | `None` | 指定した秒数が経過したら終了します (`auto_paginate=True` の場合にのみ適用されます) 。 |
`auto_paginate=False` の場合、追加のデータがあると、レスポンスに `next` URL が含まれます。次のページを取得するには、これらのヘルパーメソッドを使用します:
* **`get_crawl_status_page(next_url)`** - 前のレスポンスに含まれる不透明な `next` URL を使用して、クロール結果の次のページを取得します。
* **`get_batch_scrape_status_page(next_url)`** - 前のレスポンスに含まれる不透明な `next` URL を使用して、バッチスクレイプ結果の次のページを取得します。
これらのメソッドは、元のステータス呼び出しと同じ型のレスポンスを返し、さらにページが残っている場合は新しい `next` URL を含みます。
#### クロール
最も手軽なのはウェイター方式の `crawl` を使うことです。もしくはジョブを開始して手動でページ処理を行ってください。
* 既定のフローについては[ウェブサイトをクロールする](#crawl-a-website)を参照してください。
ジョブを開始し、`auto_paginate=False` を指定して 1 ページずつ取得します。後続のページを取得するには `get_crawl_status_page` を使用します。
```python Python theme={null}
crawl_job = client.start_crawl("https://example.com", limit=100)
# 最初のページを取得
status = client.get_crawl_status(
crawl_job.id,
pagination_config=PaginationConfig(auto_paginate=False)
)
print("First page:", len(status.data), "docs")
# get_crawl_status_pageを使用して後続のページを取得
while status.next:
status = client.get_crawl_status_page(status.next)
print("Next page:", len(status.data), "docs")
```
自動ページネーションは有効のまま、`max_pages`、`max_results`、または `max_wait_time` で早期停止します。
```python Python theme={null}
status = client.get_crawl_status(
crawl_job.id,
pagination_config=PaginationConfig(max_pages=2, max_results=50, max_wait_time=15),
)
print("クロール制限:", status.status, "ドキュメント数:", len(status.data), "次のページ:", status.next)
```
#### バッチスクレイプ
waiter メソッド `batch_scrape` を使うか、ジョブを開始して手動でページングします。
* 既定のフローは [Batch Scrape](/ja/features/batch-scrape) を参照してください。
`auto_paginate=False` を指定してジョブを開始し、1ページずつ取得します。後続のページを取得するには `get_batch_scrape_status_page` を使用します。
```python Python theme={null}
batch_job = client.start_batch_scrape(urls)
# 最初のページを取得
status = client.get_batch_scrape_status(
batch_job.id,
pagination_config=PaginationConfig(auto_paginate=False)
)
print("First page:", len(status.data), "docs")
# get_batch_scrape_status_pageを使用して後続のページを取得
while status.next:
status = client.get_batch_scrape_status_page(status.next)
print("Next page:", len(status.data), "docs")
```
自動ページネーションは有効にしたまま、`max_pages`、`max_results`、または `max_wait_time` で早期に停止します：
```python Python theme={null}
status = client.get_batch_scrape_status(
batch_job.id,
pagination_config=PaginationConfig(max_pages=2, max_results=100, max_wait_time=20),
)
print("バッチ制限:", status.status, "ドキュメント数:", len(status.data), "次:", status.next)
```
## エラーハンドリング
リクエストが失敗すると、SDK は何が原因かを説明するメッセージを含む例外を発生させます。これらの例外を捕捉し、アプリケーション内で失敗に対処できるように、呼び出しは `try`/`except` で囲んでください。
## 非同期クラス
非同期処理には `AsyncFirecrawl` クラスを使用します。メソッドは `Firecrawl` と同等ですが、メインスレッドをブロックしません。
```python Python theme={null}
import asyncio
from firecrawl import AsyncFirecrawl
async def main():
firecrawl = AsyncFirecrawl(api_key="fc-YOUR-API-KEY")
# スクレイピング
doc = await firecrawl.scrape("https://firecrawl.dev", formats=["markdown"]) # type: ignore[arg-type]
print(doc.get("markdown"))
# 検索
results = await firecrawl.search("firecrawl", limit=2)
print(results.get("web", []))
# クロール（開始とステータス）
started = await firecrawl.start_crawl("https://docs.firecrawl.dev", limit=3)
status = await firecrawl.get_crawl_status(started.id)
print(status.status)
# バッチスクレイピング（待機）
job = await firecrawl.batch_scrape([
"https://firecrawl.dev",
"https://docs.firecrawl.dev",
], formats=["markdown"], poll_interval=1, timeout=60)
print(job.status, job.completed, job.total)
asyncio.run(main())
```
```python Python theme={null}
from firecrawl import AsyncFirecrawl
async_firecrawl = AsyncFirecrawl(api_key="fc-YOUR-API-KEY")
parsed = await async_firecrawl.parse(
b"Async Parse
",
filename="upload.html",
content_type="text/html",
)
```
## ブラウザ
クラウドブラウザセッションを起動し、リモートでコードを実行できます。
### セッションの作成
```python Python theme={null}
from firecrawl import Firecrawl
app = Firecrawl(api_key="fc-YOUR-API-KEY")
session = app.browser()
print(session.id) # セッションID
print(session.cdp_url) # wss://cdp-proxy.firecrawl.dev/cdp/...
print(session.live_view_url) # https://liveview.firecrawl.dev/...
```
### コードの実行
```python Python theme={null}
result = app.browser_execute(
session.id,
code='await page.goto("https://news.ycombinator.com")\ntitle = await page.title()\nprint(title)',
language="python",
)
print(result.result) # "Hacker News"
```
Python の代わりに JavaScript を実行する:
```python Python theme={null}
result = app.browser_execute(
session.id,
code='await page.goto("https://example.com"); const t = await page.title(); console.log(t);',
language="node",
)
```
### プロファイル
セッション間でブラウザの状態 (クッキーや localStorage など) を保存して再利用します：
```python Python theme={null}
session = app.browser(
ttl=600,
profile={
"name": "my-profile",
"save_changes": True,
},
)
```
### CDP 経由で接続する
Playwright をフルに制御するには、CDP URL を使用して直接接続します。
```python Python theme={null}
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
browser = p.chromium.connect_over_cdp(session.cdp_url)
context = browser.contexts[0]
page = context.pages[0] if context.pages else context.new_page()
page.goto("https://example.com")
print(page.title())
browser.close()
```
### セッションの一覧表示とクローズ
```python Python theme={null}
# アクティブなセッションを一覧表示
sessions = app.list_browsers(status="active")
for s in sessions.sessions:
print(s.id, s.status, s.created_at)
# セッションをクローズ
app.delete_browser(session.id)
```
### スクレイピングに紐づいたインタラクティブセッション
スクレイピングの `job ID` を使用すると、そのスクレイピングで再現されたページコンテキストに対して引き続き操作できます。
* `interact(job_id, ...)` は、スクレイピングに紐づいたブラウザセッション内でコードを実行します。
* 最初の `interact` 呼び出しでは、スクレイピングコンテキストからセッションが自動的に初期化されます。
* 同じ `job ID` に対する後続の `interact` 呼び出しでは、そのブラウザのライブ状態が再利用されます。
* `stop_interaction(job_id)` は、操作が完了したらインタラクティブセッションを停止します。
```python Python theme={null}
doc = app.scrape(
"https://example.com",
actions=[{"type": "click", "selector": "a[href='/pricing']"}],
)
scrape_job_id = doc.metadata_typed.scrape_id
if not scrape_job_id:
raise RuntimeError("Missing scrape job id")
run = app.interact(
scrape_job_id,
code="print(await page.url())",
language="python",
timeout=60,
)
print(run.stdout)
app.stop_interaction(scrape_job_id)
```
> Firecrawl API key が必要な AI agent ですか？自動オンボーディングの手順については、[firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) をご覧ください。