API des statistiques de sécurité

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

L'API des statistiques de sécurité vous permet d'afficher des statistiques sur les abus et les bots au cours des 14 derniers jours. Il existe deux types de statistiques de sécurité :

Les statistiques tabulaires, qui n'ont pas de dimension temporelle. Les statistiques tabulaires sont souvent calculées à l'aide d'une fonction d'agrégation, par exemple sum for message_count ou bot_traffic.
Les statistiques de séries temporelles, qui ont une dimension temporelle.

Remarque : La détection des bots présente un délai de traitement d'environ 15 à 20 minutes en moyenne.

Paramètres dans des exemples d'appels d'API

Les sections suivantes présentent des exemples d'appels d'API qui utilisent l'API des statistiques de sécurité. Les appels d'API contiennent les paramètres suivants :

ORG : votre organisation
ENV : votre environnement.
METRIC_i : une métrique correspondant à la statistique. Consultez la section Fonctions de métriques et d'agrégation.
AGGREGATION_i : fonction d'agrégation pour la métrique. Consultez le tableau ci-dessous.
DIMENSION_i : une dimension permettant de regrouper les valeurs de la statistique.
PAGE_SIZE : nombre maximal de sous-composants renvoyés sur une seule page.
time_range : période des statistiques au format
```
"time_range": {
    "start_time": START_TIME,
    "end_time": END_TIME
}
```
où :
- START_TIME est l'heure de début de la période.
- END_TIME est l'heure de fin de la période.
START_TIME et END_TIME sont au format "YYYY-MM-DDT00:00:00Z".

La durée de la période ne peut pas dépasser 14 jours, et la date de début et la date de fin doivent être comprises dans les 365 derniers jours.

Exemple : Interroger les statistiques de sécurité tabulaires pour un environnement

Une requête qui interroge les statistiques tabulaires se présente au format suivant :

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
          }
        }'

Consultez la section Paramètres dans les exemples d'appels d'API.

Consultez la section Limites applicables aux statistiques de sécurité pour connaître le nombre maximal de métriques, de fonctions d'agrégation et de dimensions pouvant être incluses dans une requête.

Voici un exemple de requête qui interroge les statistiques tabulaires :

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
          }
        }'

Consultez la page de référence queryTabularStats pour obtenir la description de la requête et de la réponse.

Exemple : Interroger les statistiques de sécurité de séries temporelles pour un environnement

Les API de séries temporelles renvoient des statistiques de séries temporelles pour les métriques choisies, regroupées selon la dimension choisie.

L'appel suivant appelle les statistiques de série temporelle pour le trafic de bots, avec un regroupement par proxy d'API. Comme il existe quatre proxys, l'appel produit quatre séquences de points de séries temporelles. L'ordre des points de chaque ligne correspond à l'index correspondant dans le champ des colonnes.

Voici un exemple de requête :

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
          }
        }'

Consultez la section Paramètres dans les exemples d'appels d'API.

Consultez la page de référence queryTabularStats pour obtenir la description de la requête et de la réponse.

Exemple : Interroger les détails de l'incident pour la détection d'abus

L'exemple suivant interroge les détails d'un incident pour la détection d'utilisation abusive d'Advanced API Security. L'appel renvoie les informations sur le nombre de bots pour l'application de développeur pour un incident donné.

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
          }
        }'

Consultez la section Paramètres dans les exemples d'appels d'API.

La réponse renvoyée est semblable à celle-ci :

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

Consultez la page de référence queryTabularStats pour obtenir la description de la requête et de la réponse.

Métriques et fonctions d'agrégation

Le tableau suivant décrit les métriques et les fonctions d'agrégation disponibles dans l'API des statistiques de sécurité :

`Metric`	Description	`Aggregation function`
`bot`	Nombre d'adresses IP distinctes pour les bots détectés sur des intervalles d'une minute.	`count_distinct`
`bot_first_detected`	Date et heure auxquelles le bot a été détecté pour la première fois. Disponible uniquement via l'API.	`min`
`bot_last_detected`	Date et heure auxquelles le bot a été détecté pour la dernière fois. Disponible uniquement via l'API.	`max`
`bot_traffic`	Nombre de messages provenant d'adresses IP de bots détectés sur un intervalle d'une minute.	`sum`
`message_count`	Nombre total d'appels d'API traités par Apigee par intervalles d'une minute. Remarque : `message_count` ne peut pas être utilisé avec d'autres métriques du même rapport.	`sum`
`response_size`	Taille de la réponse.	`average`, `max`, `min` et `sum`

Dimensions

Les dimensions vous permettent de regrouper des valeurs de métriques en fonction des sous-ensembles de données associés. Le tableau suivant décrit les dimensions spécifiques aux rapports d'Advanced API Security.

Dimension	Description
`bot_reason`	Il peut s'agir de n'importe quelle combinaison des règles de détection de sécurité. `bot_reason` comprend le sous-ensemble de règles de détection correspondant au modèle de trafic du bot.
`incident_id` (aperçu)	UUID pour un incident de sécurité, qui est renvoyé par un appel à l'API Incidents. Consultez la section Exemple : Obtenir des détails ou un incident spécifique.
`security_action`	Action de sécurité. Les valeurs possibles sont `ALLOW`, `DENY` ou `FLAG`.
`security_action_name`	Nom de l'action de sécurité.
`security_action_headers`	En-têtes que vous pouvez utiliser pour interroger une action de sécurité de signalement.

Remarque : bot_reason et incident_id ne fonctionnent qu'avec les métriques suivantes :

bot
bot_traffic
response_size

Outre les dimensions décrites ci-dessus, Advanced API Security accepte également les dimensions suivantes :

access_token
access_token
api_product
apiproxy
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
proxy_basepath
proxy_pathsuffix
request_uri
response_status_code
target_url
useragent

Limites des statistiques de sécurité

L'API des statistiques de sécurité (séries tabulaires et séries temporelles) présente les limites suivantes :

Taille maximale de page : 14 400
Maximum de 10 dimensions de séries temporelles
Maximum de 15 dimensions de statistiques tabulaires
Maximum de 5 agrégations de métriques
Maximum de 5 agrégations de métriques de séries temporelles
Période : la durée ne peut pas dépasser 14 jours, et la date de début et la date de fin doivent être comprises dans les 365 derniers jours.
Les dimensions incident_id et bot_reason ne peuvent pas être utilisées avec les métriques message_count ou response_size.

Comparer l'API des statistiques de sécurité et l'API des rapports de sécurité

L'API des statistiques de sécurité et l'API des rapports de sécurité renvoient toutes les deux des statistiques d'utilisation abusive et des statistiques de sécurité liées aux bots, mais elles présentent les différences suivantes :

L'API des statistiques de sécurité est conçue pour afficher des statistiques sur le trafic récent des API. Les données de l'API des statistiques de sécurité ne remontent que jusqu'à 14 jours, mais vous pouvez les afficher immédiatement lorsque vous envoyez une requête.

Les statistiques de sécurité sont également affichées dans la vue des métriques d'utilisation abusive dans l'interface utilisateur d'Apigee.
L'API des rapports de sécurité est conçue pour afficher des statistiques sur les opérations de longue durée. Pour utiliser l'API des scores de sécurité, vous envoyez une tâche et ne pouvez consulter les résultats qu'une fois la tâche terminée. Les données de l'API des scores de sécurité remontent jusqu'à un an.