# Como consultar dados do Bot Manager com a GraphQL API

O conjunto de dados **botManagerMetrics** fornece acesso a dados agregados em tempo real da atividade do Azion Bot Manager, relacionados ao tráfego de bots, ações e comportamento em suas aplicações. Este conjunto de dados faz parte da GraphQL API do Real-Time Metrics e é gerado a partir das requisições analisadas e identificadas como bots, sejam eles bons ou maliciosos, ou tráfego legítimo.

Essas informações podem ser acessadas através da API GraphQL. Além disso, esses dados são retidos e disponíveis por até *2 anos*.

Este guia explicará como consultar dados do Bot Manager usando o playground GraphiQL.

:::note
Para recuperar esses dados, você deve estar inscrito no Azion Bot Manager e usar a [API GraphQL](/pt-br/documentacao/devtools/graphql-api/visao-geral/). Entre em contato com a [equipe de vendas](https://www.azion.com/pt-br/contato/) para mais detalhes sobre a assinatura.
:::

---

## Consultando dados

Para consultar seus dados, siga os passos:

1. Acesse o GraphiQL Playground visitando o link `https://api.azion.com/v4/metrics/graphql`.
    - Você deve estar logado na sua conta Azion. Caso contrário, você receberá uma mensagem de erro.
2. Envie uma query seguindo este formato:

```graphql
query {
  botManagerMetrics(
    filter: {
      tsRange: {
        begin: "2024-09-23T15:00:00"
        end: "2024-09-23T17:00:00"
      }
    }
    aggregate: {
      sum: requests
    }
    orderBy: [ts_ASC]
    groupBy: [ts, action, botCategory, botMode, classified]
    limit: 10000
  ) {
    action
    botCategory
    botMode,
    classified
    sum
  }
}
```

Onde:

| Campo | Descrição |
|----------|----------|
| `filter` | Define os critérios usados para filtrar os dados retornados pela consulta |
| `tsRange` | Um subcampo de `filter`. Especifica um intervalo de tempo para filtrar dados. Inclui os campos `begin` e `end` para definir os timestamps de início e fim. Formato: `"YYYY-MM-DDTHH:mm:ss"`; exemplo: `"2024-04-11T00:00:00"` |
| `sum: requests` | Retorna o número total de requisições avaliadas dentro do intervalo de tempo especificado, após aplicar quaisquer filtros |
| `orderBy` | Especifica a ordem em que os resultados devem ser retornados. Exemplos: `[ts_DESC]`, para ordem decrescente, e `[ts_ASC]`, para ordem crescente |
| `groupBy` | Especifica os campos pelos quais os resultados da consulta devem ser agrupados. Exemplo: `[ts]` |
| `limit` | Especifica o número máximo de resultados a serem retornados. Máximo do sistema: `10000` |

:::note
Este exemplo recupera dados para `action`, `botCategory`, `botMode`, `classified` e o total (`sum`) de requisições identificadas como bots durante o intervalo de tempo especificado, agrupados pelos campos selecionados. Para saber mais sobre os campos disponíveis, consulte a [documentação dos Campos da GraphQL API do Real-Time Metrics](/pt-br/documentacao/devtools/graphql-api/recursos/campos-gql-real-time-metrics/)
:::

3. Você receberá uma resposta JSON semelhante a esta:

```json
{
  "data": {
    "botManagerMetrics": [
      {
        "action": "allow",
        "botCategory": "Enterprise Bot",
        "botMode": "web",
        "classified": "good bot",
        "sum": 6
      },
      {
        "action": "allow",
        "botCategory": "Brute Force",
        "botMode": "web",
        "classified": "bad bot",
        "sum": 325
      },
      {
        "action": "allow",
        "botCategory": "Bad Bot Signatures",
        "botMode": "web",
        "classified": "bad bot",
        "sum": 68
      },
      {
        "action": "allow",
        "botCategory": "Non-Bot Like",
        "botMode": "web",
        "classified": "legitimate",
        "sum": 34359
      },
      {
        "action": "redirect",
        "botCategory": "Bad Bot Signatures",
        "botMode": "web",
        "classified": "bad bot",
        "sum": 703
      },
      {
        "action": "allow",
        "botCategory": "Monitoring Bot",
        "botMode": "web",
        "classified": "good bot",
        "sum": 8
      },
      {
        "action": "allow",
        "botCategory": "Bad Bot Signatures",
        "botMode": "web",
        "classified": "under evaluation",
        "sum": 2902
      },
      {
        "action": "redirect",
        "botCategory": "Malicious Browser Behavior",
        "botMode": "web",
        "classified": "bad bot",
        "sum": 17
      },
      {
        "action": "allow",
        "botCategory": "Scripted Bots",
        "botMode": "web",
        "classified": "bad bot",
        "sum": 1
      }
    ]
  }
}
```

Onde: 

| Campo | Descrição |
|----------|----------|
| `action` | Ação realizada pelo Azion Bot Manager para acessos identificados como bots |
| `botCategory` | Categoria de bot identificada na requisição. Exemplo: `scraping`, `crawling`, `brute-force` |
| `botMode` | Modo de proteção contra bots utilizado na requisição. Exemplo: `Web` |
| `classified` | Identificação do tráfego, sendo `bad bot`, `good bot`, `legitimate` ou `under evaluation` os valores possíveis |
| `sum` | Número total de requisições para cada combinação específica de atributos. Cada objeto na resposta agrupa as requisições com base nesses atributos |

:::tip
Para saber mais sobre os campos disponíveis, consulte a [documentação dos Campos da API GraphQL do Real-Time Metrics](/pt-br/documentacao/devtools/graphql-api/recursos/campos-gql-real-time-metrics/).
:::