data-feeds

Bright Data — データフィード（パイプライン）

bdata pipelines を使って構造化データを抽出します。事前構築済みのスクレイパーを検索し、入力項目を確認して実行すると、整った JSON を取得できます。スクレイピングのロジックは不要です。適したスクレイパーがない場合は、scrape に引き継ぎます。まず対象 URL を見つける必要がある場合は、search に引き継ぎます。

セットアップゲート（最初に実行）

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

いずれかのチェックに失敗した場合は処理を中断し、skills/bright-data-best-practices/references/cli-setup.md に案内してください。

ワークフロー（必ず search、次に info、最後に run）

CLI 0.4.0 以降が必要です。固定パイプラインタイプ（bdata pipelines <type> <url>）、bdata pipelines list、トップレベルの bdata status は削除されました。dataset_id、メソッド名、フィールド名を推測してはいけません。毎回調べてください。

# 1. Find a scraper by site or data type
bdata pipelines search <site or data type> [--limit n]

# 2. List its collection methods
bdata pipelines info <dataset_id>

# 3. Show one method's input fields, example input and a ready-to-run command
bdata pipelines info <dataset_id> <method>

# 4. Run it
bdata pipelines run <dataset_id> <method> <url> [--<field> <value>...]

• search は dataset_id、名前、ドメイン、collection_methods を返します。2 つのスクレイパーが同じ名前を持つ場合があるため、dataset_id とドメインで選んでください。
• collect_by_url は入力 URL ごとに 1 件のレコードを返します。discover_by_* メソッド（キーワード、カテゴリ URL など）は、入力ごとに最大 --limit-per-input 件のレコードを返します（デフォルトは 10 件です）。
• スペルミスがある場合も含め、メソッド名は記載どおりに使用してください。

コマンドの詳細については、../brightdata-cli/references/pipelines.md を参照してください。

実行方法を選ぶ

状況	アクション
サイトが分かっており、URL もある	スクレイパーを search で検索し、info を実行してから、run ... collect_by_url <url>... を実行します
どのスクレイパーが適しているか分からない	bdata pipelines search <site or data type> を実行し、結果を比較します
入力がキーワード、カテゴリ、その他の URL 以外のフィールドである	discover_by_* メソッドを使用します。info <dataset_id> <method> でフィールドを確認できます
同じスクレイパーで複数の URL を処理する	すべてを 1 回の run に渡します（URL ごとに 1 レコード）
レコードごとに値が異なる、またはネストされた入力を使う	--input '<json>' または --input @records.json を使用します
時間のかかるジョブ（レビュー、大規模なフィード、discover メソッド）	--async を指定してから status --wait と results を実行します。または、--timeout 1800 に引き上げます
サイトに適したスクレイパーがない	処理を中断し、scrape に引き継ぎます
先に URL を見つける必要がある	search に引き継ぎます

アクション

基本的なコマンド：

# Find the scraper and its inputs (example query; use the user's site)
bdata pipelines search "<site or data type>"
bdata pipelines info <dataset_id>
bdata pipelines info <dataset_id> collect_by_url

# One record per URL; other --<field> flags apply to every record
bdata pipelines run <dataset_id> collect_by_url "<url1>" "<url2>" \
    --format json --pretty -o out.json

# Discover method: no URL, fields as flags, keep the limit small (every record is billed)
bdata pipelines run <dataset_id> <discover_method> --<field> "<value>" \
    --limit-per-input 5 -o out.json

# Per-record values or nested data as JSON
bdata pipelines run <dataset_id> <method> --input @records.json -o out.json

# Long job: start async, come back later
bdata pipelines run <dataset_id> <method> "<url>" --async   # prints snapshot_id
bdata pipelines status <snapshot_id> --wait
bdata pipelines results <snapshot_id> --format ndjson -o out.ndjson

# Script-friendly: JSON from search when piped or with --json
bdata pipelines search "<site or data type>" --json | jq -r '.[] | "\(.dataset_id) \(.domain) \(.name)"'

必須フィールドが不明または不足している場合、何も起動される前にエラーになります。そのため課金は発生しません。エラーには有効なフィールドが表示されます。

フラグの詳細については、references/flags.md を参照してください。

検証ゲート

1. JSON を正常に解析できること： jq . <output> が 0 を返すこと（--format ndjson の場合は、各行を解析できること）。
2. レコード数が想定どおりであること。 collect_by_url は通常、URL ごとに 1 件のレコードを返しますが、レビュー、投稿、コメントのスクレイパーと discover_by_* メソッドは、サイトに表示される件数分の配列を返します（--limit-per-input で上限が設定されます）。必ず次を確認してください：

   jq 'length' out.json                       # top-level array count
   # OR
   jq 'if type == "array" then length else 1 end' out.json
   

3. トップレベルのエラーがないこと：

   jq -e 'if type == "object" then has("error") | not else true end' out.json \
       || { echo "pipeline reported error"; exit 1; }
   

4. レコード単位のエラーがないこと： 配列の結果では、どのレコードにも error フィールドがないことを確認します：

   jq -e 'if type == "array" then map(has("error")) | any | not else true end' out.json \
       || echo "WARN: one or more records have error fields"
   

   一部の失敗は通知されません。このチェックは必須です。
5. 主要フィールドが存在すること。 フィールドはスクレイパーごとに異なります。最初のレコードに対して jq '.[0] | keys' を実行して抜き取り確認し、ユーザーの依頼内容と照らし合わせてください。
6. 失敗した場合： レコードの error フィールドを確認します（メソッドに対して種類が異なる URL であることがよくあります）。bdata pipelines info <dataset_id> <method> を再確認してから、--timeout を 2 倍にする（または --async を使用する）などして 1 回だけ再試行してください。それでも失敗する場合は、フォールバックとして bdata scrape <url> を実行すると、ページを Markdown 形式で取得できます。

注意すべき兆候

• 先に search と info を実行せず、dataset_id、メソッド名、フィールド名を推測すること。
• 削除済みのコマンドを使用すること：bdata pipelines <type> <url>、bdata pipelines list、bdata status。これらはヒントを表示して終了します。search + info + run と bdata pipelines status <snapshot_id> を使用してください。
• あらかじめスクレーパーが用意されているサイトに bdata scrape を使用すること。構造が失われ、時間も余計にかかります。
• 1 回の run で複数の URL を受け付けるのに、URL ごとに bdata pipelines run を繰り返すこと。繰り返す必要がある場合は、並列実行数を 2～3 に制限してください。
• discover_by_* メソッドで大きな --limit-per-input を指定すること。レコードごとに課金されるため、入力を 1 件にして少ない上限から始めてください。
• レコード数とレコードごとのエラーチェックを行わずに、成功したと断言すること。パイプラインの出力では一部の失敗が通知されません。
• メソッド名のスペルミスを「修正」すること。info の一覧に記載されたとおりに使用してください。
• 正当に 5～15 分かかる実行に、短すぎる --timeout を指定すること。デフォルトの 600s は小規模な入力に適しています。長時間かかる場合は値を増やすか、--async を使用してください。

参考資料

• ../brightdata-cli/references/pipelines.md：bdata pipelines の正式なリファレンス。
• references/flags.md：search、info、run、status、results のフラグとタイムアウトのガイダンス。
• references/patterns.md：スクレーパーの選定ワークフロー、入力パターン、非同期実行、バッチ処理、一部失敗の検出、従来の curl による代替方法、共通の検証チェックリスト。
• references/examples.md：（1）単一 URL、（2）1 回の実行で複数の URL、（3）--async を使用した長時間ジョブ、（4）キーワードによる検出、（5）レコードごとの JSON 入力。