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。

工作流（始终先搜索，再查看信息，然后运行）

需要 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。两个抓取器可能同名，因此请根据 dataset_id 和域名进行选择。
• collect_by_url 对每个输入 URL 返回一条记录。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	在一次 run 中传入所有 URL（每个 URL 对应一条记录）
每条记录的值不同，或输入为嵌套结构	使用 --input '<json>' 或 --input @records.json
耗时较长的任务（评论、大型馈送、发现方法）	使用 --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 返回一条记录，但评论、帖子和留言抓取器以及 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 加倍（或使用 --async）并重试一次。如果仍然失败，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。这会丢失结构并耗费更多时间。
• 每个 URL 都循环运行一次 bdata pipelines run，而一次 run 可以接受多个 URL。如果必须循环，请将并行数限制在 2 到 3。
• 对 discover_by_* 方法设置较大的 --limit-per-input。每条记录都会计费；请从一个输入和较小的限制开始。
• 未检查记录数和逐条记录错误就声称成功。管道输出不会显示部分失败。
• “修正”拼写错误的方法名。请严格按照 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）一次运行中处理多个 URL，（3）使用 --async 运行长任务，（4）按关键词发现，（5）逐条记录的 JSON 输入。