scraper-studio

Bright Data — Scraper Studio

自然言語でスクレーパーを作成し、実行します。このスキルには2つのコマンドがあります。

• bdata scraper create <url> <description> — 必要な内容を平易な英語で説明すると、Bright Data の AI Flow がスクレーパーテンプレートを生成し、collector_id を返します。
• bdata scraper run <collector_id> <url> — そのコレクター（または Bright Data のウェブ UI で作成済みのコレクター）を URL に対して実行し、抽出したデータを取得します。

この2つをつなぐのが collector_id です。 create が出力し、run が使用します。必ず保存してください。

Amazon、LinkedIn、TikTok、Instagram、YouTube、Reddit などのプラットフォーム向けの既成スクレーパーがある場合は、ここで止めて data-feeds スキルを使用してください。これらのスクレーパーはすでに用意されており、新規作成するよりも高速で、安価で、信頼性に優れています。対象サイトに既成スクレーパーがない場合や、既存プラットフォーム向けにカスタム形式の出力を求められた場合は、Scraper Studio を使用してください。

セットアップの確認（最初に実行）

if ! command -v bdata >/dev/null 2>&1; then
    echo "bdata CLI not installed — see bright-data-best-practices/references/cli-setup.md"
elif ! bdata zones >/dev/null 2>&1; then
    echo "bdata not authenticated — run: bdata login  (or: bdata login --device for SSH)"
fi

いずれかの確認に失敗した場合は、処理を中断してセットアップに進んでください。どちらのコマンドも、認証済みの CLI が必要です。

実行する操作を選択

状況	操作
ユーザーが URL から取得したいデータを説明しており、スクレーパーがまだない	bdata scraper create <url> "<description>" → collector_id を保存する
ユーザーが collector_id を持っており、1つの URL からデータを取得したい	bdata scraper run <collector_id> <url>（デフォルトでは非同期実行してポーリング）
ユーザーが collector_id を持っており、複数の URL からデータを取得したい	bdata scraper run <collector_id> --urls "u1,u2,..." または --input-file urls.txt（1回のバッチ呼び出し）
ページが小さく、すばやく結果を確認したい（約50秒以内、URL 1件）	bdata scraper run … --sync
スクレーパーの実行後に誤ったデータ、空のデータ、または一部のデータしか返されない	出力を確認し、bdata scraper heal <collector_id> "<what's wrong>" を実行 → プレビューを確認 → 承認 → 再実行して検証する
対象サイトが既知のプラットフォーム（Amazon、LinkedIn、TikTok など）	ここで止めて、data-feeds スキルを使用する
抽出ではなく、SERP や情報の発見をしたい	search スキルを使用する
1回だけページの生データを取得したい	scrape スキルを使用する

---

アクション1 — scraper create

URL と平易な英語の説明からスクレーパーを生成します。

bdata scraper create <url> "<description>" [--name <name>] \
    [--deliver-webhook <url>] [--timeout <seconds>] \
    [--json | --pretty] [-o <path>] [--timing] [-k <api-key>]

説明は最も重要な入力です。良い説明では、必要なフィールドをすべて挙げ、それらの見つけ方に条件があれば明記します。適切な説明と不適切な説明の例については、references/prompts.md を参照してください。

# Minimal
bdata scraper create https://example.com/product/1 \
    "Extract title, price, currency, image URL, and availability \
     from this product page. If the price has a strike-through \
     original price, capture both as price and original_price."

# Save the full AI output for inspection
bdata scraper create https://example.com/product/1 \
    "Extract title, price, and image URL" \
    --name product-scraper-v1 \
    --pretty -o create.json

内部で行われる処理

create は Bright Data API を3回呼び出します。ログからデバッグできるよう、この内容をユーザーに伝えてください。

