@brightdata/sdk

亮相 Data JavaScript SDK 为刮取,网络搜索,数据集等提供简单可扩展的方法.

安装

npm install @brightdata/sdk

快开始

1. 联合国. 注册 获取您的 API 令牌

2. 初始化客户

import { bdclient } from '@brightdata/sdk';

const client = new bdclient({
    apiKey: '[your_api_token]', // or set BRIGHTDATA_API_TOKEN env variable
});

3. 发出你的第一个请求

// Scrape a webpage
const html = await client.scrapeUrl('https://example.com');
console.log(html);

// Search the web
const results = await client.search.google('pizza restaurants', { country: 'us' });
console.log(results);

不要忘记关闭 当完成:

await client.close();

特征

• 网络搜索 ——使用反机器人检测绕行和代理支持来搜索任何网站
• 搜索引擎结果 ——Google, Bing, 有批量支持的Yandex搜索
• 平台缓冲器 - 从LinkedIn、Amazon、Instagram、TikTok、YouTube、Reddit等机构收集结构化数据
• 爬行 API —— 抓取任意 URL并获得每页捆绑的每个输出格式( 标记下, HTML, 文本)
• 发现 API ——AI驱动的网络搜索,并基于意图的关联性排名
• 史克威尔工作室 – Bright Data's Scraper Studio所建自定义刮取器的触发并获取结果
• 浏览器 API – CDP WebSocket URL 用于连接 Playwright, Puppeteer, 或 Selenium 到 Bright Data 的云浏览器
• 数据集 ——通过数十个平台访问126个预建数据集,提供查询/下载支持
• 并行处理 ——同时处理多个URL或查询
• 强力错误处理 —— 有重试逻辑的打出错误类
• 区管理 自动区创建和管理
• 多个输出格式 HTML、JSON、Markdown和截图
• 双重构建 ——支持无害环境管理和共同JS
• 类型脚本 ——满打的API有超载签名
• 子路径导出 - 树木可移动进口 @brightdata/sdk/scrapers, (中文(简体) ), @brightdata/sdk/search, (中文(简体) ), @brightdata/sdk/datasets

使用量

拼接网站

// Single URL — returns HTML string by default
const html = await client.scrapeUrl('https://example.com');

// Multiple URLs (parallel processing)
const results = await client.scrapeUrl([
    'https://example1.com',
    'https://example2.com',
]);

// Get markdown content
const md = await client.scrapeUrl('https://example.com', {
    dataFormat: 'markdown',
});

// Get structured JSON
const data = await client.scrapeUrl('https://example.com', {
    format: 'json',
});

// Take a screenshot
const screenshot = await client.scrapeUrl('https://example.com', {
    dataFormat: 'screenshot',
});

// Full options
const result = await client.scrapeUrl('https://example.com', {
    format: 'raw',            // 'raw' (default) or 'json'
    dataFormat: 'html',       // 'html' (default), 'markdown' (alias: 'md'), 'screenshot'
    country: 'gb',            // two-letter country code
    method: 'GET',            // HTTP method
});

搜索引擎

// Google search
const results = await client.search.google('pizza restaurants');

// Bing search
const results = await client.search.bing('pizza restaurants');

// Yandex search
const results = await client.search.yandex('pizza restaurants');

// Batch search (parallel)
const results = await client.search.google(['pizza', 'sushi', 'tacos']);

// With options
const results = await client.search.google('pizza', {
    country: 'gb',
    format: 'json',
});

说明: 若为 country 未指定,请求通过任意 代理位置,所以结果可能是地理定位到一个出乎意料的国家. 总是通过 country 当你需要一致的,局部的结果.

平台拆卸机

从流行平台收集结构化数据. 每个平台都支持同步收藏( E)collect*)和aync策划的刮去(触发,民意调查,下载).

// LinkedIn profiles
const data = await client.scrape.linkedin.collectProfiles(
    ['https://www.linkedin.com/in/satyanadella/'],
    { format: 'json' },
);

