输入与输出架构 - Bright Data Docs

输入与输出架构定义了 Bright Data Scraper Studio IDE 采集器的数据契约：即一次采集运行接受哪些字段，以及采集器返回哪些结构化字段。

输入架构定义一次采集运行接受的字段，例如 url、keyword、country、date，或你的交互代码从 input 读取的任何自定义字段。
输出架构定义抓取器返回的结构化字段，基于 collect() 发出的数据。

这两种架构都在 Bright Data Scraper Studio IDE 中配置。当你点击 Save to Production 时，架构更改会应用到生产采集器。

什么是输入架构？

输入架构定义了你的抓取器在运行时可以接收的值。抓取器通常使用 url 输入，但输入并不局限于 URL。根据采集器逻辑，输入可以是关键词、位置、日期、ID、国家或任何自定义参数。你的交互代码通过 input 对象读取输入值：

navigate(input.url);
wait('.product-title');

const data = parse();
collect(data);

对于基于关键词的抓取器：

navigate(`https://example.com/search?q=${input.keyword}`);
wait('.search-results');

collect(parse());

如果目标 URL 或采集逻辑硬编码在抓取器代码中，抓取器也可以在没有用户提供输入的情况下运行。

定义输入参数

要在 Bright Data Scraper Studio IDE 中定义输入架构：

在 Scraper Studio IDE 中打开你的采集器。
前往 Code 选项卡。
点击 Add input parameter。
输入字段名称，例如 url、keyword、country 或 date。
添加可选的说明。
选择字段类型。
如果采集器缺少该字段就无法运行，则将其标记为 Required。
点击 Save。
当采集器就绪后，点击 Save to Production。

在采集器已经保存后，点击 IDE 中的 Edit schema 即可更新其输入架构。

输入参数有哪些设置？

设置	说明
Field name	在代码中作为 `input.<field_name>` 使用的键。
Description	可选说明，用于解释用户应提供什么值。
Type	期望的值类型，例如 text/string、boolean、date 或 country。
Required	如果启用，每个采集输入都必须包含此字段。
Predefined values	可选的固定选项，在所选类型支持时可用。例如 `country` 类型。
Case-insensitive	在字段配置支持时，将匹配值视为不区分大小写。

采集输入是什么样的？

基于 URL 的采集器可以接受一个或多个 URL：

[
  { "url": "https://example.com/product/1" },
  { "url": "https://example.com/product/2" }
]

采集器也可以接受多个输入字段：

[
  {
    "url": "https://example.com/search",
    "keyword": "standing desk",
    "country": "US"
  },
  {
    "url": "https://example.com/search",
    "keyword": "monitor arm",
    "country": "GB"
  }
]

只有标记为 Required 的字段才必须为每个输入对象提供。可选字段可以省略。

什么是输出架构？

输出架构定义了数据点的结构以及数据的组织方式。在 Bright Data Scraper Studio IDE 中，输出架构通常由传递给 collect() 的对象生成。

collect({
  title: $('.product-title').text_sane(),
  price: new Money(+$('.price').text().replace(/\D+/g, ''), 'USD'),
  availability: $('.stock-status').text_sane(),
});

这会生成如下输出字段：

{
  "title": "ErgoDesk Pro",
  "price": {
    "value": 349.99,
    "currency": "USD"
  },
  "availability": "In stock"
}

当抓取器保存时，Scraper Studio 会检测所采集数据的结构，并创建或更新输出架构。

更新输出架构

有两种方式更新输出架构：从解析器代码自动更新，或在架构编辑器中手动更新。

自动更新架构

在解析器代码中添加或更改字段。
运行预览，确认必填字段按预期返回。
点击 Save to Production。
如果 Scraper Studio 检测到架构更改，点击 Update schema。
再次点击 Save to Production。

手动更新架构

点击 IDE 中的 Edit schema。
按名称和类型添加或编辑字段。
配置必填标记、默认值、格式化、验证或 PII 设置。
保存架构。
点击 Save to Production。

