# Scheduler

[**Agendador**](https://oxylabs.io/features/scheduler) é um **recurso gratuito** do Web Scraper API que permite automatizar trabalhos recorrentes de scraping e parsing criando cronogramas. 

Assista ao tutorial em vídeo abaixo para aprender mais sobre o Agendador e como ele funciona.

{% embed url="<https://www.youtube.com/watch?v=HJLkFZ_9Z5w>" %}
Guia passo a passo para automatizar seus trabalhos recorrentes de scraping usando o Agendador
{% endembed %}

Recomendamos usar o Agendador juntamente com o [**Upload para Armazenamento em Nuvem**](https://developers.oxylabs.io/documentation/pt-br/solucoes-de-scraping/web-scraper-api/features/result-processing-and-storage/cloud-storage) recurso. Dessa forma, você pode configurar seu cronograma e receber atualizações regulares de dados no seu armazenamento sem tentar buscar resultados do nosso sistema.

{% hint style="warning" %}
**IMPORTANTE**: O Agendador é uma ferramenta poderosa que pode aumentar rapidamente sua fatura de serviço. Recomendamos testá-lo com alguns itens de trabalho e um número limitado de repetições para garantir que você receba os dados corretos nos intervalos adequados. Uma vez estabelecido, você pode parar o cronograma de teste e criar um novo cronograma em maior escala.
{% endhint %}

## Início Rápido

Ao criar um novo cronograma, siga os passos simples abaixo.

1. Diga-nos **com que frequência devemos repetir os trabalhos** enviando uma expressão de cron;
2. Forneça-nos **um conjunto de parâmetros de trabalho** que devemos executar em horários agendados;
3. Informe-nos **quando parar** enviando um horário de término.

&#x20;Veja [**aqui**](#create-a-new-schedule) para encontrar um exemplo de código para enviar um novo cronograma.

{% hint style="info" %}
**NOTA**: Você também pode baixar e importar [**esta coleção do Postman**](https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiwDdoZGfMbUe5cRL2417%2Fuploads%2FsipIxRVxZmZroadwSuqg%2FScheduler.postman_collection.json?alt=media\&token=dac92525-e5cc-43c2-a8eb-a32e8eba0483) para experimentar todos os nossos endpoints do Agendador. Novo no Postman? Saiba mais sobre esta ferramenta [**aqui**](https://developers.oxylabs.io/documentation/pt-br/guias-para-scraper-apis/using-postman).
{% endhint %}

## Endpoints

O Agendador possui vários endpoints que você pode usar para controlar o serviço:&#x20;

* [**Criar um novo cronograma**](#1.-create-a-new-schedule)
* [**Obter todos os cronogramas**](#get-all-schedules)
* [**Obter** **execuções** **informações**](#get-runs-information)
* [**Obter trabalhos agendados**](#get-scheduled-jobs)
* [**Obter informações do cronograma**](#get-schedule-info)
* [**Desativar ou reativar um cronograma**](#change-schedule-state)

### Criar um novo cronograma

#### Visão geral

Use este endpoint para iniciar um novo cronograma.

* **Endpoint**: `https://data.oxylabs.io/v1/schedules`
* **Método**: `POST`
* **Autenticação**: `Basic`
* **Cabeçalhos da requisição**: `Content-Type: application/json`

**Entrada**

<table><thead><tr><th width="150">Parâmetro</th><th width="435.3333333333333">Descrição</th><th>Valor Padrão</th></tr></thead><tbody><tr><td> <mark style="color:padrão;background-color:green;"><strong><code>cron</code></strong></mark> </td><td>Expressão de cron. Determina com que frequência o cronograma enviado será executado. Leia mais <a href="https://crontab.guru/"><strong>aqui</strong></a> e <a href="https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm"><strong>aqui</strong></a>.</td><td>-</td></tr><tr><td> <mark style="color:padrão;background-color:green;"><strong><code>itens</code></strong></mark> </td><td>Lista de conjuntos de parâmetros de trabalho do Scraper APIs que devem ser executados como parte do cronograma.</td><td>-</td></tr><tr><td><mark style="color:padrão;background-color:green;"><strong><code>end_time</code></strong></mark> </td><td>O horário em que o cronograma deve parar de ser executado. NB: o horário de término é inclusivo.</td><td>-</td></tr></tbody></table>

&#x20;    \- parâmetro obrigatório

{% hint style="info" %}
**NOTA**: Para orientação sobre como montar conjuntos de parâmetros de trabalho para a **`itens`** parte do seu payload do Agendador, consulte a página de documentação do scraper específico que você deseja usar (por exemplo, [**Google**](https://developers.oxylabs.io/documentation/pt-br/solucoes-de-scraping/web-scraper-api/targets/google), [**Amazon**](https://developers.oxylabs.io/documentation/pt-br/solucoes-de-scraping/web-scraper-api/targets/amazon), etc.).
{% endhint %}

O payload abaixo fará com que o Agendador execute dois trabalhos agendados às 03:00 nas segundas-feiras até `end_time` (inclusivo).

```json
{
  "cron": "0 3 * * 1",
  "items": [
    {"source": "universal", "url": "https://ip.oxylabs.io"},
    {"source": "google_search", "query": "stuff"}
  ],
  "end_time": "2032-12-21 12:34:45"
}
```

#### Saída

A resposta abaixo confirma que o cronograma foi criado com sucesso.

```json
{
    "schedule_id": 4134906379157007223,
    "active": true,
    "items_count": 3,
    "cron": "0 3 * * 1",
    "end_time": "2032-12-21 12:34:45",
    "next_run_at": "2022-06-06 10:15:00"
}
```

### Obter todos os cronogramas

#### Visão geral

Use este endpoint para obter a lista de todos os cronogramas associados à sua conta de usuário.

* **Endpoint**: `https://data.oxylabs.io/v1/schedules`
* **Método**: `GET`
* **Autenticação**: `Basic`

#### Saída

Este endpoint retorna a lista de todos os IDs de cronogramas associados à conta de usuário que faz a solicitação.

Veja a resposta de exemplo abaixo.

```json
{
    "schedules": [
        1764178033254455101,
        2885262175311057587,
        3251365810325795747,
        4134906379157007223,
        4164931482277157062
    ]
}
```

### Obter informações das execuções

#### Visão geral

Use este endpoint para obter informações sobre a lista de todas as execuções em um cronograma com os metadados de cada trabalho e a taxa de sucesso de cada execução.

* **Endpoint**: `https://data.oxylabs.io/v1/schedules/{id}/runs`
* **Método**: `GET`
* **Autenticação**: `Basic`

#### Saída

O payload abaixo contém uma resposta de exemplo do `/runs` endpoint.

```javascript
{
 "runs": [
        {
            "run_id": 25037485,
            "jobs": [
                {
                    "id": 7300439540206948353,
                    "create_status_code": 202,
                    "result_status": "done",
                    "created_at": "2025-02-26 09:00:21",
                    "result_created_at": "2025-02-26 09:00:23"
                },
                {
                    "id": 7300439540169188353,
                    "create_status_code": 202,
                    "result_status": "done",
                    "created_at": "2025-02-26 09:00:21",
                    "result_created_at": "2025-02-26 09:00:22"
                },
                {
                    "id": 7300439540198551553,
                    "create_status_code": 202,
                    "result_status": "done",
                    "created_at": "2025-02-26 09:00:21",
                    "result_created_at": "2025-02-26 09:00:23"
                }
            ],
            "success_rate": 1
        }
}
```

<table><thead><tr><th width="216">Chave</th><th>Descrição</th><th>Tipo</th></tr></thead><tbody><tr><td><code>execuções</code></td><td>Uma coleção de objetos de execução que representam instâncias de execução de uma tarefa ou fluxo de trabalho agendado.</td><td>Array</td></tr><tr><td><code>execuções</code>:<code>run_id</code></td><td>Um identificador único para a instância específica de execução.</td><td>Integer</td></tr><tr><td><code>execuções</code>:<code>jobs</code></td><td>Uma coleção de objetos de trabalho que foram executados como parte desta execução.</td><td>Array</td></tr><tr><td><code>execuções</code>:<code>success_rate</code></td><td>A proporção de trabalhos bem-sucedidos em relação ao total de trabalhos nesta execução (varia de 0 a 1).</td><td>Number</td></tr><tr><td><code>execuções</code>:<code>jobs</code>:<code>id</code></td><td>Um identificador único da Oxylabs para o trabalho específico.</td><td>Integer</td></tr><tr><td><code>execuções</code>:<code>jobs</code>:<code>create_status_code</code></td><td>Código de status HTTP retornado quando o trabalho foi criado, indicando a aceitação inicial da solicitação do trabalho.</td><td>Integer</td></tr><tr><td><code>execuções</code>:<code>jobs</code>:<code>result_status</code></td><td>O status de execução do trabalho (por exemplo, "done", "failed", "pending").</td><td>String</td></tr><tr><td><code>execuções</code>:<code>jobs</code>:<code>created_at</code></td><td>Timestamp quando o trabalho foi criado</td><td>String</td></tr><tr><td><code>execuções</code>:<code>jobs</code>:<code>result_created_at</code></td><td>Timestamp quando o trabalho foi concluído e produziu um resultado</td><td>String</td></tr></tbody></table>

### Obter trabalhos agendados

#### Visão geral

Use este endpoint para obter a lista de trabalhos de scraping executados como resultado da execução de um cronograma.&#x20;

* **Endpoint**: `https://data.oxylabs.io/v1/schedules/{id}/jobs`
* **Método**: `GET`
* **Autenticação**: `Basic`

#### Saída

O payload abaixo contém uma resposta de exemplo de informações do cronograma.

```json
{
    "jobs": [
        7300439540206948353,
        7300439540169188353,
        7300439540198551553,
        ...,
      ]
}
```

### Obter informações do cronograma

#### Visão geral

Use este endpoint para obter informações sobre um cronograma específico.&#x20;

* **Endpoint**: `https://data.oxylabs.io/v1/schedules/{id}`
* **Método**: `GET`
* **Autenticação**: `Basic`

#### Saída

O payload abaixo contém uma resposta de exemplo de informações do cronograma.

<pre class="language-json"><code class="lang-json">{
    "schedule_id": 1764178033254455101,
    "active": true,
    "items_count": 3,
    "cron": "0 3 * * 1",
    "end_time": "2032-12-21 12:34:45",
    "next_run_at": "2022-06-06 10:18:00",
<strong>    "links": [
</strong>        {
            "rel": "runs",
            "href": "/v1/schedules/1764178033254455101/runs",
            "method": "GET"
        },
        {
            "rel": "jobs",
            "href": "/v1/schedules/1764178033254455101/jobs",
            "method": "GET"
        }
    ],
    "stats": {
        "total_job_count": 3,
        "job_create_outcomes": [
            {
                "status_code": 202,
                "job_count": 3,
                "ratio": 1
            }
        ],
        "job_result_outcomes": [
            {
                "status": "done",
                "job_count": 2,
                "ratio": 0.67
            },
            {
                "status": "faulted",
                "job_count": 1,
                "ratio": 0.33
            }
        ]
    }
}
</code></pre>

<table><thead><tr><th width="216">Chave</th><th>Descrição</th><th>Tipo</th></tr></thead><tbody><tr><td><code>schedule_id</code></td><td>O ID único do cronograma.</td><td>Integer</td></tr><tr><td><code>active</code></td><td>O cronograma está ativo agora?</td><td>Boolean</td></tr><tr><td><code>items_count</code></td><td>O número de itens (trabalhos) no cronograma.</td><td>Integer</td></tr><tr><td><code>cron</code></td><td>A expressão cron associada ao cronograma.</td><td>String</td></tr><tr><td><code>end_time</code></td><td>O horário em que o cronograma deixará de ser repetido.</td><td>String</td></tr><tr><td><code>next_run_at</code></td><td>O horário em que o cronograma será executado em seguida.</td><td>String</td></tr><tr><td><code>links</code></td><td>Uma coleção de objetos de link que definem endpoints de API disponíveis relacionados a um recurso de cronograma.</td><td>Array</td></tr><tr><td><code>links</code>:<code>rel</code></td><td>O identificador de relacionamento que explica o propósito do link em relação ao recurso pai.</td><td>String</td></tr><tr><td><code>links</code>:<code>href</code></td><td>O caminho URL para o endpoint da API. Representa a localização do recurso que pode ser acessada.</td><td>String</td></tr><tr><td><code>links</code>:<code>método</code></td><td>O método HTTP a ser usado ao acessar este endpoint.</td><td>String</td></tr><tr><td><code>stats</code></td><td>Contém estatísticas de criação de trabalho e de conclusão de trabalho.</td><td>JSON Object</td></tr><tr><td><code>stats</code>:<code>total_job_count</code></td><td>O número de itens (trabalhos) no cronograma.</td><td>Integer</td></tr><tr><td><code>stats</code>:<code>job_create_outcomes</code></td><td>Contém estatísticas de criação de trabalho.</td><td>JSON Array</td></tr><tr><td><code>stats</code>:<code>job_create_outcomes</code>:<code>status_code</code></td><td>O código de status recebido em resposta a uma tentativa de executar o cronograma (criar um trabalho de scraping/parsing).</td><td>Integer</td></tr><tr><td><code>stats</code>:<code>job_create_outcomes</code>:<code>job_count</code></td><td>O número de tentativas de criação de trabalho que resultaram naquele código de status específico.</td><td>Integer</td></tr><tr><td><code>stats</code>:<code>job_create_outcomes</code>:<code>ratio</code></td><td>A proporção entre o número de tentativas de criação de trabalho que resultaram naquele status específico e o número total de tentativas de criação de trabalho.</td><td>Float</td></tr><tr><td><code>job_result_outcomes</code></td><td>Contém as estatísticas de resultado de trabalhos de scraping/parsing executados como parte do cronograma.</td><td>JSON Array</td></tr><tr><td><code>status</code></td><td>O status do trabalho. Valores possíveis: <code>pending</code> (o trabalho ainda está sendo processado), <code>done</code> (o trabalho foi concluído com sucesso), <code>faulted</code> (o trabalho falhou).</td><td>String</td></tr><tr><td><code>job_count</code></td><td>O número de trabalhos que resultaram naquele <code>status</code>.</td><td>Integer</td></tr><tr><td><code>ratio</code></td><td>A proporção entre o número de trabalhos com aquele status específico e o número total de trabalhos criados.</td><td>Float</td></tr></tbody></table>

### Desativar ou reativar um cronograma

#### Visão geral

Use este endpoint para ativar ou desativar um cronograma específico.

* **Endpoint**: `https://data.oxylabs.io/v1/schedules/{id}/state`
* **Método**: `PUT`
* **Autenticação**: `Basic`

#### Entrada

Use este endpoint para parar ou reiniciar um cronograma.&#x20;

Definindo `active` to `false`, você pode interromper a execução de um cronograma específico.&#x20;

Se você definir `active` to `true`, você pode reativar um cronograma previamente interrompido.

```json
{
  "active": false
}
```

**Saída**

```json
null
```

A resposta padrão é um corpo de resposta vazio com um `202` código de status.

## Códigos de resposta da API

Para códigos de resposta da API, consulte [**API**](https://developers.oxylabs.io/documentation/pt-br/solucoes-de-scraping/response-codes#api) seção.