Agregador de Resultados

Aprenda a retornar várias reponses da Web Scarper API como uma única saída maior usando o Result Aggregator.

A 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 vários trabalhos que retornam muitos arquivos pequenos que podem 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 solicitaçã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 atinge 500MB (524288000 bytes), o que acontecer 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
nome	Identificador exclusivo do agregador.	string
storage_type	Provedor de armazenamento ( s3, gcs, ou s3_compatible).	string
storage_url	Caminho de destino do bucket/container.	string
file_output_type	Formato de saída (json, jsonl, gzip_json, ou gzip_jsonl)	string
max_size_bytes	Limite máximo do 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 atinge o limite.	integer
callback_url	URL do seu endpoint de callback. Mais informações	string

– parâmetro obrigatório.

2

Enviar solicitações ao agregador

Depois que seu agregador for criado, 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 solicitaçã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 solicitaçã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 condições ocorre:

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

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

• A max_result_count o limite de resultados é atingido.

Entrega manual

Você pode forçar uma 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 da saída

Os arquivos de lote de saída são salvos no seu armazenamento com timestamps exclusivos:

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