brightdata-sdk

Bright Data SDK

通过统一的 Python SDK 访问 Web 数据。一个客户端，涵盖八类服务：平台抓取、平台搜索、Web 搜索（SERP）、AI 驱动的发现、数据集、Web 解锁、浏览器自动化和抓取工作室。

始终将客户端用作上下文管理器。在同步环境（脚本、笔记本、Claude Code）中，使用 SyncBrightDataClient。在异步环境中，使用 BrightDataClient。两者使用相同的方法名——同步客户端会自动封装调用。注意：同步客户端目前仅支持有限的平台——详情请参阅 references/scrapers.md 中的同步兼容性说明。对于不受支持的平台或数据集 API，请使用异步客户端（BrightDataClient）。

服务选择（先决定服务，再查找具体方法）

请使用此决策树选择合适的服务，然后再查找任何具体方法。大多数路由失败都是因为跳过了这一步，转而根据用户关键词进行模式匹配。

Have a URL?
  ├── On a supported platform (Amazon, LinkedIn, Facebook, Instagram, YouTube,
  │   TikTok, Reddit, ChatGPT, Perplexity, Pinterest, DigiKey)?
  │     → Platform scraping: client.scrape.<platform>.<method>(url=...)
  │
  ├── Generic page (not on any supported platform)?
  │     → Web unlocker: client.scrape_url(url=...)
  │
  └── Need login / JavaScript / click-scroll-fill / CAPTCHA / multi-step navigation?
        → Browser API: client.browser.get_connect_url() (then connect with Playwright)

No URL?
  ├── Want entities matching natural-language criteria
  │   ("find AI startups in Berlin", "competitors of Acme Corp", "people who worked at X")?
  │     → Discover: client.discover(query=..., intent=...)
  │
  ├── Want web pages / articles / search-result links
  │   ("search Google for X", "find pages about Y")?
  │     → SERP: client.search.google(query=...) [or .bing / .yandex]
  │
  ├── Want to search WITHIN a specific platform
  │   ("find products on Amazon", "TikTok videos by hashtag", "Pinterest pins about recipes")?
  │     → Platform search: client.search.<platform>.<method>(...)
  │
  └── Want bulk historical data at scale
      ("all LinkedIn companies in tech", "historical Amazon prices", "every Zillow listing in Texas")?
        → Datasets: client.datasets.<name>(filter=...) (then .download(snapshot_id))

边缘情况：

• URL 属于受支持的平台，但用户明确提到登录／点击／滚动／JS → 使用 Browser API（交互需求优先于平台）。
• URL 属于受支持的平台，但抓取工具返回 403／被拦截 → 回退到 client.scrape_url()（Web 解锁器）。
• 用户要求“查找／研究／X 是谁”，同时附带 URL（例如“查找 acme.com 的竞争对手”）→ 仍使用 Discover；URL 是上下文，不是抓取目标。

方法名称：先验证再断言

在声称某个平台方法存在或不存在，或断言某个平台不受支持之前，你必须先查阅 references/scrapers.md。过往评估显示，模型曾臆造方法名（例如，client.scrape.linkedin.people——并不存在；应使用 .profiles），也曾错误地声称某些平台不受支持（例如，Pinterest 同时支持 client.scrape.pinterest 和 client.search.pinterest）。

**规则：**在提及任何具体平台方法之前，先加载 references/scrapers.md。参考文件列出了所有平台、所有方法签名，以及同步／异步可用性矩阵。请先验证，不要想当然。如果本次会话中已加载 references/scrapers.md，请查阅上下文中的内容——无需重新加载。

已知臆造方法（这些名称在 SDK 中并不存在——模型在以往评估中臆造了它们）：

臆造方法	正确替代方法
client.scrape.linkedin.people(...)	client.scrape.linkedin.profiles(url=...)
client.scrape.instagram.users(...)	client.scrape.instagram.profiles(url=...)
client.list_datasets()	client.datasets.list()
asyncio.gather(*[client.scrape.X.<quick>(...) for ...])	触发模式——参见批处理注意事项

随着评估中发现新的臆造方法，此列表会不断增长。如果你想写一个“感觉正确”但从未在 references/scrapers.md 中见过的方法名，请将其视为可能是臆造的——加载参考文件并进行验证。

