Agregador de Resultados

Aprenda como retornar múltiplas respostas do Web Scraper API como uma única saída maior usando o Result Aggregator.

O Agregador de Resultados permite coletar vários resultados pequenos de trabalhos separados de scraping ou parsing em um único arquivo agregado. Isso é mais útil quando você executa inúmeros trabalhos que retornam muitos arquivos pequenos que poderiam ser combinados em coleções de saída maiores ou precisam processar resultados em arquivos em lote (JSON, JSONL ou Gzip).

As respostas agregadas podem ser entregues ao seu armazenamento em nuvem (Google Cloud Storage, Amazon S3 ou outros serviços compatíveis com S3).

Como usá-lo

1

Criar um agregador

Primeiro, defina uma instância de agregador com destino de armazenamento de entrega e gatilhos de entrega.

Exemplo de requisição

A requisição a seguir cria um agregador que faz upload de um arquivo em lote a cada 1 hora (cron schedule) ou quando o arquivo atingir 500MB (524288000 bytes), o que ocorrer primeiro.

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 da requisição

Parâmetro	Descrição	Tipo
name	Identificador exclusivo do agregador.	string
storage_type	Provedor de armazenamento ( s3, gcs, ou s3_compatible).	string
storage_url	Caminho do bucket/container de destino.	string
file_output_type	Formato de saída (json, jsonl, gzip_json, ou gzip_jsonl)	string
max_size_bytes	Limite máximo de tamanho do lote em bytes. Máx: 1GB.	integer
schedule	Frequência de agregação em cron expression. (por exemplo, 0 */1 * * * para cada hora). Máx: 1h.	string
max_result_count	Dispara a entrega quando a contagem de resultados atinge o limite.	integer
callback_url	URL para o seu endpoint de callback. Mais informações	string

– parâmetro obrigatório.

2

Enviar requisições ao agregador

Depois que seu agregador for criado, você pode direcionar trabalhos de scraping para ele usando o parâmetro aggregate_name . Você não precisa especificar detalhes de armazenamento nessas requisições, o agregador cuida da entrega.

Exemplo de requisição

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 info do agregador

Você pode verificar a configuração e as estatísticas de uso do seu agregador a qualquer momento.

Exemplo de requisição

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

Exemplo de resposta

{
    "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 e Saída

Entrega automática

Um arquivo em lote é fechado e enviado quando qualquer uma das seguintes situações ocorre:

• O schedule o limite de tempo é atingido (Máx: 1 hora).

• O max_size_bytes o limite de tamanho é atingido (Máx: 1GB).

• O max_result_count o limite de resultados é atingido.

Entrega manual

Você pode forçar a entrega imediata do lote atual antes que os limites sejam atingidos usando o POST https://data.oxylabs.io/v1/aggregators/{name}/trigger endpoint como no exemplo abaixo:

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

Estrutura de saída

Os arquivos de lote de saída são salvos no seu armazenamento com carimbos de data/hora únicos:

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