Esta página foi traduzida pela API Cloud Translation.

API de estatísticas de segurança

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

A API Security Stats permite-lhe ver estatísticas relacionadas com abusos e bots nos últimos 14 dias. Existem dois tipos de estatísticas de segurança:

Estatísticas tabulares, que não têm uma dimensão de tempo. As estatísticas tabulares são frequentemente calculadas através de uma função de agregação, por exemplo, sum for message_count ou bot_traffic.
Estatísticas de séries cronológicas, que têm uma dimensão de tempo.

Nota: a deteção de bots tem um atraso de processamento de cerca de 15 a 20 minutos, em média.

Parâmetros em exemplos de chamadas API

As secções seguintes dão exemplos de chamadas da API que usam a API security stats. As chamadas da API contêm os seguintes parâmetros:

ORG: a sua organização.
ENV: o seu ambiente.
METRIC_i: uma métrica para a estatística. Consulte as Métricas e funções de agregação.
AGGREGATION_i: uma função de agregação para a métrica. Consulte a tabela abaixo.
DIMENSION_i: uma dimensão para agrupar os valores da estatística.
PAGE_SIZE: número máximo de subcomponentes devolvidos numa única página.
time_range: o intervalo de tempo das estatísticas no formulário
```
"time_range": {
    "start_time": START_TIME,
    "end_time": END_TIME
}
```
where:
- START_TIME é a hora de início do intervalo de tempo.
- END_TIME é a hora de fim do intervalo de tempo.
START_TIME e END_TIME têm o formato "YYYY-MM-DDT00:00:00Z".

O intervalo de tempo pode ter, no máximo, 14 dias, e a data de início e a data de fim têm de estar nos últimos 365 dias.

Exemplo: consultar estatísticas de segurança tabulares para um ambiente

Um pedido que consulta estatísticas tabulares tem o seguinte formato:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTabularStats" \
       -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" -X POST -d \
       '{ "metrics": [{"metric": "METRIC_1", "aggregation": "AGGREGATION_1",
                      {"metric": "METRIC_2", "aggregation": "AGGREGATION_2"}],
          "dimensions": ["DIMENSION_1",  "DIMENSION_2"],
          "page_size": PAGE_SIZE,
          "time_range": {
              "start_time": START_TIME,
              "end_time": END_TIME
          }
        }'

Consulte Parâmetros em exemplos de chamadas da API.

Consulte as Limitações nas estatísticas de segurança para ver os números máximos de métricas, funções de agregação e dimensões que podem ser incluídos num pedido.

Segue-se um exemplo de um pedido que consulta estatísticas tabulares:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTabularStats" \
       -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" -X POST -d \
       '{ "metrics": [{"metric": "bot", "aggregation": "count_distinct"},
                      {"metric": "bot_traffic", "aggregation": "sum"},
                      {"metric": "bot_first_detected", "aggregation": "min"},
                      {"metric": "bot_last_detected", "aggregation": "max"}],
          "dimensions": ["apiproxy",  "bot_reason", "ax_resolved_client_ip",  "ax_geo_city",  "ax_geo_country",  "client_id",  "proxy_basepath", "proxy_pathsuffix"],
          "page_size": 1,
          "time_range": {
            "start_time": START_TIME,
            "end_time": END_TIME
          }
        }'

Consulte a página de referência para ver descrições do pedido e da resposta.queryTabularStats

Exemplo: consultar estatísticas de segurança de séries cronológicas para um ambiente

As APIs de séries cronológicas devolvem estatísticas de séries cronológicas para as métricas escolhidas, agrupadas pela dimensão escolhida.

A seguinte chamada invoca estatísticas de séries cronológicas para o tráfego de bots agrupado por proxy de API. Como existem 4 proxies, isto gera 4 sequências de pontos de séries cronológicas. A ordem dos pontos de cada linha corresponde ao índice correspondente no campo das colunas.

Segue-se um pedido de exemplo:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTimeSeriesStats" \
       -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" -X POST -d \
       '{ "metrics": [{"metric": "METRIC_1", "aggregation": "AGGREGATION_1", "order": "ORDER"}],
          "dimensions": ["DIMENSION_1"], "window_size": "WINDOW_SIZE",
          "page_size": PAGE_SIZE,
          "time_range": {
            "start_time": START_TIME,
            "end_time": END_TIME
          }
        }'

Consulte Parâmetros em exemplos de chamadas da API.

Consulte a página de referência para ver descrições do pedido e da resposta.queryTabularStats

Exemplo: consultar detalhes de incidentes para deteção de abuso

