Skip to main content

スクレイピング後にページをInteract

プロンプトまたはコード実行で、取得したページを操作します。
4 min read

ページをスクレイピングしてクリーンなデータを取得し、その後 /interact を呼び出して、そのページ上でアクションを開始します: ボタンのクリック、フォームへの入力、動的コンテンツの抽出、さらに深いページへの移動が可能です。やりたいことを記述するだけでもよく、完全に制御したい場合はコードを書くこともできます。

報奨金:5,000クレジット /interact に関する質の高いフィードバックに進呈

対象となるには、Firecrawl Feedback Assistant との内容の濃いインタビュー (よく考えられた具体的なユースケースなど) を完了してください。所要時間は数分で、いつでも中断できます。人間にもエージェントにも対応しており (リンクをエージェント用ハーネスに貼り付けるだけです!) 、/interact を使ったことがない場合でも、ご意見をお聞かせください。

インタビューを開始

報奨金の対象となるには、メールアドレスを入力してください。インタビューは毎週末に品質を確認します。

適切な操作モデルを選択#

必要なこと使用するもの正規ドキュメントSDK メソッド (Node)
最初にスクレイピングせず、独立したブラウザセッションを開始するBrowser Sandbox / 独立した Interact セッションBrowser Sandbox, Create Browser Session, Execute Browser Code, List Browser Sessions, Delete Browser Sessionbrowser(), browserExecute(), listBrowsers(), deleteBrowser()
scrapeId を使ってスクレイピング結果から続行するスクレイピング後に InteractExecute Interact, Stop Interactinteract(), stopInteraction()

ワークフローが POST /v2/scrape で始まり、レスポンスに data.metadata.scrapeId が含まれる場合は、スクレイピングに紐づいた Interact を使用します。独自のライフサイクルを持つ独立したセッションが必要な場合は、Browser Sandbox を使用します。Python SDK では、snake_case の同等メソッド (browser(), browser_execute(), list_browsers(), delete_browser(), interact(), stop_interaction()) を使用します。

AIプロンプト

ページ上で実行したいアクションを記述します

コード実行

Playwright や agent-browser を使って、安全にコード実行で操作できます

ライブビュー

埋め込み可能なストリームを通じて、ブラウザーをリアルタイムで確認したり操作したりできます

動作の仕組み#

  1. POST /v2/scrape で URL をスクレイピングします。レスポンスには data.metadata.scrapeIdscrapeId が含まれます。ブラウザの状態を保持したい場合は、このリクエストで profile を渡します。
  2. prompt または Playwright の code を指定して POST /v2/scrape/{scrapeId}/interact を呼び出し、Interactします。ここでは profile を渡さないでください。Interact セッションはスクレイピングジョブから profile を引き継ぎます。
  3. 完了したら、DELETE /v2/scrape/{scrapeId}/interact でセッションを停止します。書き込み可能な profile では、セッションの停止時に変更が保存されます。

クイックスタート#

ページをスクレイピングし、操作し、セッションを停止します:

Response

プロンプトで操作する#

ページを操作する最も簡単な方法です。やりたいことを自然言語で記述するだけで、自動的にクリック、入力、スクロール、データの抽出を行います。

レスポンスには、エージェントの回答が含まれる output フィールドがあります。

Response

プロンプトは小さく、焦点を絞る#

プロンプトは、それぞれが単一の明確なタスクであるときに最も効果を発揮します。エージェントに複雑な複数ステップのワークフローを一度に実行させるのではなく、個別の interact 呼び出しに分けてください。各呼び出しは同じブラウザセッションを再利用するため、それまでの状態が引き継がれます。

コードの実行#

より細かく制御したい場合は、ブラウザサンドボックスでコードを直接実行できます。page 変数 (Playwright の Page オブジェクト) は Node.js と Python で利用できます。Bash モードには agent-browser がプリインストールされています。セッション内でスクリーンショットを撮ることもできます: Node.js では (await page.screenshot()).toString("base64")、Python では await page.screenshot(path="/tmp/screenshot.png")、Bash では agent-browser screenshot を使用してください。

Node.js (Playwright)#