什么是输出架构编辑器（Output Schema Editor）？

输出架构编辑器精确定义了你的采集器返回哪些字段，以及每个字段如何验证、格式化和交付。编辑器有两种视图：

视图	说明
Table view	字段的可视化列表，带有开关和字段配置。
JSON view	直接对架构对象进行 JSON 编辑。

点击某个字段行会打开该字段的配置侧面板。

输出架构是如何构建的？

输出架构是一个 JSON 对象，包含顶层的 type 和一个 fields 对象：

{
  "type": "object",
  "fields": {
    "title": {
      "type": "text",
      "active": true
    },
    "price": {
      "type": "price",
      "active": true
    }
  }
}

输出字段可以有哪些属性？

这些属性适用于用户定义的输出字段。

属性	类型	说明
`type`	string	字段类型，例如 `text`、`number`、`price`、`image` 或 `object`。
`active`	boolean	该字段是否包含在输出中。默认值：`true`。
`required`	boolean	如果为 `true`，此字段没有有效值的行会被标记为错误。
`default_value`	string	当字段无法填充时使用的值。
`description`	string	该字段的人类可读说明。
`pii`	boolean	将该字段标记为包含个人身份信息。
`custom_formatting`	object	用于高级输出整形的自定义 JavaScript 格式化器。
`custom_validation`	object	定义在每条采集记录上运行的验证规则。

在侧面板中配置字段

侧面板包含针对特定字段的设置。

设置	说明
Field name	在输出 JSON 中使用的键。适用于用户定义的字段。
Display name	可选的 UI 标签，与输出键分开。
Data type	字段类型。更改类型会重置特定于类型的设置。
Active	将该字段包含在输出中或从输出中排除。
Required	当此字段缺失或无效时，将行标记为错误。
Default value	当字段无法填充时的回退值。
Description	该字段的可选人类可读说明。
Contains PII	将该字段标记为包含个人身份信息。
Format	特定于类型的输出格式化。例如 price/money 类型。
Download	对于媒体/文件字段，将文件下载到已配置的存储中。
Array values	定义 `array` 字段的项目类型。
Subfields	定义 `object` 字段的嵌套字段。
Normalize	控制空数组的行为。
Set as quick filter	将该字段作为数据集查看器中的筛选器公开。
Quick filter operator	定义快速筛选器使用的比较运算符。

有哪些可用的默认值？

可用的默认值取决于字段类型。

选项	输出行为	适用于
`undefined`	字段从输出中省略。	所有类型
`null`	字段返回为 `null`。	所有类型
`""`	空字符串。	`text`
`false`	布尔值 false。	`boolean`
`0`	数字零。	`number`、`price`
`[]`	空数组。	`array`

有哪些可用的输出字段类型？

Scraper Studio 支持以下用户定义的输出字段类型。

`text`

自由格式文本。

{
  "type": "text",
  "active": true,
  "required": false,
  "default_value": "null"
}

示例值：

"Laptop 15-inch Pro"

`number`

整数或小数。数字字符串可以转换为数字。

{
  "type": "number",
  "active": true,
  "format": {
    "decimal_places": 2
  },
  "default_value": "zero"
}

示例值：

11.23

`url`

URL 字符串。仅接受 http:// 和 https:// URL。

{
  "type": "url",
  "active": true,
  "required": true
}

示例值：

"https://example.com/product/123"

`price`

以数值和货币代码表示的货币值。

{
  "type": "price",
  "active": true,
  "format": {
    "preset": "us_style"
  }
}

示例值：

{
  "value": 99.99,
  "currency": "USD"
}

价格格式预设：

预设	说明	示例
`us_style`	美式格式。	`$1,234.56`
`locale`	区域感知格式。需要区域设置。	`1.234,56 €`
`number`	仅数值。	`1234.56`
`raw`	原始对象。	`{ "value": 1234.56, "currency": "USD" }`
`custom`	使用 `{[symbol]}`、`{[value]}`、`{[currency]}` 的模板。	`USD 1234.56`