实用的独立方法

这些方法不属于任何特定工作流——由于它们没有关联到平台或路由决策，因此很容易被忽略。模型曾臆造其中一些方法（例如，用 client.list_datasets() 代替 client.datasets.list()）；请使用下方的规范名称。

方法	功能
client.datasets.list()	在运行时列出全部 310 多个数据集。不要使用 dir() 或内省——请使用此方法。
client.discover(query=, intent=)	AI 排序的实体搜索（公司、人物、产品）。参见上文的“服务选择”。
client.scrape_url(url=...)	用于任意 URL 的 Web 解锁器。适用于没有专用平台抓取工具的网站。
client.browser.get_connect_url()	用于 Playwright / Puppeteer / Selenium 的 CDP WebSocket URL。
client.list_zones()	列出活跃的 Bright Data 区域。
client.delete_zone(name)	移除一个区域。
client.test_connection()	验证 API 令牌是否有效。
client.get_account_info()	使用情况、配额、活跃区域。

如何处理请求

探索功能

如果用户想知道有哪些功能，或询问“能做什么？”，请介绍以下 8 个类别。每个类别都遵循以下模板：名称 — 功能 — 调用示例 — 适用场景。

1. 平台抓取 — 根据 URL 从 11 个受支持的平台提取结构化数据。client.scrape.<platform>.<method>(url=...)（平台：Amazon、LinkedIn、Facebook、Instagram、YouTube、TikTok、Reddit、ChatGPT、Perplexity、Pinterest、DigiKey）。适用于用户提供了受支持平台上的 URL，并想获取结构化字段（价格、个人资料数据、帖子互动等）的情况。

2. 平台搜索 — 按关键字、个人资料或筛选条件在特定平台内搜索。client.search.<platform>.<method>(...)。适用于“在 Amazon 上按关键字查找商品”“按主题标签查找 TikTok 视频”“查找关于食谱的 Pinterest Pin”等场景，也就是用户想在某个平台内搜索，但没有具体 URL。

3. 网页搜索（SERP） — 获取结构化搜索引擎结果（标题、链接、摘要、排名）。client.search.google(query=...)（或 .bing / .yandex）。适用于“在 Google 上搜索 X”“查找关于 Y 的网页／文章”“查询 Z 的新闻”等场景，也就是用户想要网页，而不是实体。

4. 发现（AI 驱动） — 使用 client.discover(query=..., intent=...)，根据自然语言条件查找符合条件的实体（公司、个人、商品、地点）。适用于“查找柏林的 AI 初创公司”“Acme Corp 的竞争对手”“曾在 Stripe 工作的人”“研究 SaaS 定价格局”等场景，也就是用户想要符合某项描述的实体列表，而不是网页。

5. 数据集 — 访问 310 多个预构建数据集，按需获取历史数据／海量数据。client.datasets.<name>(filter=...)（然后调用 .download(snapshot_id)）。适用于“批量获取 LinkedIn 公司数据”“获取电子产品的 Amazon 历史价格”“获取德克萨斯州的所有 Zillow 房源”等场景，也就是用户想一次获取大量记录，而不是单个页面上的实时数据。

6. 网页解锁器 — 抓取任意 URL，并绕过反机器人机制，适用于没有专用平台抓取器的网站。client.scrape_url(url=...)。适用于 URL 指向普通网站（没有专用抓取器），或平台抓取器返回 403／访问被拦截时的备用方案。

7. 浏览器 API — 通过 CDP（Chrome DevTools Protocol）连接远程浏览器，进行真实浏览器交互。client.browser.get_connect_url()（然后使用 Playwright／Puppeteer 连接）。适用于登录流程、JavaScript 密集型单页应用、点击／滚动／填写交互以及 CAPTCHA 等场景，也就是任何需要真实浏览器会话的情况。这是成本最高的选项；仅在较简单的方法无法完成任务时使用。

8. Scraper Studio — 运行在 Bright Data 控制面板中配置的预构建或自定义抓取模板。client.scraper_studio.run(collector="c_xxx", input={...})。适用于用户提供的采集器 ID 对应的模板未被平台抓取器覆盖的情况。

