跳转到主要内容
POST
/
datasets
/
filter
cURL
curl --request POST \
  --url https://api.brightdata.com/datasets/filter \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'filter={
  "name": "name",
  "operator": "=",
  "value": "John"
}'
{
  "snapshot_id": "<string>"
}
将您的 API Key 粘贴到授权字段。要获取 API Key，请创建账户并了解如何生成 API Key。

​
一般描述

  • 此端点用于筛选数据集，并在您的账户中创建筛选数据的快照。
  • 任务以异步方式运行，最长可达 5 分钟。如果超时，将被取消。
  • 费用根据快照大小和每条记录定价计算。
  • 筛选组可以嵌套最多 3 层。
  • 在处理大量值时，您可以上传 CSV 或 JSON 文件以提高筛选效率。

​
文件格式要求

  • CSV
  • JSON
  • 第一行必须是与筛选字段名称匹配的表头。
  • 后续每行包含单个值。
Example: industries.csv
industries:value
Accounting
Ad Network
Advertising

​
使用文件引用的筛选语法

使用文件上传时，在筛选的 value 字段中引用文件名。
Example
{
  "operator": "and",
  "filters": [
    {
      "name": "industries:value",
      "operator": "includes",
      "value": "industries.csv"
    }
  ]
}

​
文件引用支持的运算符

OperatorField TypesDescription
inAny字段值等于文件中的任意值
not_inAny字段值不等于文件中的任意值
includesArray, Text字段值包含文件中的任意值
not_includesArray, Text字段值不包含文件中的任意值
array_includesArray文件中的任意值存在于字段值中
not_array_includesArray文件中的值不存在于字段值中

​
示例：使用多个文件进行筛选

curl \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "files[]=@/path/to/industries.csv" \
  -F "files[]=@/path/to/regions.csv" \
  -F "filter={\"operator\":\"and\",\"filters\":[{\"name\":\"industries:value\",\"operator\":\"includes\",\"value\":\"industries.csv\"},{\"name\":\"region\",\"operator\":\"in\",\"value\":\"regions.csv\"}]}" \
  "api.brightdata.com/datasets/filter?dataset_id=gd_l1vijqt9jfj7olije"

​
故障排除

问题可能解决方案
”File not found”确保筛选中引用的文件名与上传文件名完全匹配。
“Invalid file format”检查 CSV 表头是否与筛选字段名称匹配，或确保 JSON 是对象数组。
“Field not found”验证字段是否存在于数据集中。使用 获取数据集元数据。

​
相关文档

Authorizations

​
Authorization
string
header
required

在 Authorization 请求头中使用您的 Bright Data API Key 作为 Bearer 令牌。

获取 API Key: https://brightdata.com/cp/setting/users。

示例: Authorization: Bearer b5648e1096c6442f60a6c4bbbe73f8d2234d3d8324554bd6a7ec8f3f251f07df

Query Parameters

​
dataset_id
string
required

要筛选的数据集 ID（在 multipart/form-data 模式下为必填）

Example:

"gd_l1viktl72bvl7bjuj0"

​
records_limit
integer

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

Example:

1000

Body

multipart/form-data
​
filter
单字段筛选器 · object
required
  • 单字段筛选器
  • 筛选器组
  • 无值单字段筛选器
Example:
{
  "name": "name",
  "operator": "=",
  "value": "John"
}

Response

创建快照的任务已成功启动

​
snapshot_id
string

快照 ID