> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/pt-br/web-scraper-api/features/result-processing-and-storage/result-aggregator.md).
# Agregador de resultados
Aprenda a retornar várias respostas da Web Scraper API como uma única saída maior usando o Agregador de resultados.
O **Agregador de Resultados** permite coletar vários resultados pequenos de tarefas separadas de scraping ou parsing em um único arquivo agregado. Isso é mais útil quando você executa várias tarefas 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](/products/pt-br/web-scraper-api/features/result-processing-and-storage/cloud-storage.md) (Google Cloud Storage, Amazon S3 ou outros serviços compatíveis com S3).
## Como usar
{% stepper %}
{% step %}
### Criar um agregador
Primeiro, defina uma instância de agregador com o destino de armazenamento de entrega e os 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 (`agendamento cron`) ou quando o arquivo atinge 500MB (`524288000` bytes), o que ocorrer primeiro.
```bash
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. | `cadeia de caracteres` |
| `storage_type` | Provedor de armazenamento ( `s3`, `gcs`, ou `s3_compatible`). | `cadeia de caracteres` |
| `storage_url` | Caminho do bucket/contêiner de destino. | `cadeia de caracteres` |
| `file_output_type` | Formato de saída (`json`, `jsonl`, `gzip_json`, ou `gzip_jsonl`) | `cadeia de caracteres` |
| `max_size_bytes` | Limite máximo de tamanho do lote em bytes.
Máx: 1GB.
| `inteiro` |
| `schedule` | Frequência de agregação em expressão cron. (por exemplo, 0 \*/1 \* \* \* para cada hora).
Máx: 1h.
| `cadeia de caracteres` |
| `max_result_count` | Aciona a entrega quando a contagem de resultados atinge o limite. | `inteiro` |
| `callback_url` | URL do seu endpoint de callback. [**Mais informações**](/products/pt-br/web-scraper-api/integration-methods/push-pull.md#callback) | `cadeia de caracteres` |
– parâmetro obrigatório.
{% endstep %}
{% step %}
### Enviar requisições ao agregador
Depois que seu agregador for criado, você pode direcionar tarefas de scraping para ele usando o `aggregate_name` parâmetro. Você não precisa especificar detalhes de armazenamento nessas requisições; o agregador cuida da entrega.
#### Exemplo de requisição
```bash
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"
}'
```
{% endstep %}
{% step %}
### 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
```bash
GET https://data.oxylabs.io/v1/aggregators/{name}
```
#### Exemplo de resposta
```json
{
"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
}
}
```
{% endstep %}
{% endstepper %}
### Outras operações
* **Listar todos os agregadores**: `GET https://data.oxylabs.io/v1/aggregators` — retorna `{"aggregators": [...]}`.
* **Excluir um agregador**: `DELETE https://data.oxylabs.io/v1/aggregators/{name}`
## 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:
```bash
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 e hora 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
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://developers.oxylabs.io/products/pt-br/web-scraper-api/features/result-processing-and-storage/result-aggregator.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.