跳转到主要内容
POST
cURL
Bright Data 市场数据集 API 的 Filter 端点可针对 900+ 个市场数据集中的任意一个运行大型或基于文件的筛选任务,并返回一个 snapshot_id,任务完成后即可用它下载数据。
将您的 API Key 粘贴到授权字段。要获取 API Key,请创建账户并了解如何生成 API Key。

何时使用 Filter?

对于可接受异步处理的批量或基于文件的任务,使用 Filter:
  • 按字段值筛选市场数据集,例如国家、价格或布尔标志。
  • 查找文本字段包含某个值的记录。
  • 按精确值列表匹配记录。
  • 按 CSV 或 JSON 文件中的大型值列表筛选,例如排除 10 万以上的公司 ID。
  • 超过 1,000 条记录的批量导出。
  • Search 尚不支持的数据集。
如需对受支持数据集进行亚秒级实时查询,请改用 Search。

Filter 如何工作?

  • 调用 Filter 端点会启动一个异步任务,并在您的账户中创建一份筛选数据的快照。
  • 端点返回 snapshot_id,而不是筛选后的记录。
  • 任务最长运行时间为 5 分钟。运行超时的任务将被取消。
  • 按快照中的每条记录计费,采用标准市场费率 $2.5 CPM。
  • Filter 适用于全部 900+ 个市场数据集。
  • 筛选组的最大嵌套深度为 3 层。

如何进行身份验证?

Filter 使用 Bearer token 身份验证。在 Authorization 请求头中传入您的 API Key:
从账户设置获取您的 Key。

Filter 有哪些限制?

如有超出上述限制的复杂筛选需求,请联系您的客户经理。

如何使用 JSON 请求进行筛选?

当筛选值可以直接放入请求时,使用 JSON 模式。将 dataset_id、records_limit 和 filter 放在 JSON 请求体中,并将 Content-Type 设为 application/json:
Filter 返回一个 snapshot_id:

Filter 接受哪些请求字段?

如何按字段类型筛选?

每个字段筛选由字段名称、运算符和值组成。以下示例按字段类型展示常用运算符。完整的运算符表、筛选组和嵌套规则,请参阅筛选语法参考。

文本字段

使用 includes 匹配字段包含该值的记录:
此筛选可匹配 John Smith、Johnson 和 Senior John Account Manager 等值。使用 not_includes 可排除这些记录。

精确值列表

使用 in 匹配字段值恰好为列表中某个值的记录:
使用 not_in 排除字段值在列表中的记录。

何时使用 includes 而不是 in?

例如,includes 搭配 engineer 可匹配 Sales Engineer 和 Engineering Manager,而 in 搭配 ["Sales Engineer"] 仅匹配 Sales Engineer。

布尔字段

使用 = 搭配 true 或 false:

数值字段

数值字段支持 =、!=、<、<=、>、>=、in、not_in、is_null 和 is_not_null:

日期范围

在 and 组中组合 >= 和 <= 以匹配日期范围:

数组字段

使用 array_includes 匹配多值字段中包含某个精确值的记录:
此筛选匹配 categories 数组包含 Electronics 的记录。使用 not_array_includes 可排除这些记录。

空字段

使用 is_not_null 仅保留字段有值的记录,或使用 is_null 匹配字段为空的记录。这两个运算符不需要 value:

如何使用 CSV 或 JSON 文件上传进行筛选?

当您需要按大型值列表筛选时,使用文件上传。以 multipart/form-data 发送请求,将 dataset_id 和 records_limit 作为查询参数传入,并将每个筛选的 value 设为上传文件的名称:
响应与 JSON 模式返回的 snapshot_id 对象相同。

如何格式化 CSV 或 JSON 文件?

  • 第一行必须是与筛选字段名称匹配的表头。
  • 后续每行包含单个值。
  • 文件只能包含一列。
  • 不支持空行和仅包含空格的行。
Example: industries.csv
文件中的值必须与数据集字段格式完全一致。

哪些运算符接受文件引用?

文件引用仅可与 in、not_in、includes、not_includes、array_includes 和 not_array_includes 配合使用。各运算符如何处理文件,请参阅筛选语法参考。

如何按超过 10,000 个值筛选?

将这些值拆分为每个最多 10,000 行的文件,并在一次请求中全部附加。以下示例排除分布在三个文件中的公司 ID:
一次请求中的多个文件也可用于不同字段。以下示例组合了行业文件和地区文件:

如何修复文件上传错误?

Filter 返回什么?

Filter 返回 snapshot_id,即该请求创建的筛选快照的 ID:
任务完成后,将 snapshot_id 用于快照端点:

Filter 的费用是多少?

Filter 的费用为 $2.5 CPM(每返回 1,000 条记录),与市场价格相同。筛选返回 0 条记录时不收费。

Filter 可能返回哪些错误?

相关文档

授权

Authorization
string
header
必填

在 Authorization 头中使用您的 Bright Data API Key 作为 Bearer token。

认证方法:

  1. 从 Bright Data 账户设置获取您的 API Key: https://brightdata.com/cp/setting/users
  2. 在请求的 Authorization 头中包含 API Key
  3. 格式: Authorization: Bearer YOUR_API_KEY

示例:

了解如何获取 Bright Data API Key: https://docs.brightdata.com/cn/api-reference/authentication#如何生成新的-api-key?

查询参数

dataset_id
string

要过滤的数据集 ID(在 multipart/form-data 模式下为必填)

示例:

"gd_l1viktl72bvl7bjuj0"

records_limit
integer

限制快照中包含的记录数量

示例:

1000

请求体

dataset_id
string
必填

要过滤的数据集 ID

示例:

"gd_l1viktl72bvl7bjuj0"

filter
单字段过滤器 · object
必填
示例:
records_limit
integer

限制快照中包含的记录数量

示例:

1000

响应

快照创建任务已成功启动

snapshot_id
string

快照 ID