1. POST /dca/collector — 仮の Webhook 配信先（デフォルトは https://example.com/webhook）を設定した、空のスクレーパーテンプレートを作成します。c_mp3tuab31lswoxvpws のような collector_id を返します。
2. POST /dca/collectors/{collector_id}/automate_template — 説明と URL を指定して、Bright Data の AI Flow を起動します。
3. GET .../automate_template/progress（ポーリング）— status: "done" になるまで待機します。中程度の複雑さのページでは、生成に通常 5～10分かかります。

重要：collector_id を保持する

create の失敗時（AI の起動失敗、ポーリングのタイムアウト、status: "failed" での生成完了）でも、出力された collector_id のコレクターは部分的に作成された状態で残ります。この ID は復旧に利用できることを、必ずユーザーに伝えてください。ユーザーは次の操作を行えます。

• https://brightdata.com/cp/scrapers/{collector_id} を開き、ウェブ UI で仕上げるか内容を確認する。
• 同じ ID に対して、プログラムから生成を再度トリガーする。
• 最初からやり直したい場合は、UI から削除する。

レスポンスの collector_id を伝えずに、「作成に失敗しました。最初からやり直してください」と案内してはいけません。

--timeout — デフォルトは 600 s

複雑なページでは、AI 生成に 5～10 分かかることがあります。ページがシンプルであれば、デフォルトで十分です。負荷の高いサイトで詳細な説明を生成する場合は、値を大きくしてください。

bdata scraper create https://complex-site.com/page \
    "Extract all 30 fields …" \
    --timeout 1200

Timeout after N seconds waiting for AI generation が表示された場合でも、collector_id は出力されます。create を再実行すると新しいコレクターが作成されるため、再実行するのではなく、Web UI で進行状況を確認してください。

--deliver-webhook — デフォルトはプレースホルダー

CLI はスタブの Webhook（https://example.com/webhook）を設定します。これは API の契約を満たしますが、何も配信しません。CLI で使用する場合はスタブのままにしてください。結果は scraper run で同期的に取得します。本番実行で Webhook 配信を希望する場合は、Bright Data web UI で実際の配信先を再設定できます。

---

アクション 2 — scraper run

1 つ以上の URL に対してスクレイパーを実行します。

bdata scraper run <collector_id> [url] \
    [--urls "u1,u2,..." | --input-file <path>] \
    [--sync [--sync-timeout 25-50]] \
    [--timeout <seconds>] [--name <name>] [--version <version>] \
    [--json | --pretty] [-o <path>] [--timing] [-k <api-key>]

入力元は必ず 1 つだけ選んでください： 位置引数の <url>、--urls、または --input-file です。これらを組み合わせると、only one input source というエラーになります。

複数 URL の場合は、配列のリクエスト本文を使った 1 回の API 呼び出しとして /dca/trigger 経由で実行します。これは、Scraper Studio Node および Python のリファレンスプロジェクト（triggerWithUrls / trigger_with_urls）で採用されている標準的なパターンです。スナップショットは 1 つ、ポーリングループは 1 つ、結果は統合された配列が 1 つです。for url in $(cat urls.txt); do bdata scraper run ... のようなループを独自に作成しないでください。 1 回で済む処理に N 回の API 呼び出しを行うことになります。

実行モードの選択

                ┌─────────────────────────────────────────────────┐
                │ Expected to finish in ≤ ~50 seconds?            │
                └─────────────────────────────────────────────────┘
                 yes                                       no
                  │                                         │
                  ▼                                         ▼
       ┌──────────────────────┐                ┌────────────────────────┐
       │   --sync             │                │  default (no flag)     │
       │   /dca/crawl         │                │  trigger_immediate +   │
       │   one-shot, 25–50 s  │                │  poll get_result       │
       └──────────────────────┘                └────────────────────────┘
                  │
                  │  on 202 timeout: response_id is printed —
                  │  re-run WITHOUT --sync to poll for it
                  ▼
            (cleanly fall back to async)