`boolean`

true/false 值。

{
  "type": "boolean",
  "active": true,
  "default_value": "false"
}

示例值：

true

`date`

日期或时间戳值。

{
  "type": "date",
  "active": true,
  "format": {
    "preset": "iso"
  }
}

日期格式预设：

预设	说明	示例
`iso`	ISO 8601 字符串。	`2024-03-15T10:30:00.000Z`
`timestamp`	以毫秒表示的 Unix 时间戳。	`1710494400000`
`locale`	区域感知的可读日期。	`March 15, 2024 at 10:30:00 AM UTC`

区域格式化可以包括：

区域设置，例如 en-US、fr-FR、ru-RU
日期样式：long、medium、short
时间样式：long、medium、short

`country`

两个字母的 ISO 3166-1 alpha-2 国家代码。

{
  "type": "country",
  "active": true
}

示例值：

"US"

`phone`

解析为结构化组件的电话号码。

{
  "type": "phone",
  "active": true
}

示例值：

{
  "area_code": 1,
  "number": 5555555555,
  "extension": "1234"
}

`image`

已下载或被引用的图片。

{
  "type": "image",
  "active": true,
  "download": true,
  "format": {
    "behavior": "object",
    "content_type": true
  }
}

当启用 Download 时，文件会存储在已配置的交付目标中。在适用情况下，文件下载与页面加载分开计费。

`video`、`pdf` 和 `doc`

这些文件类型使用与 image 相同的下载和行为设置。

{
  "type": "video",
  "active": true,
  "download": true
}

支持的文件字段类型：

类型	说明
`video`	已下载或被引用的视频文件。
`pdf`	已下载或被引用的 PDF 文件。
`doc`	已下载或被引用的文档文件。

文件字段输出选项

对于已下载的文件字段，例如 image、video、pdf 和 doc，输出架构编辑器允许你控制文件元数据的返回方式。这些设置在字段行为设置为 Object 时出现。

Behavior

使用 Behavior 选择文件字段的返回方式。

Simple — 仅返回已下载的文件路径或原始远程 URL。
Object — 返回一个包含文件元数据的对象，例如 file_path、remote_url、content_type、file_size 和 response_headers，具体取决于启用了哪些选项。

当你需要的不仅仅是文件路径时使用 Object，例如在验证文件类型、检查文件大小或调试下载头时。

Include content type

启用 Include content type 以在输出中包含文件的 MIME 类型。示例：

{
  "content_type": "image/jpeg"
}

用它来确认已下载的文件是图片、PDF、视频还是其他媒体类型。

Include file size

启用 Include file size 以包含以字节为单位的已下载文件大小。示例：

{
  "file_size": 123456
}

用它来验证文件大小、检测空的或意外过大的下载，或排查失败的媒体处理。

Include response headers

启用 Include response headers 以包含 Scraper Studio 下载文件时收到的 HTTP 响应头。示例：

{
  "response_headers": {
    "accept-ranges": "bytes",
    "age": "21753",
    "cache-control": "public, max-age=31557600",
    "content-type": "image/jpeg",
    "date": "Sun, 05 Jul 2026 12:43:07 GMT",
    "last-modified": "Sun, 05 Jul 2026 06:40:34 GMT",
    "source-length": "2088714",
    "source-type": "image/jpeg",
    "vary": "Accept"
  }
}

响应头可以帮助你调试文件下载、验证内容类型、检查缓存行为，以及排查意外的媒体响应。

示例输出

当 Behavior 设置为 Object 且所有元数据选项都启用时，输出可能如下所示：

