# Agregador de resultados

El **Agregador de resultados** te permite recopilar múltiples resultados pequeños de trabajos separados de scraping o análisis en un único archivo agregado. Esto es más útil cuando ejecutas numerosos trabajos que devuelven muchos archivos pequeños que podrían combinarse en colecciones de salida más grandes o necesitan procesar resultados en archivos por lotes (JSON, JSONL o Gzip).

Las respuestas agregadas pueden entregarse a tu [almacenamiento en la nube](https://developers.oxylabs.io/documentation/es/soluciones-de-scraping/web-scraper-api/features/result-processing-and-storage/cloud-storage) (Google Cloud Storage, Amazon S3 u otros servicios compatibles con S3).

## Cómo usarlo

{% stepper %}
{% step %}

### Crear un agregador

Primero, define una instancia de agregador con el destino de almacenamiento de entrega y los disparadores de entrega.

#### Ejemplo de solicitud

La siguiente solicitud crea un agregador que sube un archivo por lotes cada 1 hora (`programación cron`) o cuando el archivo alcanza 500 MB (`524288000` bytes), lo que ocurra primero.

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

#### Parámetros de la solicitud

| Parámetro                                                                        | Descripción                                                                                                                                                         | Tipo      |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| <mark style="color:predeterminado;background-color:green;">`name`</mark>         | Identificador único del agregador.                                                                                                                                  | `string`  |
| <mark style="color:predeterminado;background-color:green;">`storage_type`</mark> | Proveedor de almacenamiento ( `s3`, `gcs`, o `s3_compatible`).                                                                                                      | `string`  |
| <mark style="color:predeterminado;background-color:green;">`storage_url`</mark>  | Ruta del bucket/contenedor de destino.                                                                                                                              | `string`  |
| `file_output_type`                                                               | Formato de salida (`json`, `jsonl`, `gzip_json`, o `gzip_jsonl`)                                                                                                    | `string`  |
| `max_size_bytes`                                                                 | <p>Límite máximo de tamaño del lote en bytes.</p><p>Máx: <strong>1GB</strong>.</p>                                                                                  | `integer` |
| `schedule`                                                                       | <p>Frecuencia de agregación en <strong>expresión cron</strong>. (p. ej., <code>0 \*/1 \* \* \*</code> para cada hora).<br>Máx: <strong>1h</strong>.</p>             | `string`  |
| `max_result_count`                                                               | Dispara la entrega cuando el conteo de resultados alcanza el límite.                                                                                                | `integer` |
| `callback_url`                                                                   | URL de su endpoint de callback. [**Más información**](https://developers.oxylabs.io/documentation/es/soluciones-de-scraping/integration-methods/push-pull#callback) | `string`  |

&#x20;    – parámetro obligatorio.
{% endstep %}

{% step %}

### Enviar solicitudes al agregador

Una vez creado tu agregador, puedes dirigir trabajos de scraping a él usando el `aggregate_name` parámetro. No necesitas especificar los detalles de almacenamiento en estas solicitudes; el agregador se encarga de la entrega.

#### Ejemplo de solicitud

```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 %}

### Recuperar información del agregador

Puedes comprobar la configuración y las estadísticas de uso de tu agregador en cualquier momento.

#### Ejemplo de solicitud

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

#### Ejemplo de respuesta

```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 %}

## Entrega y salida

### Entrega automática

Un archivo por lotes se cierra y sube cuando ocurre cualquiera de lo siguiente:

* El `schedule` se alcanza el límite de tiempo (Máx: 1 hora).
* El `max_size_bytes` se alcanza el límite de tamaño (Máx: 1GB).
* El `max_result_count` se alcanza el límite de resultados.

### Entrega manual

Puedes forzar una entrega inmediata del lote actual antes de que se alcancen los límites usando el `POST https://data.oxylabs.io/v1/aggregators/{name}/trigger` endpoint como en el ejemplo siguiente:

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

### Estructura de salida

Los archivos por lotes de salida se guardan en tu almacenamiento con marcas de tiempo únicas:

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