モード	エンドポイント	使用する場面
デフォルト（単一 URL、非同期＋ポーリング）	/dca/trigger_immediate → /dca/get_result をポーリング	約 50 s を超えると予想される処理、ページネーションのある処理、所要時間が不明な処理。単一 URL では、これが安全なデフォルトです。
--sync（単一 URL）	/dca/crawl	50 s 未満で完了すると予想される、単一ページの抽出。より高速な方法で、リクエストは 1 回で済み、ポーリングも不要です。複数 URL とは併用できません — /dca/crawl が受け付ける URL は 1 つだけです。
複数 URL（--urls / --input-file）	/dca/trigger（配列のリクエスト本文）→ /dca/dataset をポーリング	同じコレクターで 2 件以上の URL を処理する場合。API 呼び出しは 1 回、スナップショット ID は 1 つ、結果は統合された配列が 1 つです。大規模なバッチでは、長めの --timeout（デフォルトは 3600s）を使用してください。

# Default — async + poll (recommended for most cases)
bdata scraper run c_mp3tuab31lswoxvpws https://www.amazon.com/dp/B08N5WRWNW

# Pretty-printed, saved to disk
bdata scraper run c_mp3tuab31lswoxvpws https://www.amazon.com/dp/B08N5WRWNW \
    --pretty -o product.json

# Sync mode for a fast page
bdata scraper run c_mp3tuab31lswoxvpws https://example.com/p/1 --sync

# Sync with a tighter server timeout
bdata scraper run c_mp3tuab31lswoxvpws https://example.com/p/1 \
    --sync --sync-timeout 30

# Multi-URL via comma-separated list — one batch call
bdata scraper run c_mp3tuab31lswoxvpws \
    --urls "https://example.com/p/1,https://example.com/p/2,https://example.com/p/3" \
    --pretty -o products.json

# Multi-URL via file (one URL per line; # comments and blanks ignored)
bdata scraper run c_mp3tuab31lswoxvpws --input-file urls.txt -o products.json

# Multi-URL via JSON array
echo '["https://example.com/p/1","https://example.com/p/2"]' > urls.json
bdata scraper run c_mp3tuab31lswoxvpws --input-file urls.json

--sync-timeout の範囲は 25～50 です

この範囲外の値を指定すると、--sync-timeout must be between 25 and 50 seconds と表示されて終了します。デフォルトは 50 です。値を 50 未満にするのは、時間のかかるページで早めに失敗させ、非同期処理に切り替えたい場合だけにしてください。

--sync のタイムアウトからの復旧

/dca/crawl がサーバー側でタイムアウトすると、{"error":"crawl_results_timeout","response_id":"r_late_..."} を含む 202 が返されます。CLI は response_id を表示し、「--sync を付けずに再実行」というメッセージを出して終了します。その指示どおりにしてください。--sync を外し、同じコマンドを再実行します。デフォルトの非同期処理では、既存の response_id に対して /dca/get_result をポーリングします。同期処理のタイムアウトを致命的な失敗として扱わないでください。

サイレントなバッチへの自動フォールバック（ページネーションのあるページ／大規模なページ）

1 つの URL から、リアルタイムジョブの上限を超える数のページに展開される場合（ページネーションのある一覧、無限スクロール、「すべてのレビュー」ページなど）、リアルタイムエンドポイントは次のようなエラーを返します。

Request generated 501 pages and exceeded realtime job limit of 51 pages

CLI はこれを検知し、バッチ処理（/dca/trigger → /dca/dataset をポーリング）に自動的にフォールバックします。通知は 1 行表示されます。フラグは不要です。バッチジョブのポーリング間隔は長め（10 s）で、デフォルトのタイムアウトも長め（1 時間）です。

ユーザーに通知だけが表示され、長時間待つことになっても、これは想定どおりです。大規模なジョブには時間がかかります。API を切り替えたり、スクレイパーの構成を変更したりしてフォールバックを「修正」しようとせず、そのまま処理を続けてください。

--name and --version