デフォルトの言語です。Playwright のコードを直接記述できます。page はすでにブラウザに接続されています。

Python#

Playwright の Python API を使う場合は、language"python" に設定します。

Bash (agent-browser)#

agent-browser は、60 以上のコマンドがプリインストールされたサンドボックス内の CLI です。要素参照 (@e1, @e2, ...) 付きのアクセシビリティツリーを提供し、LLM による自動化に最適です。

一般的な agent-browser コマンド:

コマンド説明
snapshot要素参照付きの完全なアクセシビリティツリー
snapshot -iインタラクティブな要素のみ
click @e1参照で要素をクリック
fill @e1 "text"フィールドをクリアしてテキストを入力
type @e1 "text"クリアせずにテキストを入力
press Enterキーボードのキーを押す
scroll down 500500 ピクセル下にスクロール
get text @e1テキストコンテンツを取得
get url現在の URL を取得
wait @e1要素が表示されるまで待機
wait --load networkidleネットワークがアイドル状態になるまで待機
find text "X" clickテキストで要素を見つけてクリック
screenshot現在のページのスクリーンショットを撮る
eval "js code"ページ内で JavaScript を実行

ライブビュー#

すべての Interact レスポンスでは、埋め込んでブラウザをリアルタイムで確認できる liveViewUrl が返されます。デバッグやデモ、ブラウザ駆動の UI の構築に便利です。

Response

インタラクティブ ライブビュー#

レスポンスには interactiveLiveViewUrl も含まれます。閲覧専用の標準ライブビューとは異なり、インタラクティブ ライブビューでは、埋め込みストリームを通じてユーザーがブラウザセッションを直接クリック、入力、操作できます。これは、ログインフローや、エンドユーザーがブラウザを操作する必要があるガイド付きワークフローなど、ユーザー向けのブラウザUIを構築する場合に役立ちます。

CDP URL#

すべてのInteractレスポンスでは、cdpUrl も返されます。これは、ブラウザセッション用の生の Chrome DevTools Protocol (CDP) WebSocket URL です。これを使うと、Playwright、Puppeteer、または任意のCDPクライアントからライブセッションに直接接続し、自分のコードでブラウザを操作できます。

セッションのライフサイクル#

作成#

最初の POST /v2/scrape/{scrapeId}/interact 呼び出しで、スクレイピングセッションが継続され、インタラクションが開始されます。

再利用#

同じscrapeIdに対する後続のinteract呼び出しでは、既存のセッションが再利用されます。browserは開いたままで、呼び出し間でも状態が維持されるため、複数のインタラクションを連続して実行できます。

クリーンアップ#

使用が終わったら、明示的にセッションを停止してください:

セッションは、TTL (default: 10分) または非アクティブ タイムアウト (default: 5分) に基づいて自動的に期限切れになります。

Warning

不要な課金を避けるため、使用後は必ずセッションを停止してください。Credits は秒単位で按分されます。最低料金はブラウザ1分です。prompt を使用するセッションはブラウザ1分あたり7 Credits、prompt を使用しないセッションは2 Credits が課金されます。詳細は課金を参照してください。

Scrape + Interact での永続プロファイル#

デフォルトでは、各スクレイピング + interact セッションはクリーンなブラウザで開始されます。profile を使うと、スクレイピング間でブラウザの状態 (cookies、localStorage、sessions) を保存して再利用できます。これは、ログイン状態を維持したり、設定を保持したりするのに便利です。

最初の POST /v2/scrape リクエストに profile オブジェクトを渡します。POST /v2/scrape/{scrapeId}/interact には profile を渡さないでください。interact セッションは、scrape ジョブのブラウザセッションとプロファイル設定を再利用します。書き込み可能なプロファイルの変更を保存できるように、DELETE /v2/scrape/{scrapeId}/interact で interact セッションを停止してください。

cURL

プロファイルのライフサイクルは次のとおりです。

  1. profile.namesaveChanges: true を指定してスクレイピングを作成します。
  2. 返された scrapeId に対して、プロンプトまたはコードで操作を実行します。
  3. セッションを停止して、cookies、localStorage、その他のブラウザの状態を保存します。
  4. 後続のスクレイピングを同じ profile.name で開始します。変更を書き戻さずに既存の状態だけを読み取りたい場合は、saveChanges: false を使用します。
