scrape

Bright Data — Scrape

透過 Bright Data CLI 從一個或多個 URL 取得乾淨內容（Markdown、HTML、JSON、螢幕截圖）。此技能負責「擷取原始或輕度結構化內容」的工作。對於平台特定的結構化資料（Amazon、LinkedIn、TikTok 等），請停止並改用 data-feeds — 您將獲得乾淨的 JSON，無需撰寫選擇器邏輯。

設定檢查（先執行）

在進行任何擷取之前，請確認 CLI 已安裝並通過驗證：

if ! command -v bdata >/dev/null 2>&1; then
    echo "bdata CLI 未安裝 — 請參閱 bright-data-best-practices/references/cli-setup.md"
elif ! bdata zones >/dev/null 2>&1; then
    echo "bdata 未通過驗證 — 執行: bdata login  (或: bdata login --device 用於 SSH)"
fi

如果任一檢查失敗，請停止並引導使用者至 skills/bright-data-best-practices/references/cli-setup.md。請勿在未告知使用者的情況下，默默使用舊版 curl 作為備援方案。

選擇您的路徑

情況	動作
單一 URL	bdata scrape <url> -f markdown
少量清單（≤ 約 20 個 URL）	shell 迴圈，一次一個（請參閱 references/patterns.md）
大量清單（數十個以上）	使用 xargs -P 4 並設定並行上限（請參閱 references/patterns.md）
分頁列表	擷取第 1 頁 → 提取下一頁 URL → 附加 → 重複（請參閱 references/examples.md）
JS 繁重 / 需登入 / 需互動	升級至 bdata browser（請參閱 brightdata-cli 技能）
Amazon、LinkedIn、TikTok、Instagram、YouTube、Reddit 等	停止 — 轉交給 data-feeds
尚無 URL，僅有主題	轉交給 search

執行

核心指令：

# 乾淨的 Markdown（預設）
bdata scrape "https://example.com/article" -f markdown -o article.md

# 原始 HTML（當您需要 DOM 時）
bdata scrape "https://example.com" -f html -o page.html

# 結構化 JSON（當 Unlocker 回傳解析後的欄位時）
bdata scrape "https://example.com" -f json --pretty -o page.json

# 視覺快照（儲存 PNG）
bdata scrape "https://example.com" -f screenshot -o page.png

# 地理定位（覆蓋出口國家）
bdata scrape "https://example.com" --country de -f markdown

完整旗標參考：references/flags.md。

驗證檢查（在宣稱成功前執行）

1. 非空輸出： test -s "$out_path" — 或者，對於標準輸出，至少 200 位元組的內容。
2. 非封鎖頁面 — 在輸出中搜尋以下任何特徵（不區分大小寫）：
   • Access Denied
   • Just a moment
   • Attention Required
   • Checking your browser
   • captcha
   • cf-browser-verification
   • cloudflare （且總內容小於 2KB）
3. 任務應有的標記存在： 例如，產品頁面應包含價格模式（\$\d）；文章應包含至少一個 <h1> 或 # 標題。
4. 失敗時的升級步驟：
   • 使用不同的 --country 重試（例如，若來源網站位於美國，可使用 --country de）
   • 升級至 bdata browser 以進行完整的 JS 渲染（轉交給 brightdata-cli 技能）

在通過上述所有檢查之前，請勿報告成功。

紅旗

• 未檢查輸出即宣稱成功。
• 使用 2>/dev/null 忽略錯誤 — 您將錯過驗證失敗和速率限制錯誤。
• 對 Amazon/LinkedIn/TikTok/Instagram/YouTube/Reddit URL 執行 bdata scrape — 這些平台由 data-feeds 支援，可直接回傳結構化資料。使用擷取會失去結構。
• 在同一任務中重複擷取相同的 URL — 請快取第一次的結果。
• 對大量清單依序使用 bdata scrape 迴圈，而非使用 xargs -P 4（或類似方式）並設定並行上限。
• 直接使用 curl 對 api.brightdata.com — 這是舊版路徑；僅在 CLI 不可用時使用。

參考資料

• references/flags.md — 每個旗標及其使用時機說明。
• references/patterns.md — shell 迴圈批次處理、xargs 並行、分頁配方、重試/退避、封鎖頁面復原鏈、舊版 curl 備援方案。
• references/examples.md — (1) 單一頁面轉 Markdown，(2) 批次處理 URL 清單並設定並行上限，(3) 分頁列表，(4) 封鎖頁面復原。