O exemplo seguinte consulta os detalhes de um incidente para a deteção de abuso da API Advanced Security. A chamada devolve detalhes sobre a quantidade de bots para a app do programador para um determinado incidente.

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTabularStats" \
       -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" -X POST -d  \
       '{"metrics": [{"metric": "bot_traffic", "aggregation": "sum"}],
         "dimensions": ["incident_id", "developer_app"],
          "filter": "incident_id eq '\''d897d1af-51ac-4b5d-a29e-d1059d922a05'\''",
          "page_size": 100,
          "time_range": {
            "start_time": START_TIME,
            "end_time": END_TIME
          }
        }'

Consulte Parâmetros em exemplos de chamadas da API.

Isto devolve uma resposta como a seguinte:

{
  "values": [
    [
      "d897d1af-51ac-4b5d-a29e-d1059d922a05",
      "Developer2_App1",
      18353
    ],
    [
      "d897d1af-51ac-4b5d-a29e-d1059d922a05",
      "Developer1_App1",
      18082
    ]
  ],
  "columns": [
    "incident_id",
    "developer_app",
    "bot_traffic"
  ]
}

Consulte a página de referência para ver descrições do pedido e da resposta.queryTabularStats

Métricas e funções de agregação

A tabela seguinte descreve as métricas e as funções de agregação disponíveis na API de estatísticas de segurança:

`Metric`	Descrição	`Aggregation function`
`bot`	O número de endereços IP distintos para bots detetados em intervalos de 1 minuto.	`count_distinct`
`bot_first_detected`	Data e hora em que o bot foi detetado pela primeira vez. Disponível apenas através da API.	`min`
`bot_last_detected`	Data e hora da última deteção do bot. Disponível apenas através da API.	`max`
`bot_traffic`	O número de mensagens de endereços IP de bots detetados em intervalos de um minuto.	`sum`
`message_count`	O número total de chamadas de API processadas pelo Apigee em intervalos de um minuto. Nota: `message_count` não pode ser usada com outras métricas no mesmo relatório.	`sum`
`response_size`	Tamanho da resposta.	`average`, `max`, `min`, `sum`

Dimensões

As dimensões permitem agrupar valores de métricas com base em subconjuntos de dados relacionados. A tabela seguinte descreve as dimensões específicas dos relatórios de segurança avançada da API:

Dimensão	Descrição
`bot_reason`	Pode ser qualquer combinação das regras de deteção de segurança. `bot_reason` consiste no subconjunto das regras de deteção que corresponderam ao padrão de tráfego do bot.
`incident_id` (pré-visualização)	O UUID de um incidente de segurança, que é devolvido por uma chamada à API Incidents. Consulte Exemplo: obter detalhes ou um incidente específico.
`security_action`	A ação de segurança. Os valores possíveis são `ALLOW`, `DENY` ou `FLAG`.
`security_action_name`	O nome da ação de segurança.
`security_action_headers`	Cabeçalhos que pode usar para consultar uma ação de segurança de flag.

Nota: bot_reason e incident_id só funcionam com as seguintes métricas:

bot
bot_traffic
response_size

Além das dimensões descritas acima, a segurança avançada da API também suporta as seguintes dimensões:

access_token
api_product
apiproxy
app_group_app
app_group_name
ax_edge_execution_fault_code
ax_geo_city
ax_geo_continent
ax_geo_country
ax_geo_region
ax_isp
ax_resolved_client_ip
ax_ua_agent_version
client_id
developer
developer_app
developer_email
environment
is_filtered_out
proxy_basepath
proxy_pathsuffix
request_uri
response_status_code
target_url
useragent

Limitações nas estatísticas de segurança

A API de estatísticas de segurança (tabular e de séries cronológicas) tem os seguintes limites:

Tamanho máximo da página: 14400
Máximo de 10 dimensões de séries cronológicas
Máximo de 15 dimensões de estatísticas tabulares
Máximo de 5 agregações de métricas.
Máximo de 5 agregações de métricas de intervalos temporais
Intervalo de tempo: a duração pode ser de, no máximo, 14 dias, e a data de início e a data de fim têm de estar nos últimos 365 dias.
Não é possível usar as dimensões incident_id e bot_reason com as métricas message_count ou response_size.
A dimensão is_filtered_out só é suportada por estatísticas tabulares e aplica-se também a dados antigos.

Comparar a API de estatísticas de segurança e a API de relatórios de segurança

Tanto a API de estatísticas de segurança como a API de relatórios de segurança devolvem estatísticas de segurança relacionadas com abuso e bots, mas têm as seguintes diferenças:

A API de estatísticas de segurança foi concebida para ver estatísticas sobre o tráfego recente da API. Os dados da API de estatísticas de segurança só remontam a 14 dias, mas pode ver as estatísticas imediatamente quando envia um pedido.

As estatísticas de segurança também são apresentadas na vista Métricas de abuso na IU do Apigee.
A API de relatórios de segurança foi concebida para ver estatísticas de operações de longa duração. Para usar a API de classificações de segurança, envia uma tarefa e vê os resultados apenas quando a tarefa estiver concluída. Os dados da API de pontuações de segurança remontam a um ano.