bright-data-best-practices

CLI 设置参考

Bright Data CLI（bdata）的安装、身份验证和故障排除文档集中在一个权威位置：

→ references/cli-setup.md

在执行任何会调用 bdata 的任务前，请先查阅该文档。

Bright Data API

Bright Data 提供大规模网页数据提取基础设施。四种主要 API 适用于不同的用例，请始终为任务选择最具体的工具。

选择合适的 API

用例	API	原因
按 URL 抓取任意网页（无需交互）	Web Unlocker	基于 HTTP，自动绕过机器人检测，成本最低
Google / Bing / Yandex 搜索结果	SERP API	专用于 SERP 提取，可返回结构化数据
从 Amazon、LinkedIn、Instagram、TikTok 等获取结构化数据	Web Scraper API	内置抓取器，无需解析
点击、滚动、填写表单、运行 JS、拦截 XHR	Browser API	完整的浏览器自动化
Puppeteer / Playwright / Selenium 自动化	Browser API	通过 CDP/WebDriver 连接
通过原始代理（DC/ISP/Residential/Mobile）路由自己的 HTTP 客户端	代理网络	当你需要使用自己的请求逻辑直接访问代理，而不是使用托管 API 时，请参阅 proxy.md 技能

身份验证模式（所有 API）

所有 API 使用相同的身份验证模式。以下环境变量适用于直接 REST API 集成；如果使用 bdata CLI，bdata login 会自动处理所有这些内容（请参阅 references/cli-setup.md）。

export BRIGHTDATA_API_KEY="your-api-key"         # From Control Panel > Account Settings
export BRIGHTDATA_UNLOCKER_ZONE="zone-name"       # Web Unlocker zone name
export BRIGHTDATA_SERP_ZONE="serp-zone-name"      # SERP API zone name
export BROWSER_AUTH="brd-customer-ID-zone-NAME:PASSWORD"  # Browser API credentials

Web Unlocker 和 SERP API 的 REST API 身份验证标头：

Authorization: Bearer YOUR_API_KEY

---

Web Unlocker API

基于 HTTP 的抓取代理。最适合无需浏览器交互的简单页面获取。

端点： POST https://api.brightdata.com/request

import requests

response = requests.post(
    "https://api.brightdata.com/request",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "zone": "YOUR_ZONE_NAME",
        "url": "https://example.com/product/123",
        "format": "raw"
    }
)
html = response.text

关键参数

参数	类型	说明
zone	string	Zone 名称（必填）
url	string	目标 URL，需包含 http:// 或 https://（必填）
format	string	"raw"（HTML）或 "json"（结构化封装）（必填）
method	string	HTTP 方法，默认为 "GET"
country	string	用于地理定位的 2 字母 ISO 国家代码（例如 "us"、"de"）
data_format	string	转换格式："markdown" 或 "screenshot"
async	boolean	true 表示异步模式

快速示例

# Get markdown (best for LLM input)
response = requests.post(
    "https://api.brightdata.com/request",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"zone": ZONE, "url": url, "format": "raw", "data_format": "markdown"}
)

# Geo-targeted request
json={"zone": ZONE, "url": url, "format": "raw", "country": "de"}

# Screenshot for debugging
json={"zone": ZONE, "url": url, "format": "raw", "data_format": "screenshot"}

# Async for bulk processing
json={"zone": ZONE, "url": url, "format": "raw", "async": True}

重要规则： 绝不能将 Web Unlocker 与 Puppeteer、Playwright、Selenium 或反检测浏览器搭配使用。请改用 Browser API。

完整参考（包括代理接口、特殊标头、异步流程、功能和计费）请参阅 references/web-unlocker.md。

---

SERP API

用于提取 Google、Bing、Yandex 和 DuckDuckGo 搜索引擎的结构化结果。

端点： POST https://api.brightdata.com/request（与 Web Unlocker 相同）

response = requests.post(
    "https://api.brightdata.com/request",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "zone": "YOUR_SERP_ZONE",
        "url": "https://www.google.com/search?q=python+web+scraping&brd_json=1&gl=us&hl=en",
        "format": "raw"
    }
)
data = response.json()
for result in data.get("organic", []):
    print(result["rank"], result["title"], result["link"])

Google URL 必要参数