• --name <name> — Bright Data ダッシュボードでこの実行にタグを付けます。多数の実行をスクリプト化していて、あとから見つけたい場合に便利です。
• --version <version> — 特定のスクレイパーバージョンを固定します（ウェブ UI で反復作業を行う場合は、通常 dev を指定します）。最新の公開バージョンを使う場合は省略してください。

---

アクション 3 — scraper heal

実行は成功したものの、誤ったデータ、空のデータ、または一部のみのデータが返された場合、既存のスクレイパーをその場で修正します。スクレイパーの collector_id は変わりません。置き換えるのではなく、改善します。

bdata scraper heal <collector_id> "<what's wrong>" [--url <verify-url>] \
    [--timeout <seconds>] [--max-retries <n>] [--no-retry] \
    [--json | --pretty] [-o <path>] [--timing] [-k <api-key>]

不具合を検知するのはあなたです。 CLI が独自にスクレイパーの不具合を判断することはありません。実行結果を確認し、判断してください。修復には時間がかかり、料金も発生するため、データに問題がある場合にのみ修復してください。正当な理由でデータが空の場合は、修復しないでください。

<prompt> は必須で、最も重要な入力です。何が問題で、正しい出力がどうあるべきかを具体的に指定してください。例：「価格フィールドが null を返します。セレクターが <span data-testid=...> 内に移動しました。価格と通貨を再取得してください。」 曖昧なプロンプト（「修正して」など）では、曖昧な修復結果になります。プロンプトの上限は 1000 文字です。

内部での処理

1. POST /dca/collectors/{collector_id}/refactor_template に {prompt, custom_input: []} を指定します。AI による自動修復ジョブが開始されます。
2. GET .../refactor_template/progress（ポーリング）で status: "done" になるまで待ちます。ジョブの形式と所要時間は automate_template と同じです。

出力と検証ループ

heal（--auto-approve なし）は、通常、すぐに完了するのではなく承認ゲートで停止します。レスポンスには status: "awaiting_approval" と、重要な 2 つのフィールドが含まれます。

• preview_result — 修正後のスクレイパーが生成するサンプル行です。修正を適用する前に、正しいかどうかを判断できます。
• diff_summary — テンプレートの変更内容の概要です。
• next_step — 適用するには bdata scraper approve <collector_id> を、破棄するには --reject を指定するよう案内します。

{
  "collector_id": "c_mp3tuab31lswoxvpws",
  "status": "awaiting_approval",
  "preview_result": [{"price": "29.99", "currency": "USD"}],
  "diff_summary": "Updated price selector from .price to span[data-testid='price']",
  "next_step": "bdata scraper approve c_mp3tuab31lswoxvpws"
}

preview_result を確認してから、bdata scraper approve <collector_id> を実行して修正を適用してください。または、--reject を指定して修正を破棄し、より具体的なプロンプトで再度修復してください。approve は done になるまでポーリングし、検証用の next_step として bdata scraper run <id> <url> を返します。

heal に --url <verify-url> を渡すと、承認と実行の手順を具体的に指定できます。自動修復の全体的なループは次のとおりです。

run → inspect → heal → review preview → approve → run → verify

承認ゲートを完全にスキップするには、heal --auto-approve を使用します。自動的に承認され、done になるまでポーリングされます。

失敗しても既存のスクレイパーに影響はありません

修復に失敗した場合（429 の上限到達、タイムアウト、終端状態の failed など）、既存のスクレイパーは変更されず、以前と同じように動作します。CLI はその旨と collector_id を表示します。失敗した create とは異なり、中途半端な状態のものが残ることはありません。

---

アクション 4 — scraper approve

--auto-approve を指定せずに scraper heal を実行すると、承認ゲートで停止します。status: "awaiting_approval" と、修正後のスクレイパーが生成するサンプル行を含む preview_result、および diff_summary が表示されます。プレビューを確認してから修正を適用してください。

bdata scraper approve <collector_id> [--reject] [--url <verify-url>] \
    [--timeout <seconds>] [--json | --pretty] [-o <path>] [-k <api-key>]

