结果聚合器

了解如何使用结果聚合器将多个 Web Scraper API 响应合并为单个更大的输出。

该 结果聚合器 允许您将来自单独爬取或解析任务的多个小结果收集到一个聚合文件中。当您运行大量返回许多小文件的任务，这些文件可以合并为更大的输出集合或需要以批量文件（JSON、JSONL 或 Gzip）处理结果时，这非常有用。

聚合后的响应可以传送到您的 云存储 （Google Cloud Storage、Amazon S3 或其他兼容 S3 的服务）。

使用方法

1

创建聚合器

首先，定义一个具有交付存储目标和交付触发器的聚合器实例。

请求示例

下面的请求创建了一个每 1 小时上传一次批处理文件（cron 调度）或当文件达到 500MB（524288000 字节）时触发交付，以先到者为准。

curl -X POST https://data.oxylabs.io/v1/aggregators \
-u "USERNAME:PASSWORD" \
-H "Content-Type: application/json" \
-d '{
  "name": "amazon_hourly",
  "storage_type": "s3",
  "storage_url": "s3://my_bucket/batches",
  "max_result_count": 10000,
  "max_size_bytes": 524288000,
  "schedule": "0 */1 * * *"
}'

请求参数

参数	描述	类型
name	聚合器的唯一标识符。	字符串
storage_type	存储提供商（ s3, gcs，或 s3_compatible).	字符串
storage_url	目标存储桶/容器路径。	字符串
file_output_type	输出格式（json, jsonl, gzip_json，或 gzip_jsonl)	字符串
max_size_bytes	以字节为单位的最大批处理大小限制。 最大： 1GB.	整数
schedule	以 cron 表达式表示的聚合频率。 0 */1 * * * （例如， 每 1 小时）。 最大：.	字符串
max_result_count	当结果数量达到该限制时触发交付。	整数
callback_url	回调端点的 URL。 更多信息	字符串

– 必填参数。

2

发送请求到聚合器

聚合器创建后，您可以在爬取任务中使用 aggregate_name 参数将任务路由到它。您无需在这些请求中指定存储细节，聚合器会处理交付。

请求示例

curl --user "USERNAME:PASSWORD" \
'https://data.oxylabs.io/v1/queries' \
-H "Content-Type: application/json" \
-d '{
    "source": "universal",
    "url": "https://www.example.com",
    "aggregate_name": "amazon_hourly"
}'

3

检索聚合器信息

您可以随时查看聚合器的配置和使用统计信息。

请求示例

GET https://data.oxylabs.io/v1/aggregators/{name}

响应示例

{
    "name": "amazon_hourly",
    "callback_url": "",
    "storage_type": "s3",
    "storage_url": "s3://my_bucket/path_for_aggregates",
    "max_result_count": 1048576,
    "max_size_bytes": 524288000,
    "schedule": "0 */1 * * *",
    "file_output_type": "jsonl",
    "filename_prefix": "",
    "filename_suffix": "",
    "created_at": "2025-12-05T13:30:32Z",
    "usage_statistics": {
        "total_result_count": 0,
        "total_bytes_delivered": 0,
        "total_files_delivered": 0
    }
}

交付与输出

自动交付

当发生以下任一情况时，批处理文件会被关闭并上传：

• 该 schedule 达到时间限制（最大：1 小时）。

• 该 max_size_bytes 达到大小限制（最大：1GB）。

• 该 max_result_count 达到结果数量限制。

手动交付

您可以使用以下端点在达到限制之前强制立即交付当前批次： POST https://data.oxylabs.io/v1/aggregators/{name}/trigger 示例如下：

curl -X POST https://data.oxylabs.io/v1/aggregators/amazon_hourly/trigger -u "USERNAME:PASSWORD"

输出结构

输出批处理文件使用带有唯一时间戳的名称保存到您的存储：

my_bucket/
├── batches/
│   ├── 2024-08-08T01:00:00.000-00:00-amazon_hourly.jsonl
│   ├── 2024-08-08T02:00:00.000-00:00-amazon_hourly.jsonl
│   └── 2024-08-08T03:00:00.000-00:00-amazon_hourly.jsonl