跳转到主要内容
输入与输出 schema 定义了 Bright Data Scraper Studio IDE 收集器的数据契约：一次收集运行接受哪些字段，以及收集器返回哪些结构化字段。
  • 输入 schema（Input schema） 定义一次收集运行接受的字段，例如 url、keyword、country、date，或交互代码从 input 读取的任意自定义字段。
  • 输出 schema（Output schema） 定义爬虫返回的结构化字段，基于 collect() 发出的数据。
两种 schema 均在 Bright Data Scraper Studio IDE 中配置。当你点击 Save to Production 时，schema 变更会应用到生产环境的收集器。

​
什么是输入 schema？

输入 schema 定义爬虫在运行时可以接收的值。 爬虫通常使用 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 中定义输入 schema：
  1. 在 Scraper Studio IDE 中打开你的收集器。
  2. 进入 Code 标签页。
  3. 点击 Add input parameter。
  4. 输入字段名称，例如 url、keyword、country 或 date。
  5. 添加可选描述。
  6. 选择字段类型。
  7. 如果收集器没有该字段就无法运行，将其标记为 Required。
  8. 点击 Save。
  9. 收集器准备就绪后，点击 Save to Production。
收集器保存后，在 IDE 中点击 Edit schema 即可更新其输入 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 的字段才必须在每个输入对象中提供。可选字段可以省略。

​
什么是输出 schema？

输出 schema 定义数据点结构以及数据的组织方式。 在 Bright Data Scraper Studio IDE 中，输出 schema 通常由传给 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 会检测收集到的数据结构，并创建或更新输出 schema。

​
如何更新输出 schema？

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

​
自动更新 schema

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

​
手动更新 schema

  1. 在 IDE 中点击 Edit schema。
  2. 按名称和类型添加或编辑字段。
  3. 配置必填标记、默认值、格式化、校验或 PII 设置。
  4. 保存 schema。
  5. 点击 Save to Production。

​
什么是输出 schema 编辑器？

输出 schema 编辑器（Output Schema Editor）精确定义收集器返回哪些字段，以及每个字段如何被校验、格式化与交付。 编辑器有两种视图：
视图说明
Table view字段的可视化列表，带开关与字段配置。
JSON view直接对 schema 对象进行 JSON 编辑。
点击字段所在行会打开该字段的配置侧边面板。

​
输出 schema 的结构是怎样的？

输出 schema 是一个 JSON 对象，包含顶层 type 和一个 fields 对象： 
{
  "type": "object",
  "fields": {
    "title": {
      "type": "text",
      "active": true
    },
    "price": {
      "type": "price",
      "active": true
    }
  }
}

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

以下属性适用于用户自定义的输出字段。
属性类型说明
typestring字段类型，例如 text、number、price、image 或 object。
activeboolean字段是否包含在输出中。默认值：true。
requiredboolean若为 true，该字段没有有效值的行会被标记为错误。
default_valuestring字段无法填充时使用的值。
descriptionstring字段的可读说明。
piiboolean将该字段标记为包含个人身份信息。
custom_formattingobject用于高级输出整形的自定义 JavaScript 格式化器。
custom_validationobject定义在每条收集记录上运行的校验规则。

​
在侧边面板中配置字段

侧边面板包含针对单个字段的设置。
设置项说明
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区域感知格式。需要 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"
  }
}
日期格式预设：
预设说明示例
isoISO 8601 字符串。2024-03-15T10:30:00.000Z
timestamp以毫秒为单位的 Unix 时间戳。1710494400000
locale区域感知的可读日期。March 15, 2024 at 10:30:00 AM UTC
区域格式可包含：
  • Locale，例如 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
  }
}
图片行为选项：
行为说明
simple已下载时返回文件名，未下载时返回源 URL。
object返回包含文件路径、远程 URL 以及（可选）content type 的对象。
对象输出示例： 
{
  "file_path": "file_xxxxxxxxxxx.img",
  "remote_url": "https://example.com/image.png",
  "content_type": "image/png"
}
启用 Download 后，文件会存储到所配置的交付目标。文件下载在适用情况下与页面加载分开计费。

​
video、pdf 和 doc

这些文件类型使用与 image 相同的下载和行为设置。 
{
  "type": "video",
  "active": true,
  "download": true
}
支持的文件字段类型：
类型说明
video已下载或被引用的视频文件。
pdf已下载或被引用的 PDF 文件。
doc已下载或被引用的文档文件。

​
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 转换字段类型？

类型说明示例值
html2textHTML 转换为可读文本。Product title\nDescription text
html2markdownHTML 转换为 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 生成。它们的名称和类型是固定的。你可以在输出 schema 配置的 Additional data 下开启或关闭它们。
字段类型默认说明
inputstring / object开触发该次爬取的输入值或对象。
prime_inputstring / object关使用发现或分页时的原始根输入。
errorstring开该行收集失败原因的说明。
error_codestring开结构化错误代码，例如 validation 或 timeout。
warningstring开该行的系统级警告。
warning_codestring开结构化警告代码。
status_codenumber关类 HTTP 的爬取结果代码，例如 200 或 404。
timestampdate关页面被收集的日期和时间。
requested_timestampdate关任务被触发的日期和时间。
page_idstring关页面爬取的唯一标识符。
job_idstring关产生该行的任务 ID。
collector_idstring关收集器的 ID。
collector_queuestring关任务提交到的队列。
crawl_typestring关该行使用的爬取或解析器类型。
screenshotfile关收集时浏览器页面的截图。
htmlfile关页面的完整 HTML 快照。
warcfile关页面的 WARC 归档。
当 screenshot、html 或 warc 处于启用状态时，相应文件会下载到所配置的存储目标。

​
如何为截图添加水印？

当启用 screenshot 系统字段时，可以为截图添加水印。每个水印项都有一个标签和一个数据来源。
来源说明
Browser URL截图时浏览器所在的 URL。
Timestamp截图捕获的时间戳。
Input value来自收集器输入的值，例如 url 或 config.country。

​
完整的输出 schema 是什么样子？

{
  "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 开发爬虫

在 IDE 中构建爬虫的分步教程

Scraper Studio 函数参考

交互函数与解析器函数，含参数与示例

启动数据收集与交付

触发收集并将输出交付到你的目标位置

触发爬虫（API）

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