• デフォルトでは承認します（POST /dca/collectors/{id}/resume_automation_job {"message": true}）。その後、done になるまでポーリングし、検証用の next_step として bdata scraper run <id> <url> を返します。
• --reject を指定すると、提案された修正を破棄するために {"message": false} を送信します。再試行するには、より具体的なプロンプトで再度修復してください。
• 修復に複数回の承認が必要な場合、approve が再び awaiting_approval で停止することがあります。その場合は、もう一度実行してください。

awaiting_approval は失敗ではありません。修正の準備ができており、あなたの判断を待っていることを意味します。

作成してから実行する全体のワークフロー

jq で collector_id を確実に取得し、複数 URL の一括処理パスを使って run を続けて実行します。

# 1. Create the scraper, save the AI output, extract the collector_id
bdata scraper create https://example.com/product/1 \
    "Extract title, price, currency, image URL, and availability" \
    --pretty -o create.json

# 2. Pull the collector_id (or copy from the human-readable summary)
COLLECTOR_ID=$(jq -r '.collector_id // .id' create.json)
echo "Built: $COLLECTOR_ID"

# 3. Run it on every URL in one batch — single API call, merged result array
bdata scraper run "$COLLECTOR_ID" --input-file urls.txt \
    --pretty -o out/results.json

bdata scraper run を for url in $(cat urls.txt); do ... done ループで囲まないでください。 これでは API 呼び出しが N 回、スナップショットが N 個になります。代わりに --input-file urls.txt（または --urls "..."）を使ってください。CLI はすべての URL を 1 つの配列ボディで /dca/trigger に POST し、統合された結果配列を 1 つ返します。

エンドツーエンドのレシピ（バッチ入力ファイルの形式、エラーからの復旧、Web UI への引き継ぎ）については、references/recipes.md をご覧ください。

---

よくある間違い

1. コマンド名をでっち上げる。 コマンド名は bdata scraper create と bdata scraper run です。bdata generate、bdata scrape-batch、bdata data、bdata build はありません。これらのどれかを使おうとしているなら、幻覚を起こしています。bdata scraper --help を実行して確認してください。

2. タイムアウト後に create を再実行する。 生成するたびに新しいコレクターが作成されます。ポーリングがタイムアウトしても、作成途中のコレクターはエラー出力に表示されています。Web UI で再開するか、待ってから再度ポーリングしてください。別のコレクターを無駄に作らないでください。

3. 何でも --sync にする。 サーバー側では同期処理の上限が 50 秒です。ページネーションのあるページや負荷の高い SPA はタイムアウトします。ページが小さいと明確に分かっている場合を除き、デフォルトの非同期処理を使ってください。

4. 既知のプラットフォームで Scraper Studio を使わない。 対象が Amazon、LinkedIn、TikTok、Instagram、YouTube、Reddit などの場合、data-feeds スキルで公開されている事前構築済みのスクレイパーのほうが、より高速で、低コストで、信頼性も高くなります。そのサイト用の事前構築済みスクレイパーがない場合、またはユーザーがカスタムの出力形式を明示的に希望している場合にのみ、カスタムスクレイパーを作成してください。

5. 同期処理のタイムアウトを失敗と見なす。 --sync の 202 タイムアウトでは、有効な response_id が返されます。ジョブはバックエンドで引き続き実行中です。同じコマンドを --sync なしで再実行すると、処理を引き継げます。

6. エラー時に collector_id／response_id を破棄する。 CLI は意図的に、すべての失敗経路でこれらを出力します。どちらも API と Web UI から復旧できます。必ずユーザーに伝えてください。

7. バッチの自動フォールバックを無効にしようとする。 そのためのフラグはありません。URL の展開後のページ数がリアルタイムのページ上限を超えた場合、フォールバックするのが正しい動作です。そのまま実行させてください。