可提供帮助，加载与任一类别相关的参考文件以了解详情。

从特定 URL 提取数据

用户有一个 URL，并想从中提取结构化数据。

如果 URL 来自受支持的平台（Amazon、LinkedIn、Facebook、Instagram、YouTube、TikTok、Reddit、ChatGPT、Perplexity、Pinterest、DigiKey — 完整列表和可用方法见 references/scrapers.md）：

• 使用 client.scrape.<platform>.<method>(url=...)
• 查看 references/scrapers.md，了解各平台可用的方法

如果 URL 来自不受支持的平台或普通网站：

• 使用 client.scrape_url(url=...) 获取带反机器人绕过功能的原始页面数据
• 查看 references/advanced.md，了解网页解锁器选项

如果用户有多个 URL（批量处理）：

• 使用 BrightDataClient 和触发方法（_trigger 后缀），避免顺序执行造成阻塞
• 先触发所有任务，再使用 job.wait() 和 job.to_result() 收集结果
• 查看 references/advanced.md，了解批量执行模式

没有特定 URL 的研究或探索

用户想查找信息，但没有起始 URL。

对于网页搜索结果（链接、摘要、排名）：

• 使用 client.search.google(query=...)、client.search.bing(query=...) 或 client.search.yandex(query=...)
• 阅读 references/search.md，了解可用的搜索引擎和参数

对于特定平台的搜索（在 Amazon 上查找商品、在 LinkedIn 上查找个人资料、在 YouTube 上查找视频等）：

• 使用 client.search.<platform>.<method>(...)
• 阅读 references/scrapers.md——各个平台下列出了搜索方法

对于更深入的探索（查找符合条件的公司、人员或实体）：

• 使用 client.discover(query=..., intent=...)
• Discover API 需要意图短语，而不仅仅是关键词
• 阅读 references/search.md，了解 Discover API 的详情

批量或历史数据需求

用户请求“批量数据”“历史数据”“数据库”“列表”，或希望大规模获取数据，而不是逐个抓取页面。

• 在运行时使用 client.datasets.list() 查找可用的数据集
• 阅读 references/datasets-overview.md，了解数据集类别和使用模式
• 创建经过筛选的快照：snapshot_id = client.datasets.<name>(filter={...})
• 下载数据：data = client.datasets.<name>.download(snapshot_id)（默认格式为 jsonl；也支持 json、csv）
• 快照需要时间生成——下载操作会阻塞，直到快照就绪（最长 5 分钟）

多步骤研究工作流

用户有一个广泛的研究目标（例如“研究柏林的竞争对手”）。

步骤 1：查找来源

• 使用 client.discover(query=..., intent=...) 进行实体级探索
• 或使用 client.search.google(query=...) 获取网页搜索结果

步骤 2：从已发现的来源提取数据

• 对每个已发现的 URL 使用 client.scrape.<platform>.<method>(url=...)
• 如果 URL 很多，则使用触发方法进行批量处理

步骤 3：按需使用批量数据补充信息

• 检查 client.datasets，获取有关已发现实体的历史背景信息

交互式网页任务

用户需要登录、点击、滚动、填写表单或执行 JavaScript。

• 使用 client.browser.get_connect_url() 获取 CDP WebSocket URL
• 使用 Playwright、Puppeteer 或其他 CDP 客户端进行连接
• 这是成本最高的选项——仅在更简单的方法无法完成任务时使用
• 阅读 references/advanced.md，了解浏览器 API 的详情

Scraper Studio 模板

用户想使用预构建或自定义的抓取模板。

• 使用 client.scraper_studio.run(collector="c_xxx", input={...})
• 需要 collector ID——用户必须提供该 ID，或知道要使用哪个模板
• 阅读 references/advanced.md，了解 scraper studio 的详情

注意事项

Browser API 是最后的手段，而非默认选择

默认： 对于受支持平台上的页面（Amazon 商品、LinkedIn 个人资料、Instagram 帖子／Reels 等）→ 使用平台抓取工具。

