Agregador de Resultados

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

O Agregador de Resultados permite coletar múltiplos pequenos resultados 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 usar

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 solicitação a seguir cria um agregador que envia um arquivo em lote a cada 1 hora (agendamento cron) 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 solicitação

Parâmetro	Descrição	Tipo
name	Identificador único 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 expressão cron. (por exemplo, 0 */1 * * * para cada hora). Máx: 1h.	string
max_result_count	Dispara a entrega quando a contagem de resultados atingir o limite.	integer
callback_url	URL para seu endpoint de callback. Mais informações	string

– parâmetro obrigatório.

2

Enviar solicitações ao agregador

Após criar seu agregador, você pode direcionar trabalhos de scraping para ele usando o aggregate_name parâmetro. Você não precisa especificar detalhes de armazenamento nessas solicitaçõ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 informações 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 ocorre qualquer uma das seguintes situações:

• 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 timestamps ú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