结果聚合器

了解如何使用结果聚合器将多个 网页爬虫 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 * * * 表示每小时）。 最大： 1h.	字符串
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