筛选数据集 (BETA)

基于提供的过滤条件创建数据集快照

POST /datasets/filter

cURL

cURL

curl --request POST \
  --url https://api.brightdata.com/datasets/filter \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "dataset_id": "gd_l1viktl72bvl7bjuj0",
  "filter": {
    "name": "name",
    "operator": "=",
    "value": "John"
  },
  "records_limit": 1000
}
'

200

{
  "snapshot_id": "<string>"
}

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

​

一般描述

• 调用此端点会启动异步任务，用于筛选数据集并在您的账户中创建包含筛选数据的快照。
• 任务完成的最长时间为 5 分钟。如果任务在此时间内未完成，将被取消。
• 创建数据集快照将根据快照大小和记录价格产生费用。
• 筛选组的最大嵌套深度为 3。

​

使用模式

​

1. JSON 模式（无需上传文件）

当您不上传任何文件时使用此模式。

• 所有参数（dataset_id、records_limit 和 filter）通过 JSON 请求体发送。
• Content-Type 必须为 application/json。
• 不使用查询参数。

Example

curl --request POST \
  --url https://api.brightdata.com/datasets/filter \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "dataset_id": "gd_l1viktl72bvl7bjuj0",
    "records_limit": 100,
    "filter": {
      "name": "name",
      "operator": "=",
      "value": "John"
    }
  }'

---

​

2. Multipart/Form-Data 模式（文件上传）

当上传 CSV 或 JSON 文件包含筛选值时使用此模式。

• dataset_id 和 records_limit 必须作为 查询参数 放在 URL 中。
• filter 和上传的文件包含在 form-data 请求体 中。
• Content-Type 必须为 multipart/form-data。

Example

curl --request POST \
  --url "https://api.brightdata.com/datasets/filter?dataset_id=gd_l1vijqt9jfj7olije&records_limit=100" \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'filter={"operator":"and","filters":[{"name":"industries:value","operator":"includes","value":"industries.csv"}]}' \
  --form 'files[]=@/path/to/industries.csv'

---

​

筛选语法

​

运算符

下表显示字段筛选中可使用的运算符。

Operator	Field Types	Description
=	Any	等于
!=	Any	不等于
<	Number, Date	小于
<=	Number, Date	小于或等于
>	Number, Date	大于
>=	Number, Date	大于或等于
in	Any	测试字段值是否等于筛选值中提供的任意值
not_in	Any	测试字段值是否不等于筛选值中提供的所有值
includes	Array, Text	测试字段值是否包含筛选值。如果筛选值是单个字符串，匹配字段值包含该字符串的记录。如果筛选值是字符串数组，匹配字段值包含数组中至少一个字符串的记录。
not_includes	Array, Text	测试字段值是否不包含筛选值。如果筛选值是单个字符串，匹配字段值不包含该字符串的记录。如果筛选值是字符串数组，匹配字段值不包含数组中任何字符串的记录。
array_includes	Array	测试筛选值是否在字段值中（完全匹配）
not_array_includes	Array	测试筛选值是否不在字段值中（完全匹配）
is_null	Any	测试字段值是否等于 NULL。运算符不接受任何值。
is_not_null	Any	测试字段值是否不等于 NULL。运算符不接受任何值。

​

多个筛选组合

多个字段筛选可以通过 2 个逻辑运算符 'and'、'or' 组合成筛选组。 API 支持最大嵌套深度为 3。

筛选组示例：

{
    // operator can be one of ["and", "or"]
    "operator": "and",
    // an array of field filters
    "filters": [
        {
            "name": "reviews_count",
            "opeartor": ">",
            "value": "200"
        },
        {
            "name": "rating",
            "operator": ">",
            "value": "4.5"
        }
    ]
}

授权

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

请求体

application/jsonmultipart/form-data

dataset_id · string · 必填

要过滤的数据集 ID

示例:

"gd_l1viktl72bvl7bjuj0"

filter · 单字段过滤器 · object · 必填

单字段过滤器

过滤器组

无值单字段过滤器

Show child attributes

示例:

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

records_limit · integer

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

示例:

1000

响应

200

application/json

快照创建任务已成功启动

snapshot_id · string

快照 ID