Result Aggregator

Aprende cómo devolver múltiples respuestas de Web Scraper API como una única salida más grande usando Result Aggregator.

El Agregador de Resultados te permite recopilar múltiples resultados pequeños de trabajos separados de scraping o parsing 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 (Google Cloud Storage, Amazon S3 u otros servicios compatibles con S3).

Cómo usarlo

1

Crear un agregador

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

Ejemplo de solicitud

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

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
name	Identificador único del agregador.	string
storage_type	Proveedor de almacenamiento ( s3, gcs, o s3_compatible).	string
storage_url	Ruta del bucket/contenedor de destino.	string
file_output_type	Formato de salida (json, jsonl, gzip_json, o gzip_jsonl)	string
max_size_bytes	Límite máximo de tamaño del lote en bytes. Máx.: 1GB.	integer
schedule	Frecuencia de agregación en cron expression. (p. ej., 0 */1 * * * para cada hora). Máx.: 1h.	string
max_result_count	Dispara la entrega cuando el recuento de resultados alcanza el límite.	integer
callback_url	URL de tu endpoint de callback. Más información	string

– parámetro obligatorio.

2

Enviar solicitudes al agregador

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

Ejemplo de solicitud

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

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

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

Ejemplo de respuesta

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

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 la 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 a continuación:

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