// Amazon products
const data = await client.scrape.amazon.collectProducts(
    ['https://www.amazon.com/dp/B0D77BX8Y4'],
    { format: 'json' },
);

// Instagram profiles
const data = await client.scrape.instagram.collectProfiles(
    ['https://www.instagram.com/natgeo/'],
    { format: 'json' },
);

// TikTok profiles
const data = await client.scrape.tiktok.collectProfiles(
    ['https://www.tiktok.com/@tiktok'],
    { format: 'json' },
);

// YouTube videos
const data = await client.scrape.youtube.collectVideos(
    ['https://www.youtube.com/watch?v=dQw4w9WgXcQ'],
    { format: 'json' },
);

// Reddit posts
const data = await client.scrape.reddit.collectPosts(
    ['https://www.reddit.com/r/technology/top/'],
    { format: 'json' },
);

乐器刮刮 (同步触发 民调 下载):

const result = await client.scrape.linkedin.profiles(
    ['https://www.linkedin.com/in/satyanadella/'],
    { pollInterval: 5000, pollTimeout: 180_000 },
);
console.log(result.data);    // structured data
console.log(result.status);  // 'ready'
console.log(result.rowCount);

可用的平台 : linkedin, (中文(简体) ), amazon, (中文(简体) ), instagram, (中文(简体) ), tiktok, (中文(简体) ), youtube, (中文(简体) ), reddit, (中文(简体) ), facebook, (中文(简体) ), pinterest, (中文(简体) ), chatGPT, (中文(简体) ), digikey, (中文(简体) ), perplexity

爬行 API

抓取一个或多个 URL 并获得每页捆绑的每个输出格式(markdown, HTML, text).

// Sync — single round-trip
const result = await client.crawler.crawl('https://example.com');
console.log(result.data[0].markdown);

// Batch
const result = await client.crawler.crawl([
    'https://example.com',
    'https://example.com/about',
]);
console.log(`${result.pageCount} pages`);

// Async — trigger, poll, download
const job = await client.crawler.trigger('https://example.com');
const status = await client.crawler.status(job.snapshotId);
const result = await client.crawler.download(job.snapshotId);

发现 API

AI驱动的网络搜索,根据意图进行关联性排名.

discover() 决定: DiscoverResult 包装( 不是赤色阵列) 。 项目 开始 result.data (或其别名) result.results结果确是永恒的. 失败时 result.success 实值 false, (中文(简体) ), result.error 带着理由,和 result.data 编号 : result.results 保留一个空阵列——所以不丢.

// Basic search
const result = await client.discover('artificial intelligence trends 2026');

if (!result.success) {
    console.error('discover failed:', result.error);
} else {
    console.log(result.results); // [{ link, title, description, relevance_score }, ...]
    for (const item of result) {
        console.log(`[${item.relevance_score}] ${item.title}`);
    }
}

// With intent for semantic ranking
const result = await client.discover('Tesla battery technology', {
    intent: 'recent breakthroughs in EV battery chemistry',
});

// With filtering and localization
const result = await client.discover('sustainable fashion brands', {
    intent: 'eco-friendly clothing companies',
    filterKeywords: ['sustainability', 'eco-friendly', 'organic'],
    country: 'us',
    numResults: 10,
});

// Include full page content
const result = await client.discover('python asyncio tutorial', {
    includeContent: true,
    numResults: 3,
});

// Manual trigger/poll/fetch
const job = await client.discoverTrigger('market research SaaS', {
    intent: 'competitor pricing strategies',
});
await job.wait({ timeout: 60_000 });
const data = await job.fetch();

史克威尔工作室

触发并获取您自定义的剪贴机所建 史克威尔工作室。 。 。 .

// Orchestrated — trigger + poll + return results
const results = await client.scraperStudio.run('c_your_collector_id', {
    input: { url: 'https://example.com/product/1' },
});
// results: RunResult[] — one per input with { input, data, error, responseId, elapsedMs }

