Nous recommandons vivement, avant de commencer à utiliser l'API de Cato, de bien vouloir consulter la Politique de Support pour l'API de Cato.

Aperçu de accountMetrics

La requête accountMetrics vous aide à analyser l'état et la qualité des connexions des sites et des utilisateurs SDP au Cloud Cato. Ces données concernent le trafic à l'intérieur du tunnel DTLS entre le site et le Cloud Cato.

accountMetrics montre des mesures historiques, statistiques et analytiques pour le compte. Il retourne des données similaires à la fenêtre Connectivité de Site dans l'Application de Gestion Cato.

Pour les comptes revendeurs, vous pouvez créer des clés API distinctes à l'intérieur de chaque compte client que vous connectez à l'API Cato. Pour en savoir plus sur la limitation du débit et la requête API accountMetrics, consultez Comprendre la Limitation de Débit de l'API Cato.

Working with Bucket Granularity and API Query Limits

There is a maximum limit of 100,000 returned items per accountMetrics API query. Si une requête atteint cette limite, alors la requête ne retourne pas de données supplémentaires et un message d'erreur s'affiche.

Cato calcule cette limite en multipliant les éléments suivants :

• Nombre total de sites plus utilisateurs de VPN
• Nombre de mesures (étiquettes API/télémétrie)
• Nombre de buckets

In other words, the sum of (sites + VPN users) * (metrics) * (buckets) must be less than 100,000. Par exemple, la requête suivante produira une erreur :

• 10 sites
• 140 VPN users
• 5 mesures
• 150 buckets

(10 + 140) * 5 * 150 = 112,500 items in the query. Dans cet exemple, vous pouvez réduire le nombre de buckets pour exécuter la requête avec succès.

For more about the types of API labels, see Cato API - AccountMetrics > Timeseries.

Calcul de la Granularité Minimale pour une Requête

This section explains how to calculate the minimum granularity (bucket size) based on the time frame for the query.

1. Cadre temporel - Convertir le cadre temporel en secondes
2. Limite de bucket - Calculer la limite de bucket basée sur 100000 / ( (sites + utilisateurs VPN) * (mesures) )
3. Granularité Minimale = (cadre temporel) / (limite de bucket)

Par exemple, la première ligne dans le tableau ci-dessous montre la limite de requête pour 7 jours, 100 sites et utilisateurs VPN, avec 5 mesures :

• 7 days = 604,800 seconds
• 200 buckets = 10000 / (100) * (5)
• 3024 secondes de granularité minimale = 604800 / 200

Le tableau suivant montre des exemples de configurations pour la requête accountMetrics avec la granularité minimale des buckets :

Détails pour les Champs de accountMetrics

Voici les détails que les champs de accountMetrics peuvent retourner pour la requête :

• ID - ID de compte
• de - heure de début
• à - heure de fin
• granularité - taille du bucket
• sites -données renvoyées pour chaque site (tableau avec requêtes et champs imbriqués)
• séries temporelles - cadre de temps pour les données, et définit la relation entre les buckets et les données (tableau avec requêtes et champs imbriqués)

accountMetrics ID

The ID field shows the unique account internal ID.

This account ID isn't shown in the Cato Management Application, instead it is the number in the URL for the Cato Management Application. For example, the account ID is 26 for the following URL: https://cc2.catonetworks.com/#!/26/topology.

accountMetrics From

Le champ De montre l'heure de début pour les données de la requête et est défini dans l'argument timeFrame.

accountMetrics To

Le champ À montre l'heure de fin pour les données de la requête et est défini dans l'argument timeFrame.

accountMetrics Granularity

Le champ Granularité montre la durée en secondes pour un seul bucket de mesures. Le nombre de buckets est défini dans l'argument séries temporelles > bucket.

La Granularité est calculée selon la formule suivante : timeFrame/buckets. For example, if the query is returning five minutes of data (timeFrame) with 60 buckets, then the Granularity (bucket size) is 5 seconds (300 seconds / 60).

La Granularité minimale pour un bucket est de 5 secondes. Lorsque la Granularité du bucket est inférieure à 5 secondes, il est possible qu'aucune donnée ne soit retournée pour ce bucket.

