pip install brightdata-sdk

Bright Data 推出的 Python SDK，提供易用且可扩展的方法用于网页搜索与爬取

功能特性

• 通过 Bright Data Web Unlocker API 配合代理进行网站爬取
• 使用 Bright Data SERP API 执行网页搜索
• 支持多个搜索引擎：Google、Bing、Yandex
• 并行处理：同时处理多个 URL 或查询
• 强健的错误处理：完善的重试与异常处理机制
• 区域（Zone）管理：自动创建与管理 Zone
• 多种输出格式：JSON、原始 HTML、Markdown 等

安装

在终端中安装：

pip install brightdata-sdk

若使用 macOS，建议先为项目创建并启用虚拟环境

快速开始

创建一个 Bright Data 账号并复制你的 API Key

1. 初始化客户端

from brightdata import bdclient

client = bdclient(api_token="your_api_token_here") # 也可在 .env 文件中设置 BRIGHTDATA_API_TOKEN

或配置自定义的 Zone 名称

client = bdclient(
    api_token="your_token",
    auto_create_zones=False,          # 否则会自动创建 Zone
    web_unlocker_zone="custom_zone",
    serp_zone="custom_serp_zone"
)

2. 搜索引擎结果

# 单个搜索查询
result = client.search("pizza restaurants")

# 多个查询（并行处理）
queries = ["pizza", "restaurants", "delivery"]
results = client.search(queries)

# 指定不同的搜索引擎
result = client.search("pizza", search_engine="google") # 也可设置为 "yandex" 或 "bing"

# 自定义参数
results = client.search(
    ["pizza", "sushi"],
    country="gb",
    format="raw"
)

Tip

将鼠标悬停在包中的 "search" 或其他函数上，可查看其全部可用参数。

3. 爬取网站

# 单个 URL
result = client.scrape("https://example.com")

# 多个 URL（并行处理）
urls = ["https://example1.com", "https://example2.com", "https://example3.com"]
results = client.scrape(urls)

# 自定义参数
result = client.scrape(
    "https://example.com",
    format="raw",
    country="gb",
    data_format="screenshot"
)

4. 下载内容

# 下载已爬取的内容
data = client.scrape("https://example.com")
client.download_content(data) 

函数参数

🔍 Search(...)

使用 SERP API 进行搜索。接受与 scrape() 相同的参数，另外包含：

- `query`: 字符串或字符串列表形式的搜索查询
- `search_engine`: "google"、"bing" 或 "yandex"
- 其他参数同 scrape()

🔗 scrape(...)

使用 Web Unlocker 爬取单个 URL 或 URL 列表。

- `url`: 单个 URL 字符串或 URL 字符串列表
- `zone`: Zone 标识（若为 None 则自动配置）
- `format`: "json" 或 "raw"
- `method`: HTTP 方法
- `country`: 两位国家代码
- `data_format`: "markdown"、"screenshot" 等
- `async_request`: 启用异步处理
- `max_workers`: 最大并行工作线程（默认：10）
- `timeout`: 请求超时时间（秒，默认：30）

💾 Download_Content(...)

将内容保存到本地文件。

- `content`: 要保存的内容
- `filename`: 输出文件名（若为 None 将自动生成）
- `format`: 文件格式（"json"、"csv"、"txt" 等）

⚙️ 配置常量

常量	默认值	描述
DEFAULT_MAX_WORKERS	10	最大并行任务数
DEFAULT_TIMEOUT	30	请求超时（秒）
CONNECTION_POOL_SIZE	20	最大并发 HTTP 连接数
MAX_RETRIES	3	失败时的重试次数
RETRY_BACKOFF_FACTOR	1.5	指数退避倍数

高级配置

🔧 环境变量

在项目根目录创建 .env 文件：

BRIGHTDATA_API_TOKEN=your_bright_data_api_token
WEB_UNLOCKER_ZONE=your_web_unlocker_zone  # 可选
SERP_ZONE=your_serp_zone                  # 可选

🌐 管理 Zones

列出所有活动的 Zone

# 列出所有活动的 Zone
zones = client.list_zones()
print(f"Found {len(zones)} zones")

👥 客户端管理

bdclient 类

bdclient(
    api_token: str = None,
    auto_create_zones: bool = True,
    web_unlocker_zone: str = None,
    serp_zone: str = None,
)

⚠️ 错误处理

bdclient 类

SDK 内置输入校验与重试机制。

若遇到 Zone 相关问题，可使用 list_zones() 查看你的活动 Zone，并在你的账号设置中确认你的 API Key 拥有管理员权限（admin permissions）。

支持

如有任何问题，请联系 Bright Data 支持，或在本仓库提交 issue。