Agregador de resultados

Aprende a devolver varias respuestas de Web Scarper 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 parsing en un único archivo agregado. Esto es especialmente ú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 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 un destino de almacenamiento de entrega y 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.

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.	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.: 1 GB.	integer
schedule	Frecuencia de agregación en expresión cron. (p. ej., 0 */1 * * * para cada hora). Máx.: 1 h.	cadena
max_result_count	Activa la entrega cuando el recuento de resultados alcanza el límite.	integer
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 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

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 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 se sube cuando ocurre cualquiera de las siguientes situaciones:

• 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.: 1 GB).

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

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

Estructura de salida

Los archivos de salida por lotes 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