Agregador de resultados

Aprende a devolver múltiples respuestas de Web Scraper API como una sola 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 parseo 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 cuando necesitas procesar resultados en archivos por lotes (JSON, JSONL o Gzip).

Las respuestas agregadas se pueden entregar 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 y los desencadenadores 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 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 solicitud

Parámetro	Descripción	Tipo
name	Identificador único del agregador.	cadena
storage_type	Proveedor de almacenamiento ( s3, gcs, o s3_compatible).	cadena
storage_url	Ruta del bucket/contenedor de destino.	cadena
file_output_type	Formato de salida (json, jsonl, gzip_json, o gzip_jsonl)	cadena
max_size_bytes	Límite máximo del tamaño del lote en bytes. Máx.: 1GB.	entero
schedule	Frecuencia de agregación en expresión cron. (p. ej., 0 */1 * * * para cada hora). Máx.: 1h.	cadena
max_result_count	Dispara la entrega cuando el conteo de resultados alcanza el límite.	entero
callback_url	URL de tu endpoint de callback. Más información	cadena

– parámetro obligatorio.

2

Enviar solicitudes al agregador

Una vez creado tu agregador, puedes enviar 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

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

Obtener información del agregador

Puedes consultar 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
    }
}

Otras operaciones

• Listar todos los agregadores: GET https://data.oxylabs.io/v1/aggregators — devuelve {"aggregators": [...]}.
• Eliminar un agregador: DELETE https://data.oxylabs.io/v1/aggregators/{name}

Entrega y salida

Entrega automática

Un archivo por lotes se cierra y se sube cuando ocurre cualquiera de las siguientes condiciones:

• 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 siguiente ejemplo:

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