覆盖规则： 用户明确提及以下任一操作 → 按要求使用 Browser API（它确实是合适的工具）： 登录、点击、滚动、填写、输入、执行 JavaScript、CAPTCHA、截图、生成 PDF、多步导航。

反向覆盖规则： 用户要求对不需要上述任何操作的页面使用 Browser API，且 URL 属于受支持的平台 → 不要照做。展示平台抓取工具代码，并说明成本／速度差异（约便宜 10 倍，约 30 秒，而非约 5 分钟）。

# WRONG (browser when scraper would do):
cdp_url = client.browser.get_connect_url()
browser = await playwright.chromium.connect_over_cdp(cdp_url)
page = await browser.new_page()
await page.goto("https://amazon.com/dp/B09V3KXJPB")
# ↑ scraper is ~10x cheaper, ~30s vs ~5min, returns structured data not raw HTML

# RIGHT (use the platform scraper):
result = await client.scrape.amazon.products(url="https://amazon.com/dp/B09V3KXJPB")

# RIGHT — legitimate browser-API case (the user mentions login):
# User said "log into Amazon and check my recent orders"
cdp_url = client.browser.get_connect_url(country="us")
browser = await playwright.chromium.connect_over_cdp(cdp_url)
page = await browser.new_page()
await page.goto("https://amazon.com/login")
await page.fill("#ap_email", username)
# ... etc — browser is the right tool here.

• 数据集返回的是历史数据，而非实时数据。如果用户需要当前数据，请改用平台抓取工具或 Web Unlocker。
• Discover API 需要提供意图（对要查找内容的自然语言描述），而不只是关键词。请将“restaurants”这类单独的关键词改写为意图短语，例如“查找奥斯汀市中心带户外座位的意大利餐厅”。
• 抓取工具返回 403 或遭到拦截时，请尝试使用 client.scrape_url()（Web Unlocker）作为备用方案——它可以处理反机器人保护。
• 始终优先选择满足需求且成本最低的服务。成本顺序（从低到高）：数据集 → SERP → 平台抓取工具 → Web Unlocker → Discover → Scraper Studio → Browser API。
• 始终将客户端用作上下文管理器。不要创建多个客户端实例——在一个会话的所有操作中复用同一个客户端。
• 每个抓取工具支持 3 种执行模式：快速（阻塞至结果返回）、触发（立即返回任务）、手动（触发 + 状态查询 + 获取）。除非用户需要批量处理或非阻塞执行，否则默认使用快速模式。
• 快速方法会阻塞数分钟，具体取决于平台和页面复杂度。不要设置较短的超时时间——SDK 默认值已按平台校准。大多数操作预计需要 2–10 分钟。
• SDK 会自动重试网络错误和超时（重试 3 次，采用指数退避）。不要再自行添加重试逻辑——这会导致重复重试并浪费 API 额度。
• 数据集操作返回的是 snapshot_id，而非数据本身。快照会经历以下生命周期：scheduled → building → ready。使用 .download(snapshot_id)，该方法会一直阻塞到快照就绪。支持的下载格式：json、jsonl、csv。

批量操作（多个 URL）时，使用触发模式

原因： 快速方法（例如 client.scrape.amazon.products）会阻塞 2–10 分钟，等待抓取完成。即使默认速率限制为 10 req/s，200 次快速调用的 asyncio.gather 也会导致 200 × 约 5 分钟 / 10（速率限制）= 约 100 分钟的阻塞执行时间。触发模式会发起请求并返回任务；结果就绪后，你可以并行收集。

# WRONG (anti-pattern, even with rate_limit respected):
results = await asyncio.gather(*[
    client.scrape.amazon.products(url=u) for u in urls
])  # ↑ each call blocks ~5min; total ~100min for 200 URLs

# RIGHT (trigger pattern):
jobs = [await client.scrape.amazon.products_trigger(url=u) for u in urls]
for job in jobs:
    await job.wait(timeout=600)
results = [await job.to_result() for job in jobs]
# ↑ total time ≈ longest single scrape ≈ 5-10 min, regardless of N

速率限制（默认 10 req/s）会让触发请求依次发出；并行处理发生在等待阶段，此阶段只进行状态轮询，成本很低。不要使用 asyncio.gather 并行发起触发请求，否则会触发速率限制。