// Multiple inputs (processed sequentially)
const results = await client.scraperStudio.run('c_your_collector_id', {
    input: [
        { url: 'https://example.com/product/1' },
        { url: 'https://example.com/product/2' },
    ],
});

// Manual control — trigger, then poll yourself
const job = await client.scraperStudio.trigger('c_your_collector_id', {
    url: 'https://example.com/product/1',
});
const data = await job.waitAndFetch();

// Check job status (by job ID from the dashboard)
const status = await client.scraperStudio.status('j_abc123');
console.log(status.status); // 'queued' | 'running' | 'done' | 'failed'

浏览器 API

构建 CDP WebSocket URL,用于连接 Playwright, Puppeteer, 或 Selenium 到Bright Data 的云浏览器. 全权证书来自 browserUsername编号 :browserPassword 选项或 BRIGHTDATA_BROWSERAPI_USERNAME编号 :BRIGHTDATA_BROWSERAPI_PASSWORD (原始内容存档于2018-10-21). env vars.

// Get a connection URL
const url = client.browser.getConnectUrl();

// Geo-target the browser with a 2-letter country code
const usUrl = client.browser.getConnectUrl({ country: 'us' });

// Connect with Playwright
import { chromium } from 'playwright';
const browser = await chromium.connectOverCDP(url);
const page = await browser.newPage();
await page.goto('https://example.com');
const html = await page.content();
await browser.close();

数据集

访问126个预建数据集,用于查询和下载结构化数据快照.

const ds = client.datasets;

// List all datasets available on your account
const list = await ds.list();

// Get field metadata for a dataset
const meta = await ds.instagramProfiles.getMetadata();
console.log(meta.fields); // [{ name, type, description }, ...]

// Query a dataset (triggers a snapshot)
const snapshotId = await ds.instagramProfiles.query(
    { url: 'https://www.instagram.com/natgeo/' },
    { records_limit: 10 },
);

// Check snapshot status
const status = await ds.instagramProfiles.getStatus(snapshotId);
console.log(status.status); // 'running' | 'ready' | ...

// Download when ready
const rows = await ds.instagramProfiles.download(snapshotId);

可用的数据集 :

保存结果

const data = await client.scrapeUrl('https://example.com');
const filePath = await client.saveResults(data, {
    filename: 'results.json',
    format: 'json',
});
console.log(`Saved to: ${filePath}`);

配置

运行时间支持