Pour plus d'informations sur le champ Granularité, consultez Travailler avec accountMetrics > Granularité.

accountMetrics Sites

Le champ Sites contient des données liées à un ou plusieurs sites dans le compte. You can also specify data for VPN users with their user IDs.

Pour plus d'informations sur le champ Sites pour accountMetrics, consultez Cato API - AccountMetrics > Sites.

accountMetrics Timeseries

Montre les mesures pour le compte selon le cadre temporel spécifié (buckets) dans la requête, et inclut des statistiques et mesures historiques. Ces données sont similaires au champ fenêtre Connectivité de Site dans l'Application de Gestion Cato pour chaque site.

Pour plus d'informations sur le champ séries temporelles pour accountMetrics, consultez Cato API - AccountMetrics > Séries Temporelles.

Arguments pour accountMetrics

Voici les arguments que vous pouvez transmettre et définir les données renvoyées par la requête :

• accountID - ID de compte
• ID - ID de compte (argument hérité)
• cadre temporel - heure de début et de fin de la requête
• groupInterfaces - Combiner les analyses pour les liens en un seul lien (pour la valeur booléenne true)
• groupDevices - Pour plusieurs sites, et un seul site avec plusieurs Sockets, combiner les analyses en un seul Socket (pour la valeur booléenne true)

accountMetrics accountID Argument

Entrez l'ID de compte pour les données que la requête renvoie. Cet argument est obligatoire.

This account ID isn't shown in the Cato Management Application, instead it is the number in the URL for the Cato Management Application. For example, the account ID is 26 for the following URL: https://cc2.catonetworks.com/#!/26/topology.

accountMetrics timeFrame Argument

Entrez le cadre temporel pour les données que la requête renvoie. L'argument est au format <type>.<time value>. Cet argument est obligatoire.

Voici les options prises en charge pour définir le cadre temporel :

• dernier.<durée du temps> - La valeur <durée du temps> pour le type dernier est conforme à ISO-8601 et renvoie des données pour les temps spécifiques précédents. Par exemple :
  • timeFrame = last.PT5M montre les 5 dernières minutes
  • timeFrame = last.PT2H montre les 2 dernières heures
  • timeFrame = last.P1D montre le jour précédent 1
  • timeFrame = last.P3M montre les 3 mois précédents
  • timeFrame = last.P1Y montre l'année précédente 1
• utc.<short-time-frame-spec> - Le cadre temporel combine une date de début et de fin au format AA-MM-JJ/hh:mm:ss selon le fuseau horaire spécifié. Vous devez entrer toutes les valeurs de date et d'heure pour l'argument. Par exemple :
  • timeFrame = utc.2020-02-{11/04:50:00--21/04:50:00} montre 10 jours de données analytiques du 11 février 2020 4:50:00 am au 21 février 2020 4:50:00 am
  • timeFrame = utc.2020-02-11/{04:50:15--16:50:15} montre 12 heures de données analytiques le 11 février 2020 de 4:50:15 am à 16:50:15 pm
  • timeFrame = utc.2020-{02-11/04:50:00--04-11/04:50:00} montre 2 mois de données analytiques du 11 février 2020 4:50:00 am au 11 avril 4:50:00 am
  • timeFrame = utc.{2019-10-01/04:50:00--2020-02-01/04:50:00} montre 4 mois de données analytiques du 1 octobre 2019 4:50:00 am au 11 février 2020 4:50:00 am

    Ce format vous permet de configurer un cadre temporel incluant plus d'une année civile

Pour en savoir plus sur l'argument timeFrame et le champ Granularité, voir Travailler avec accountMetrics > Granularity.

Argument groupInterfaces de accountMetrics

Lorsque l'argument booléen groupInterfaces est défini sur true, les données de toutes les interfaces sont agrégées en une seule interface.

Argument groupDevices de accountMetrics

Lorsque l'argument booléen groupDevices est défini sur true, les analyses pour tous les Sockets (généralement deux en haute disponibilité) sont agrégées en un seul résultat. Pour obtenir les meilleurs résultats pour Sockets agrégés, nous recommandons que les noms et fonctionnalités (par exemple Destination) pour les liens des deux Sockets soient cohérents.