参数	说明	示例
q	搜索查询	q=python+web+scraping
brd_json	解析后的 JSON 输出	brd_json=1（数据管道中始终使用）
gl	搜索国家/地区	gl=us
hl	语言	hl=en
start	分页偏移量	start=10（第 2 页），start=20（第 3 页）
tbm	搜索类型	tbm=nws（新闻）、tbm=isch（图片）、tbm=vid（视频）
brd_mobile	设备	brd_mobile=1（移动设备）、brd_mobile=ios
brd_browser	浏览器	brd_browser=chrome
brd_ai_overview	触发 AI Overview	brd_ai_overview=2
uule	编码后的地理位置	用于精确的位置定位

注意： num 参数自 2025 年 9 月起已弃用。请使用 start 进行分页。

已解析的 JSON 响应结构

{
  "organic": [{"rank": 1, "global_rank": 1, "title": "...", "link": "...", "description": "..."}],
  "paid": [],
  "people_also_ask": [],
  "knowledge_graph": {},
  "related_searches": [],
  "general": {"results_cnt": 1240000000, "query": "..."}
}

Bing 关键参数

参数	描述
q	搜索查询
setLang	语言（建议使用 4 字母格式：en-US）
cc	国家代码
first	分页（每次递增 10：1、11、21……）
safesearch	off、moderate、strict
brd_mobile	设备类型

用于批量 SERP 的异步请求

# Submit
response = requests.post(
    "https://api.brightdata.com/request",
    params={"async": "1"},
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"zone": SERP_ZONE, "url": "https://www.google.com/search?q=test&brd_json=1", "format": "raw"}
)
response_id = response.headers.get("x-response-id")

# Retrieve (retrieve calls are NOT billed)
result = requests.get(
    "https://api.brightdata.com/serp/get_result",
    params={"response_id": response_id},
    headers={"Authorization": f"Bearer {API_KEY}"}
)

**计费：**仅对每 1,000 次成功请求收费。异步检索调用不计费。

完整参考文档（包括 Maps、Trends、Reviews、Lens、Hotels、Flights 参数）请参阅 references/serp-api.md。

---

Web Scraper API

提供适用于 100 多个平台的预构建抓取工具，用于提取结构化数据。无需编写解析逻辑。

同步端点： POST https://api.brightdata.com/datasets/v3/scrape 异步端点： POST https://api.brightdata.com/datasets/v3/trigger

# Sync (up to 20 URLs, returns immediately)
response = requests.post(
    "https://api.brightdata.com/datasets/v3/scrape",
    params={"dataset_id": "YOUR_DATASET_ID", "format": "json"},
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"input": [{"url": "https://www.amazon.com/dp/B09X7M8TBQ"}]}
)

if response.status_code == 200:
    data = response.json()  # Results ready
elif response.status_code == 202:
    snapshot_id = response.json()["snapshot_id"]  # Poll for completion

参数

参数	类型	描述
dataset_id	string	Scraper Library 中的抓取工具标识符（必填）
format	string	json（默认）、ndjson、jsonl、csv
custom_output_fields	string	以竖线分隔的字段：url|title|price
include_errors	boolean	在结果中包含错误信息

请求正文

{
  "input": [
    { "url": "https://www.amazon.com/dp/B09X7M8TBQ" },
    { "url": "https://www.amazon.com/dp/B0B7CTCPKN" }
  ]
}

轮询异步结果

import time

# Trigger
snapshot_id = requests.post(
    "https://api.brightdata.com/datasets/v3/trigger",
    params={"dataset_id": DATASET_ID, "format": "json"},
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"input": [{"url": u} for u in urls]}
).json()["snapshot_id"]

# Poll
while True:
    status = requests.get(
        f"https://api.brightdata.com/datasets/v3/progress/{snapshot_id}",
        headers={"Authorization": f"Bearer {API_KEY}"}
    ).json()["status"]

    if status == "ready": break
    if status == "failed": raise Exception("Job failed")
    time.sleep(10)

# Download
data = requests.get(
    f"https://api.brightdata.com/datasets/v3/snapshot/{snapshot_id}",
    params={"format": "json"},
    headers={"Authorization": f"Bearer {API_KEY}"}
).json()

进度状态值： starting → running → ready | failed **数据保留期限：**30 天。 **计费：**按交付的记录计费。无效且抓取失败的输入 URL 仍会计费。

完整参考文档（包括抓取工具类型、输出格式、交付选项和计费详情）请参阅 references/web-scraper-api.md。

---

Browser API（Scraping Browser）

通过 CDP/WebDriver 实现完整的浏览器自动化。自动处理 CAPTCHA、指纹识别和反机器人检测。

连接方式：