• 在同步环境（脚本、笔记本、Claude Code）中，使用 SyncBrightDataClient。在异步环境中，使用 BrightDataClient。两者使用相同的方法名称——唯一的区别是异步调用需要 await。不要在 SyncBrightDataClient 中使用带 _sync 后缀的方法。注意：同步客户端支持的平台有限。同步抓取支持：Amazon、LinkedIn、Instagram、Facebook、ChatGPT、Pinterest。同步搜索支持：Google、Bing、Yandex、Amazon、LinkedIn、Instagram、ChatGPT、Pinterest。对于 TikTok、YouTube、Reddit、Perplexity、DigiKey 抓取工具／搜索，以及数据集 API，请使用异步客户端。
• 平台搜索方法（例如 client.search.amazon.products()）与平台抓取工具（例如 client.scrape.amazon.products()）不同。搜索会按关键词查找内容；抓取则会从特定 URL 提取数据。

示例

“获取这个 Amazon 产品的评价”

使用 client.scrape.amazon.reviews(url="<the_url>")。 返回结构化的评价数据：评分、文本、日期、评价者姓名。 快速方法 — 会阻塞，直到任务完成（最长约 4 分钟）。

“查找柏林的 AI 初创公司”

步骤 1：client.discover(query="AI startups in Berlin", intent="find technology companies") 返回符合条件的实体列表，其中包含 URL 和元数据。

步骤 2：对于带有 URL 的每条结果，可选择抓取更深入的数据： client.scrape.linkedin.companies(url=...) 或 client.scrape_url(url=...)。

“我需要电子产品的历史价格数据”

步骤 1：使用 client.datasets.list() 查找相关数据集。

步骤 2：创建经过筛选的快照： snapshot_id = client.datasets.amazon_products(filter={"name": "category", "operator": "=", "value": "Electronics"}, records_limit=1000)

步骤 3：下载数据： data = client.datasets.amazon_products.download(snapshot_id)

注意：快照生成期间，下载操作会阻塞（最长 5 分钟）。默认格式为 jsonl（也支持 json、csv）。这是历史/批量数据，不是实时价格。返回记录列表。

故障排除

• 401 Unauthorized：API 令牌无效或已过期。请检查传递给客户端构造函数的令牌。
• 403 Forbidden / Blocked：目标网站拦截了请求。请尝试使用 client.scrape_url()（Web Unlocker）作为备用方案，或使用其他抓取方法。
• 超时：不要降低超时时间，应当延长。某些操作需要几分钟。针对特定平台的默认值已经过优化。
• “Dataset not found”：使用 client.datasets.list() 查看可用数据集。数据集属性名称采用 snake_case（例如，amazon_products、linkedin_profiles）。
• 沙盒环境中的 SSL/代理错误：在客户端构造函数中传入 ssl_verify=False 以跳过 SSL 验证，或使用 ssl_ca_cert='/path/to/cert.pem' 自定义证书处理。
• 速率限制错误：降低并发量。默认限制为每秒 10 个请求。请使用顺序调用或触发方法进行批量处理。

何时加载参考资料

• 当用户提到 Amazon、LinkedIn、Facebook、Instagram、YouTube、TikTok、Reddit、ChatGPT、Perplexity、Pinterest、DigiKey 或其他特定平台时，请阅读 references/scrapers.md，了解该平台可用的抓取方法、搜索方法和参数。
• 当用户未提及特定平台，却要求 “查找”“搜索”“发现”“研究”“查询” 某项内容时，请阅读 references/search.md，了解 SERP 引擎和 Discover API 选项。
• 当用户要求 “批量数据”“历史数据”“数据库”“列表”“数据集” 或需要大规模数据时，请阅读 references/datasets-overview.md，了解数据集类别以及如何在运行时发现特定数据集。
• 当用户需要 批量处理多个 URL、非阻塞执行、浏览器自动化、JavaScript 执行、登录/会话处理、自定义抓取模板，或简单方法已失败 时，请阅读 references/advanced.md，了解执行模式、批处理工作流、Web Unlocker、Browser API 和 Scraper Studio 的详情。