Node.js (QQ 20) 是支持和测试的运行时间. SDK也在Bun下方运行,没有崩溃,但有一个真正的警告:Bun被捆绑了 undici 只能提供裸骨 Agent (无) compose(),没有 close(),没有自定义 dispatch),和"邦"(Bun's) request()编号 :stream() 忽略 dispatcher 选项全部,通过 Bun 自己的本地 HTTP 客户端进行路由。 在实践中,这意味着请求在Bun下仍然成功,但运输的调子——连接集成、留守、自定义超时、自动重试429/500/502/503/504和DNS缓存——在这方面没有任何效果; Bun本身的默认适用。 SDK自动检测缺失的能力(从未崩溃构造或 close()而不是失败.

API 托肯语Name

获取您的 API 令牌 亮相数据控制面板。 。 。 .

已经登录到CLI了? SDK没有配置. 如果你已经跑 brightdata login 与 亮数据 CLI,SDK自动取出那些存储的证书. 符号按此顺序解决:

1. apiKey 转至 new bdclient({ apiKey })
2. BRIGHTDATA_API_TOKEN (或 BRIGHTDATA_API_KEY() 环境变量
3. 由CLI存储的证书(brightdata login(中文(简体) )

如果没有找到,客户端会投放带有登录或设置符号的指示.

环境变量

BRIGHTDATA_API_TOKEN=your_api_token                  # BRIGHTDATA_API_KEY also accepted
BRIGHTDATA_WEB_UNLOCKER_ZONE=your_web_unlocker_zone  # Optional
BRIGHTDATA_SERP_ZONE=your_serp_zone                  # Optional
BRIGHTDATA_BROWSERAPI_USERNAME=your_browser_username # Optional, for Browser API
BRIGHTDATA_BROWSERAPI_PASSWORD=your_browser_password # Optional, for Browser API
BRIGHTDATA_VERBOSE=1                                  # Optional, enable verbose logging

提示 : 从 a 装入时 .env 文件为 node --env-file=.env, (中文(简体) ), 请注意,您 shell 中已经设定的变量优先于文件.

客户选项

const client = new bdclient({
    apiKey: 'string',           // API token (or use BRIGHTDATA_API_TOKEN env var)
    timeout: 120000,            // Request timeout in ms (1000–300000)
    autoCreateZones: true,      // Auto-create zones if they don't exist
    webUnlockerZone: 'string',  // Custom web unlocker zone name
    serpZone: 'string',         // Custom SERP zone name
    logLevel: 'INFO',           // 'DEBUG' | 'INFO' | 'WARNING' | 'ERROR' | 'CRITICAL'
    structuredLogging: true,    // Use structured JSON logging
    verbose: false,             // Enable verbose logging
    rateLimit: 0,               // Max requests per period (0 = unlimited)
    ratePeriod: 1000,           // Rate limit period in ms
});

资源清理

客户端维持了HTTP连接. 完成时总是关闭 :

await client.close();

// Or use Symbol.asyncDispose (TypeScript 5.2+)
await using client = new bdclient();

常数

区管理

const zones = await client.listZones();
console.log(`Found ${zones.length} zones`);

子路径导出

仅用于摇树或导入所需:

import { ScrapeRouter, LinkedinAPI } from '@brightdata/sdk/scrapers';
import { SearchRouter } from '@brightdata/sdk/search';
import { DatasetsClient, BaseDataset } from '@brightdata/sdk/datasets';

处理错误

SDK 导出扩展的打出错误类别 BRDError数字 :

import { bdclient, ValidationError, AuthenticationError, BRDError } from '@brightdata/sdk';

try {
    const result = await client.scrapeUrl('https://example.com');
} catch (error) {
    if (error instanceof ValidationError) {
        console.error('Invalid input:', error.message);
    } else if (error instanceof AuthenticationError) {
        console.error('Auth failed:', error.message);
    } else if (error instanceof BRDError) {
        console.error('SDK error:', error.message);
    }
}

错误类型 : ValidationError, (中文(简体) ), AuthenticationError, (中文(简体) ), ZoneError, (中文(简体) ), NetworkError, (中文(简体) ), NetworkTimeoutError, (中文(简体) ), TimeoutError, (中文(简体) ), APIError, (中文(简体) ), DataNotReadyError, (中文(简体) ), FSError

解决问题

视窗和公司网络

认证错误: 无效的 API 密钥

如果您得到此错误, 请检查以下顺序 :

1. 验证标志本身 工作,在SDK之外:

   curl -H "Authorization: Bearer YOUR_TOKEN" https://api.brightdata.com/zone/get_active_zones
   

   如果失败, 将生成一个新的 API 密钥 管理员 权限 控制面板。注意SDK的需要 账户级 API 令牌 – 不是区密码 .
2. 检查外壳覆盖 . 您 shell 中设置的环境变量 优先于 .env 装入的文件 node --env-file=.env运行 set BRIGHTDATA (窗户)或 env | grep BRIGHTDATA (macOS/Linux)和清晰 任何剩余值.
3. 检查你的 .env 文件 : 没有引用, 周围没有空格 =没有跟踪 白空格, 和符号完全复制( 包括破折号) 。 偏好 LF 线 结局.
4. 打印实际装入的 :

   console.log(JSON.stringify(process.env.BRIGHTDATA_API_TOKEN));
   

   隐藏字符如 \r 将在输出中可见.

支助

关于任何问题,请联系 亮数据支持,或者在此寄存器中打开一个问题.

许可证

本项目根据以下规定获得许可证: MIT 许可证。 。 。 .