筛选数据集（JSON 或文件上传）

根据提供的筛选条件创建数据集快照

POST /datasets/filter

cURL

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"
}'

200

{
  "snapshot_id": "<string>"
}

将您的 API Key 粘贴到授权字段。要获取 API Key，请创建账户并了解如何生成 API Key。

​

一般描述

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

---

​

文件格式要求

CSV

• 第一行必须是与筛选字段名称匹配的表头。
• 后续每行包含单个值。

Example: industries.csv

industries:value
Accounting
Ad Network
Advertising

JSON

• 必须是对象数组，每个对象的键与筛选字段名称匹配。

Example industries.json

[
  {"industries:value": "Accounting"},
  {"industries:value": "Ad Network"},
  {"industries:value": "Advertising"}
]

---

​

使用文件引用的筛选语法

使用文件上传时，在筛选的 value 字段中引用文件名。

Example

{
  "operator": "and",
  "filters": [
    {
      "name": "industries:value",
      "operator": "includes",
      "value": "industries.csv"
    }
  ]
}

​

文件引用支持的运算符

Operator	Field Types	Description
in	Any	字段值等于文件中的任意值
not_in	Any	字段值不等于文件中的任意值
includes	Array, Text	字段值包含文件中的任意值
not_includes	Array, Text	字段值不包含文件中的任意值
array_includes	Array	文件中的任意值存在于字段值中
not_array_includes	Array	文件中的值不存在于字段值中

---

​

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

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”	验证字段是否存在于数据集中。使用 获取数据集元数据。

​

相关文档

• 获取数据集列表
• 获取数据集元数据
• 数据集下载 API

授权

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

示例:

Authorization: Bearer b5648e1096c6442f60a6c4bbbe73f8d2234d3d8324554bd6a7ec8f3f251f07df

了解如何获取 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

请求体

multipart/form-data

filter · 单字段筛选器 · object · 必填

单字段筛选器

筛选器组

无值单字段筛选器

Show child attributes

示例:

{
  "name": "name",
  "operator": "=",
  "value": "John"
}

响应

200

application/json

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

snapshot_id · string

快照 ID