パラメータデフォルト説明
nameNone永続プロファイルの名前です。同じ名前のスクレイピングはブラウザの状態を共有します。
saveChangestruetrue の場合、interact セッションの停止時にブラウザの状態がプロファイルに保存されます。既存のデータを読み込み、変更を書き戻さないようにするには、false に設定します。これは、複数の同時リーダーが必要な場合に便利です。
Note

一度にプロファイルへ保存できるセッションは 1 つだけです。別のセッションがすでに保存中の場合は、409 エラーが返されます。saveChanges: false で同じプロファイルを開くことはできますし、後でもう一度試すこともできます。

ブラウザの状態は、interact セッションが停止したときに保存されます。プロファイルを再利用できるよう、完了したら必ずセッションを停止してください。

永続化の検証#

実際のログインフローに頼らずに永続化をテストするには、1つ目のセッションで localStorage に値を書き込み、そのセッションを停止したあと、同じプロファイルを使う2つ目のセッションでその値を読み取ります。

cURL

2回目のInteractレスポンスでは、localStorage"saved"cookietrue と表示されるはずです。

Info

API 経由で作成したプロファイルは、まだ Dashboard > Interact > Profiles に表示されない場合があります。現在、Dashboard では API で作成された永続プロファイルの完全な一覧は確認できません。

使い分けの目安#

ユースケース推奨理由
Web searchSearch専用の検索エンドポイント
URL から整形されたコンテンツを取得ScrapeAPI 呼び出し 1 回で、セッション不要
ページ上でクリック、入力、移動を行うInteract (prompt)英語で指示するだけ
操作の先にあるデータを抽出するInteract (prompt)セレクタ不要
複雑なスクレイピングロジックInteract (code)Playwright を完全に制御可能
Info

Interact と Browser Sandbox の違い: Interact は Browser Sandbox と同じインフラ上に構築されていますが、最も一般的なパターン、つまりページをスクレイピングしてからさらに深く進む場合に、より使いやすいインターフェースを提供します。Browser Sandbox は、特定のスクレイピングに紐づかない独立したブラウザセッションが必要な場合に適しています。

料金#

  • コードのみ (prompt なし): セッション1分あたり2 credits
  • AI プロンプト あり: セッション1分あたり7 credits
  • スクレイピング: スクレイピング自体の請求は別途行われます (スクレイピング1回あたり1 credit に加え、format ごとのコスト) 。

API リファレンス#

リクエスト本文 (POST)#

フィールドデフォルト説明
promptstringなしAIエージェント向けの自然言語タスクです。code が設定されていない場合は必須です。最大10,000文字。
codestringなし実行するコード (Node.js、Python、または Bash) 。prompt が設定されていない場合は必須です。最大100,000文字。
languagestring"node""node""python"、または "bash"code を使用する場合にのみ指定します。
timeoutnumber30タイムアウト時間 (秒) (1~300) 。
originstringなしアクティビティ追跡用の呼び出し元識別子。

レスポンス#

FieldDescription
successエラーなく実行が完了した場合は true
cdpUrlブラウザセッション用の生の Chrome DevTools Protocol (CDP) WebSocket URL。Playwright、Puppeteer、または任意の CDP クライアントで直接接続できます
liveViewUrlブラウザセッション用の読み取り専用のライブビュー URL
interactiveLiveViewUrlインタラクティブ ライブビュー URL (閲覧者がブラウザを操作できます)
outputプロンプトに対するエージェントの自然言語での回答。prompt を使用している場合にのみ含まれます。
stdoutコード実行時の標準出力
resultサンドボックスからの生の戻り値。code の場合: 最後に評価された式。prompt の場合: エージェントが output の生成に使用した生のページスナップショット。
stderr標準エラー出力
exitCode終了コード (0 = 成功)
killedタイムアウトにより実行が終了した場合は true

フィードバックやサポートが必要な場合は、help@firecrawl.com にメールするか、Discord でお問い合わせください。