• Playwright/Puppeteer：wss://${AUTH}@brd.superproxy.io:9222
• Selenium：https://${AUTH}@brd.superproxy.io:9515

const { chromium } = require("playwright-core");

const AUTH = process.env.BROWSER_AUTH;
const browser = await chromium.connectOverCDP(`wss://${AUTH}@brd.superproxy.io:9222`);
const page = await browser.newPage();
page.setDefaultNavigationTimeout(120000); // Always set to 2 minutes

await page.goto("https://example.com", { waitUntil: "domcontentloaded" });
const html = await page.content();
await browser.close();

from playwright.async_api import async_playwright

async with async_playwright() as p:
    browser = await p.chromium.connect_over_cdp(f"wss://{AUTH}@brd.superproxy.io:9222")
    page = await browser.new_page()
    page.set_default_navigation_timeout(120000)
    await page.goto("https://example.com", wait_until="domcontentloaded")
    html = await page.content()
    await browser.close()

自定义 CDP 函数

函数	用途
Captcha.solve	手动触发 CAPTCHA 求解
Captcha.setAutoSolve	启用/禁用 CAPTCHA 自动求解
Proxy.setLocation	设置精确地理位置（在调用 goto 之前调用）
Proxy.useSession	在多个会话中保持相同 IP
Emulation.setDevice	应用设备配置文件（iPhone 14 等）
Emulation.getSupportedDevices	列出可用的设备配置文件
Unblocker.enableAdBlock	屏蔽广告以节省带宽
Unblocker.disableAdBlock	重新启用广告
Input.type	快速输入文本，适用于批量填写表单
Browser.addCertificate	为会话安装客户端 SSL 证书
Page.inspect	获取实时会话的 DevTools 调试 URL

// CDP session pattern for custom functions
const client = await page.target().createCDPSession();

// CAPTCHA solve with timeout
const result = await client.send("Captcha.solve", { timeout: 30000 });

// Precise geo location (must be before goto)
await client.send("Proxy.setLocation", {
  latitude: 37.7749,
  longitude: -122.4194,
  distance: 10,
  strict: true
});

// Block unnecessary resources
await client.send("Network.setBlockedURLs", { urls: ["*google-analytics*", "*.ads.*"] });

// Device emulation
await client.send("Emulation.setDevice", { deviceName: "iPhone 14" });

会话规则

• 每个会话仅允许一次初始导航 — 新 URL = 新会话
• **空闲超时：**5 分钟
• **最长持续时间：**30 分钟

地理位置

• 国家级：在凭据用户名后追加 -country-us
• 欧盟范围：追加 -country-eu（通过 29 个以上欧洲国家路由）
• 精确位置：使用 Proxy.setLocation CDP 命令（在导航之前）

错误代码

代码	问题	解决方法
407	端口错误	Playwright/Puppeteer → 9222，Selenium → 9515
403	身份验证错误	检查凭据格式和区域类型
503	服务扩容中	等待 1 分钟后重新连接

**计费：**仅按流量计费。屏蔽图片、CSS 和字体以降低成本。

完整参考文档（包括所有 CDP 函数、带宽优化、CAPTCHA 模式和调试）请参阅 references/browser-api.md。

---

详细参考资料

• references/web-unlocker.md — Web Unlocker：完整参数列表、代理接口、特殊标头、异步流程、功能、计费、反模式
• references/serp-api.md — SERP API：所有 Google 参数（Maps、Trends、Reviews、Lens、Hotels、Flights）、Bing 参数、解析后的 JSON 结构、异步处理、计费
• references/web-scraper-api.md — Web Scraper API：同步与异步、所有参数、轮询、抓取器类型、输出格式、计费
• references/browser-api.md — Browser API：连接字符串、会话规则、所有 CDP 函数、地理定位、带宽优化、CAPTCHA、调试、错误代码

相关技能

• brightdata-proxy — 使用你自己的 HTTP 客户端，而不是托管 API，通过 Bright Data 的原始代理网络（Datacenter、ISP、Residential、Mobile）路由请求。涵盖网络/IP 池选择、brd-customer-... 用户名格式、定向和粘性会话参数、Residential/Mobile 的 SSL CA 设置，以及 cURL、Python（requests/httpx/aiohttp/Scrapy）、Node（fetch/axios）、Playwright、Puppeteer 和 Selenium 集成。当任务需要访问原始代理，而非使用 Web Unlocker / SERP / Web Scraper / Browser API 时，请转交给它。代理持续遭到拦截时的升级顺序：原始代理 → Web Unlocker → Browser API → Web Scraper API。