# Agregador de Resultados

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](/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 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.

```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 solicitação

| Parâmetro                                                                | Descrição                                                                                                                                                   | Tipo      |
| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| <mark style="color:padrão;background-color:green;">`nome`</mark>         | Identificador exclusivo do agregador.                                                                                                                       | `string`  |
| <mark style="color:padrão;background-color:green;">`storage_type`</mark> | Provedor de armazenamento ( `s3`, `gcs`, ou `s3_compatible`).                                                                                               | `string`  |
| <mark style="color:padrão;background-color:green;">`storage_url`</mark>  | 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`                                                         | <p>Limite máximo do tamanho do lote em bytes.</p><p>Máx: <strong>1GB</strong>.</p>                                                                          | `integer` |
| `schedule`                                                               | <p>Frequência de agregação em <strong>expressão cron</strong>. (por exemplo, <code>0 \*/1 \* \* \*</code> para cada hora).<br>Máx: <strong>1h</strong>.</p> | `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**](/products/pt-br/web-scraper-api/integration-methods/push-pull.md#callback)                          | `string`  |

&#x20;    – parâmetro obrigatório.
{% endstep %}

{% step %}

### 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

```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 solicitaçã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 %}

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

```bash
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
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.oxylabs.io/products/pt-br/web-scraper-api/features/result-processing-and-storage/result-aggregator.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.