scrape

Bright Data — スクレイピング

Bright Data CLI を介して、1 つ以上の URL からクリーンなコンテンツ（Markdown、HTML、JSON、スクリーンショット）を取得します。このスキルは、「生データまたは軽く構造化されたコンテンツを取得する」役割を担います（「fetch raw or lightly-structured content」）。プラットフォーム固有の構造化データ（Amazon、LinkedIn、TikTok など）の場合は、そこで停止して、代わりに data-feeds を使用してください。セレクターロジックなしでクリーンな JSON を取得できます。

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

スクレイピングを行う前に、CLI がインストールされ、認証済みであることを確認します。

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 を案内してください。従来の curl によるフォールバックをユーザーに確認せずに試してはいけません。

方法を選択

状況	対応
URL が 1 つ	bdata scrape <url> -f markdown
小規模なリスト（約 20 件以下）	シェルループで 1 件ずつ実行（references/patterns.md を参照）
大規模なリスト（数十件以上）	並列数を制限して xargs -P 4 を使用（references/patterns.md を参照）
ページネーション付きの一覧	1 ページ目をスクレイピング → 次ページの URL を抽出 → 追加 → 繰り返し（references/examples.md を参照）
JavaScript への依存が大きい／ログインが必要／操作が必要	bdata browser に切り替え（brightdata-cli スキルを参照）
Amazon、LinkedIn、TikTok、Instagram、YouTube、Reddit、…	停止し、data-feeds に引き継いでください
URL がなく、トピックだけがある	search に引き継いでください

操作

基本コマンド：

# Clean markdown (default)
bdata scrape "https://example.com/article" -f markdown -o article.md

# Raw HTML (when you need the DOM)
bdata scrape "https://example.com" -f html -o page.html

# Structured JSON (when the Unlocker returns parsed fields)
bdata scrape "https://example.com" -f json --pretty -o page.json

# Visual snapshot (saves PNG)
bdata scrape "https://example.com" -f screenshot -o page.png

# Geo-targeted (override the exit country)
bdata scrape "https://example.com" --country de -f markdown

すべてのフラグのリファレンス：references/flags.md。

検証の確認（成功を報告する前に実行）

1. 出力が空でないこと： test -s "$out_path" を実行します。標準出力の場合は、少なくとも 200 バイトのコンテンツがあることを確認します。
2. ブロックページではないこと — 出力に以下のいずれかの特徴的な文字列が含まれていないか、大文字・小文字を区別せずに grep で検索します。
   • Access Denied
   • Just a moment
   • Attention Required
   • Checking your browser
   • captcha
   • cf-browser-verification
   • cloudflare（本文全体が 2KB 未満の場合）
3. タスクに必要な目印が存在すること： たとえば、商品ページには価格のパターン（\$\d）、記事には少なくとも 1 つの <h1> または # 見出しが含まれている必要があります。
4. 失敗した場合のエスカレーション手順：
   • --country を別の値にして再試行します（例：対象サイトの接続元が米国の場合は --country de）。
   • 完全な JavaScript レンダリングのため bdata browser に切り替えます（brightdata-cli スキルに引き継ぎます）。

上記のすべての確認に合格するまで、成功を報告しないでください。

注意事項

• 出力を確認せずに成功を報告すること。
• 2>/dev/null でエラーを隠すこと — 認証エラーやレート制限エラーを見落とします。
• Amazon／LinkedIn／TikTok／Instagram／YouTube／Reddit の URL に bdata scrape を実行すること — これらは data-feeds がサポートしており、構造化データを直接返します。スクレイピングすると構造が失われます。
• 同じタスク内で同じ URL を繰り返しスクレイピングすること — 最初の結果をキャッシュしてください。
• 並列数に上限を設けて xargs -P 4（または同様の方法）を使わずに、大規模なリストに対して bdata scrape を順番にループ実行すること。
• api.brightdata.com に直接 curl すること — これは従来の方法であり、CLI を利用できない場合に限ります。

リファレンス

• references/flags.md — 各フラグと使用する場面についての説明。
• references/patterns.md — シェルループによるバッチ処理、xargs の並列実行、ページネーションの手順、再試行／バックオフ、ブロックページからの復旧手順、従来の curl によるフォールバック。
• references/examples.md — （1）単一ページを Markdown に変換、（2）並列数を制限して URL のリストをバッチ処理、（3）ページネーション付きの一覧、（4）ブロックページからの復旧。