8. for url in $(cat urls.txt); do bdata scraper run ... ループを手作業で作る。 API が本来 1 つのバッチとして扱う処理に対して、API 呼び出しが N 回、スナップショット ID が N 個、ポーリングループが N 回になります。--input-file urls.txt または --urls "u1,u2,..." を使ってください。CLI は配列全体を 1 回のリクエストで /dca/trigger に POST し、統合された結果配列を 1 つ返します。これは Scraper Studio の参照 SDK にある標準的な triggerWithUrls／trigger_with_urls ヘルパーと同じ動作です。

9. create で曖昧な説明をする。 「ページをスクレイピングする」のような説明では、汎用的なスクレイパーが作成されます。すべてのフィールドを指定し、条件（「セール価格がある場合は、両方の価格を取得する」）を明記し、判別条件（「おすすめ欄ではなく、タイトルの近くにある価格」）を指定してください。references/prompts.md をご覧ください。

10. 壊れたスクレイパーを修正するために create を再実行する。 これでは新しいコレクターが作成され、古いコレクターは放置されます。既存のスクレイパーを修正するには、bdata scraper heal <collector_id> "<what's wrong>" を使ってください。スクレイパーをその場で変更するため、保存済みの collector_id を引き続き使え、品質も向上します。

11. awaiting_approval を失敗と見なす。 これは heal の通常の終了状態です。修正内容の計算は完了しており、判断待ちの状態です。preview_result を確認してから、bdata scraper approve <id>（または --reject）を実行してください。承認手順を省略するには heal --auto-approve を使ってください。

---

トラブルシューティング

症状	原因	対処方法
bdata: command not found	CLI がインストールされていません	インストール方法については、brightdata-cli を参照してください。
Invalid or expired API key	ログインしていません	bdata login を実行します（SSH の場合は bdata login --device）。
create が id を返さない	テンプレートが作成される前に API 呼び出しが失敗しました	--timing の出力で失敗したリクエストを確認し、ネットワークとアカウントの状態を確認してください。
Timeout after 600 seconds waiting for AI generation	ページが複雑で、デフォルトのポーリング時間を超えました	collector_id は引き続き出力されます。ウェブ UI で開くか、--timeout 1200 を指定して再実行してください。
進捗状況のポーリングで status: "failed" が返る	AI Flow がテンプレートを作成できませんでした	説明を改善し、フィールドやセレクターについてより具体的に記述してください。より適切な URL（検索結果ではなく、正規の商品ページなど）を使って再試行してください。
--sync が crawl_results_timeout を伴う 202 を返す	ページの処理に同期サーバーの上限を超える時間がかかりました	--sync を指定せずに再実行し、出力された response_id を使って /dca/get_result をポーリングしてください。
--sync-timeout must be between 25 and 50 seconds	値が範囲外です	[25, 50] の範囲内の値を指定してください。
Request generated N pages and exceeded realtime job limit	URL が展開されすぎました	これは自動的に処理されます。バッチへのフォールバック通知を待ち、ポーリングさせてください。
データが返されず、[] または {} だけが返る	セレクターが一致しませんでした	スクレイパーテンプレートは実行されましたが、何も抽出されませんでした。https://brightdata.com/cp/scrapers/{collector_id} を開いて確認・編集するか、より具体的な説明で再構築してください。

---

参照ファイル

• references/prompts.md — AI Flow が処理できる scraper create の説明の書き方。適切な説明と不適切な説明の例、フィールドの列挙パターン、条件付きルールを紹介します。
• references/recipes.md — エンドツーエンドのレシピ：create から collector_id を取得する、URL のリストをバッチ実行する、同期から非同期へのフォールバックを処理する、失敗した create から復旧する、ダッシュボードからスクレイパーを一覧表示する。
• references/api-flow.md — CLI が使用する正確な REST エンドポイント、ペイロード、ステータスを示す値（/dca/collector、/dca/collectors/{id}/automate_template、/dca/trigger_immediate、/dca/get_result、/dca/crawl、/dca/trigger、/dca/dataset）。予期しない CLI 出力のデバッグ時や、ユーザーが API を直接呼び出したい場合に参照してください。