{
  "image": {
    "file_path": "image.jpg",
    "remote_url": "https://example.com/image",
    "content_type": "image/jpeg",
    "file_size": 123456,
    "response_headers": {
      "accept-ranges": "bytes",
      "age": "21753",
      "cache-control": "public, max-age=31557600",
      "content-type": "image/jpeg",
      "date": "Sun, 05 Jul 2026 12:43:07 GMT",
      "last-modified": "Sun, 05 Jul 2026 06:40:34 GMT",
      "source-length": "2088714",
      "source-type": "image/jpeg",
      "vary": "Accept"
    }
  }
}

`array`

有序的值列表。元素类型通过 items 定义。

{
  "type": "array",
  "active": true,
  "normalize": {
    "empty": "keep"
  },
  "default_value": "empty_array",
  "items": {
    "type": "text"
  }
}

空数组行为：

选项	说明
`keep`	将空数组保持为 `[]`。
`drop`	用已配置的默认值替换空数组。

嵌套对象的数组：

{
  "type": "array",
  "active": true,
  "items": {
    "type": "object",
    "fields": {
      "name": {
        "type": "text",
        "active": true
      },
      "price": {
        "type": "price",
        "active": true
      }
    }
  }
}

`object`

带有自身子字段的嵌套对象。

{
  "type": "object",
  "active": true,
  "fields": {
    "title": {
      "type": "text",
      "active": true
    },
    "price": {
      "type": "price",
      "active": true
    },
    "in_stock": {
      "type": "boolean",
      "active": true
    }
  }
}

有哪些可用的 HTML 转换字段类型？

类型	说明	示例值
`html2text`	HTML 转换为可读文本。	`Product title\nDescription text`
`html2markdown`	HTML 转换为 Markdown。	`## Product title`
`html2html`	原始 HTML 内容。	`<div class="product"><h1>Title</h1></div>`
`html2ldjson`	来自 `application/ld+json` 脚本的结构化数据。	`{"@type":"Product","name":"Widget"}`

示例：

{
  "type": "html2markdown",
  "active": true
}

如何验证字段值？

自定义验证让你定义在字段的每个采集值上运行的 JavaScript 规则。抛出错误可将该值标记为无效：

function validate(v) {
  if (!v)
    throw new Error('Value is required');

  return true;
}

当为必需的输出质量配置了验证时，未通过验证的行会被视为错误行。

如何格式化字段值？

自定义格式化让你在输出交付之前转换字段值。

function process(value) {
  return value;
}

当内置格式化选项不符合所需的输出形态时，使用自定义格式化。

我应该在什么时候使用 collect() 而不是 set_lines()？

记录的发出方式会影响输出数据集。

函数	行为	使用场景
`collect(data)`	向数据集追加一条记录。	大多数抓取器。
`set_lines(data)`	用最新的一组记录替换先前发出的记录。	应保留最新快照的渐进式采集。

使用 collect() 的示例：

collect({
  title,
  price,
  availability,
});

使用 set_lines() 的示例：

set_lines(products);

我可以添加哪些系统字段？

系统字段由 Scraper Studio 生成。它们的名称和类型是固定的。你可以在输出架构配置的 Additional data 下打开或关闭它们。

字段	类型	默认	说明
`input`	string / object	开	触发本次爬取的输入值或对象。
`prime_input`	string / object	关	使用发现或分页时的原始根输入。
`error`	string	开	该行采集失败原因的说明。
`error_code`	string	开	结构化错误代码，例如 `validation` 或 `timeout`。
`warning`	string	开	该行的系统级警告。
`warning_code`	string	开	结构化警告代码。
`status_code`	number	关	类似 HTTP 的爬取结果代码，例如 `200` 或 `404`。
`timestamp`	date	关	页面被采集的日期和时间。
`requested_timestamp`	date	关	作业被触发的日期和时间。
`page_id`	string	关	页面爬取的唯一标识符。
`job_id`	string	关	产生该行的作业 ID。
`collector_id`	string	关	采集器的 ID。
`collector_queue`	string	关	作业提交到的队列。
`crawl_type`	string	关	该行使用的爬取或解析器类型。
`screenshot`	file	关	采集时浏览器页面的截图。
`html`	file	关	页面的完整 HTML 快照。
`warc`	file	关	页面的 WARC 存档。

