# 结果聚合器

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

聚合后的响应可以传送到您的 [云存储](https://developers.oxylabs.io/documentation/cn/zhua-qu-jie-jue-fang-an/web-scraper-api/features/result-processing-and-storage/cloud-storage) （Google Cloud Storage、Amazon S3 或其他兼容 S3 的服务）。

## 使用方法

{% stepper %}
{% step %}

### 创建聚合器

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

#### 请求示例

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

```bash
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 * * *"
}'
```

#### 请求参数

| 参数                                                                   | 描述                                                                                                                                   | 类型    |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| <mark style="color:默认;background-color:green;">`name`</mark>         | 聚合器的唯一标识符。                                                                                                                           | `字符串` |
| <mark style="color:默认;background-color:green;">`storage_type`</mark> | 存储提供商（ `s3`, `gcs`，或 `s3_compatible`).                                                                                               | `字符串` |
| <mark style="color:默认;background-color:green;">`storage_url`</mark>  | 目标存储桶/容器路径。                                                                                                                          | `字符串` |
| `file_output_type`                                                   | 输出格式（`json`, `jsonl`, `gzip_json`，或 `gzip_jsonl`)                                                                                    | `字符串` |
| `max_size_bytes`                                                     | <p>以字节为单位的最大批处理大小限制。</p><p>最大： <strong>1GB</strong>.</p>                                                                             | `整数`  |
| `schedule`                                                           | <p>以 <strong>cron 表达式</strong>表示的聚合频率。 <code>0 \*/1 \* \* \*</code> （例如， <strong>每 1 小时）。</strong><br><strong>最大：</strong>.</p>      | `字符串` |
| `max_result_count`                                                   | 当结果数量达到该限制时触发交付。                                                                                                                     | `整数`  |
| `callback_url`                                                       | 回调端点的 URL。 [**更多信息**](https://developers.oxylabs.io/documentation/cn/zhua-qu-jie-jue-fang-an/integration-methods/push-pull#callback) | `字符串` |

&#x20;    – 必填参数。
{% endstep %}

{% step %}

### 发送请求到聚合器

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

#### 请求示例

```bash
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"
}'
```

{% endstep %}

{% step %}

### 检索聚合器信息

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

#### 请求示例

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

#### 响应示例

```json
{
    "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
    }
}
```

{% endstep %}
{% endstepper %}

## 交付与输出

### 自动交付

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

* 该 `schedule` 达到时间限制（最大：1 小时）。
* 该 `max_size_bytes` 达到大小限制（最大：1GB）。
* 该 `max_result_count` 达到结果数量限制。

### 手动交付

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

```bash
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
```