当 screenshot、html 或 warc 处于活动状态时，文件会下载到已配置的存储目标。

如何添加截图水印？

当启用 screenshot 系统字段时，可以为截图添加水印。每个水印项都有一个标签和一个数据源。

数据源	说明
Browser URL	截图时浏览器所在的 URL。
Timestamp	截图捕获的时间戳。
Input value	来自采集器输入的值，例如 `url` 或 `config.country`。

完整的输出架构是什么样的？

{
  "type": "object",
  "fields": {
    "url": {
      "type": "url",
      "active": true,
      "required": true
    },
    "title": {
      "type": "text",
      "active": true
    },
    "price": {
      "type": "price",
      "active": true,
      "format": {
        "preset": "us_style"
      },
      "default_value": "zero"
    },
    "rating": {
      "type": "number",
      "active": true,
      "format": {
        "decimal_places": 1
      }
    },
    "in_stock": {
      "type": "boolean",
      "active": true,
      "default_value": "false"
    },
    "listed_date": {
      "type": "date",
      "active": true,
      "format": {
        "preset": "iso"
      }
    },
    "country": {
      "type": "country",
      "active": true
    },
    "images": {
      "type": "array",
      "active": true,
      "normalize": {
        "empty": "keep"
      },
      "default_value": "empty_array",
      "items": {
        "type": "image",
        "download": true
      }
    },
    "seller": {
      "type": "object",
      "active": true,
      "fields": {
        "name": {
          "type": "text",
          "active": true
        },
        "phone": {
          "type": "phone",
          "active": true
        }
      }
    }
  }
}

开发抓取器

在 IDE 中构建抓取器的分步演练

函数参考

带有参数和示例的交互与解析器函数

发起采集与交付

触发采集并将输出交付到你的目标

触发抓取器（API）

通过 API 运行已发布的采集器进行批量采集

​什么是输入架构？

​定义输入参数

​输入参数有哪些设置？

​采集输入是什么样的？

​什么是输出架构？

​更新输出架构

​自动更新架构

​手动更新架构

​什么是输出架构编辑器（Output Schema Editor）？

​输出架构是如何构建的？

​输出字段可以有哪些属性？

​在侧面板中配置字段

​有哪些可用的默认值？

​有哪些可用的输出字段类型？

​text

​number

​url

​price

​boolean

​date

​country

​phone

​image

​video、pdf 和 doc

​文件字段输出选项

​Behavior

​Include content type

​Include file size

​Include response headers

​示例输出

​array

​object

​有哪些可用的 HTML 转换字段类型？

​如何验证字段值？

​如何格式化字段值？

​我应该在什么时候使用 collect() 而不是 set_lines()？

​我可以添加哪些系统字段？

​如何添加截图水印？

​完整的输出架构是什么样的？

​相关内容

开发抓取器

函数参考

发起采集与交付

触发抓取器（API）

什么是输入架构？

定义输入参数

输入参数有哪些设置？

采集输入是什么样的？

什么是输出架构？

更新输出架构

自动更新架构

手动更新架构

什么是输出架构编辑器（Output Schema Editor）？

输出架构是如何构建的？

输出字段可以有哪些属性？

在侧面板中配置字段

有哪些可用的默认值？

有哪些可用的输出字段类型？

`text`

`number`

`url`

`price`

`boolean`

`date`

`country`

`phone`

`image`

`video`、`pdf` 和 `doc`

文件字段输出选项

Behavior

Include content type

Include file size

Include response headers

示例输出

`array`

`object`

有哪些可用的 HTML 转换字段类型？

如何验证字段值？

如何格式化字段值？

我应该在什么时候使用 collect() 而不是 set_lines()？

我可以添加哪些系统字段？

如何添加截图水印？

完整的输出架构是什么样的？

相关内容