Utiliser les API de métriques

Vous consultez la documentation d'Apigee Edge.
Consultez la documentation Apigee X.
en savoir plus

Apigee Edge enregistre une grande variété de données opérationnelles et commerciales qui transitent par les API. Les métriques dérivées de ces données sont utiles pour surveiller les opérations et l'activité. À l'aide d'Edge API Analytics, vous pouvez, par exemple, déterminer quelles API fonctionnent bien ou mal, quels développeurs génèrent le trafic le plus important et quelles applications sont à l'origine du plus grand nombre de problèmes pour vos services de backend.

Pour faciliter l'accès à ces données de métriques, Edge expose une API RESTful. Vous pouvez utiliser l'API de métriques lorsque vous devez automatiser certaines fonctions Analytics, telles que la récupération périodique de métriques à l'aide d'un client ou d'un script d'automatisation. Vous pouvez également utiliser l'API pour créer vos propres visualisations sous la forme de widgets personnalisés que vous pouvez incorporer dans des portails ou des applications personnalisées.

Pour en savoir plus sur l'utilisation d'Analytics dans l'interface utilisateur de gestion d'API Edge, consultez la page Présentation de l'analyse d'API.

À propos des API de métriques

Edge fournit deux API de métriques:

  • Obtenir des métriques renvoie les métriques d'une organisation et d'un environnement sur une période donnée, telle qu'une heure, un jour ou une semaine.

    Par exemple, pour la semaine précédente, vous voulez obtenir :

    • Le nombre d'erreurs de stratégie
    • Le temps de réponse moyen
    • Le trafic total
  • Obtenir les métriques organisées par dimensions renvoie des métriques sur une période donnée pour une organisation et un environnement regroupées par dimension.

    Par exemple, pour la semaine précédente, vous utilisez des dimensions afin de regrouper les métriques par produit d'API, proxy d'API et e-mail de développeur pour obtenir :

    • Le nombre d'erreurs de stratégie par produit API
    • Le temps de réponse moyen par proxy d'API
    • Le trafic total par e-mail de développeur

    L'API Obtenir des métriques organisées par dimensions prend en charge des fonctionnalités supplémentaires non compatibles avec l'API Obtenir des métriques, notamment:

À propos des quotas de l'API de mesures

Edge applique les quotas suivants sur ces appels. Le quota est basé sur le système backend qui gère l'appel :

  • Postgres : 40 appels par minute
  • BigQuery : 12 appels par minute

Déterminez le système backend qui gère l'appel en examinant l'objet de réponse. Chaque objet de réponse contient une propriété metaData qui répertorie le service ayant géré l'appel dans la propriété Source. Par exemple, pour Postgres :

{
  ...
  "metaData": {
    "errors": [],
    "notices": [
      "Source:Postgres",
      "Table used: xxxxxx.yyyyy",
      "query served by:111-222-333"
    ]
  }
}

Pour BigQuery, la propriété Source est :

"Source:Big Query"

Si vous dépassez le quota d'appels, l'API renvoie une réponse HTTP 429.

Obtenir des métriques avec l'API de gestion

La principale différence entre les deux API est que l'API Obtenir des métriques renvoie des métriques brutes pour l'ensemble de l'organisation et de l'environnement, tandis que l'API Obtenir des métriques organisées par dimensions permet de regrouper des métriques en fonction de différents types d'entités, tels que le produit d'API, le développeur et l'application.

L'URL de requête pour l'API Obtenir des métriques est :

https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats

Pour l'API Obtenir des métriques organisées par dimensions, vous ajoutez une ressource supplémentaire à l'URL après /stats qui spécifie la dimension souhaitée :

https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/dimension

Par exemple, pour obtenir les métriques regroupées par proxy d'API, vous devez utiliser l'URL suivante pour appeler l'API de gestion:

https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/apiproxy

Spécifier les métriques à renvoyer

Pour les API Obtenir des métriques et Obtenir des métriques organisées par dimensions, vous devez utiliser le paramètre de requête select pour spécifier les metrics à récupérer, ainsi qu'une fonction d'agrégation facultative, au format suivant :

?select=metric

ou :

?select=aggFunction(metric)

Où :

  • métrique spécifie les données que vous voulez renvoyer. Par exemple, le nombre de requêtes API, de succès de cache (hit) ou d'erreurs de règle. Reportez-vous à la section metrics pour consulter un tableau spécifiant le nom de métrique à utiliser avec le paramètre de requête select.
  • aggFunction spécifie la fonction d'agrégation facultative exécutée sur la métrique. Par exemple, vous pouvez utiliser les fonctions d'agrégation suivantes avec la métrique de latence de traitement :

    • avg : renvoie la latence de traitement moyenne.
    • min : renvoie la latence de traitement minimale.
    • max : renvoie la latence de traitement maximale.
    • sum: renvoie la somme de toutes les latences de traitement.

    Les métriques ne prennent pas toutes en charge toutes les fonctions d'agrégation. La documentation sur les metrics contient un tableau spécifiant le nom de la métrique et la fonction (sum, avg, min, max) prise en charge par la métrique.

Par exemple, pour renvoyer le nombre moyen de transactions, c'est-à-dire les requêtes proxy d'API, par seconde :

?select=tps

Notez que cet exemple ne nécessite pas de fonction d'agrégation. L'exemple suivant utilise une fonction d'agrégation pour renvoyer la somme des succès de cache :

?select=sum(cache_hit)

Vous pouvez renvoyer plusieurs métriques pour un seul appel d'API. Afin d'obtenir des métriques pour la somme des erreurs de règle et la taille moyenne de la requête, définissez le paramètre de requête select à l'aide d'une liste de métriques séparées par une virgule :

?select=sum(policy_error),avg(request_size)

Spécifier la période

L'API de métriques renvoie des données pour une période spécifiée. Utilisez le paramètre de requête timeRange pour spécifier la période, au format suivant :

?timeRange=MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM

Notez le caractère %20 figurant avant HH:MM. Le paramètre timeRange requiert un caractère d'espace encodé au format URL avant HH:MM ou un caractère +, comme dans cet exemple : MM/DD/YYYY+HH:MM~MM/DD/YYYY+HH:MM.

Exemple :

?timeRange=03/01/2018%2000:00~03/30/2018%2023:59

N'utilisez pas 24:00 en tant qu'heure car elle s'articule sur 00:00. Utilisez plutôt 23:59.

Utiliser un délimiteur

Pour séparer plusieurs dimensions dans un appel d'API, utilisez une virgule (,) comme délimiteur. Par exemple, dans l'appel d'API

curl https://api.enterprise.apigee.com/v1/o/myorg/e/prod/stats/apis,apps?select=sum(message_count)&timeRange=9/24/2018%2000:00~10/25/2018%2000:00&timeUnit=day

les dimensions apis et apps sont séparées par ,.

Exemples d'appels d'API

Cette section contient des exemples utilisant les API Obtenir des métriques et Obtenir des métriques organisées par dimensions. Pour obtenir des exemples supplémentaires, consultez les exemples d'API de métriques.

Renvoyer le nombre total d'appels passés à vos API pendant un mois

Pour afficher le nombre total d'appels passés à toutes les API de votre organisation et de votre environnement pendant un mois, utilisez l'API Obtenir des métriques :

curl -v "https://api.enterprise.apigee.com/v1/o/{org}/e/{env}/stats/?select=sum(message_count)&timeRange=03/01/2018%2000:00~03/31/2018%2023:59" \
-u email:password

Exemple de réponse :

{
  "environments": [
    {
      "metrics": [
        {
          "name": "sum(message_count)",
          "values": [
            "7.44944088E8"
          ]
        }
      ],
      "name": "prod"
    }
  ],
...
}

Renvoie le nombre total de messages par proxy d'API pour deux jours.

Dans cet exemple, vous renvoyez des métriques pour le nombre de requêtes reçues par tous les proxys d'API sur une période de deux jours. Le paramètre de requête select définit la fonction d'agrégation sum pour la métrique message_count sur la dimension apiproxy. Le rapport renvoie le débit de message de requête pour toutes les API concernant le trafic reçu entre le début du 20/06/2018 et la fin du 21/06/2018, au format UTC :

curl  https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59" \
-u email:password

Exemple de réponse :

{
  "environments" : [ {
    "dimensions" : [ {
      "metrics" : [ {
        "name" : "sum(message_count)",
        "values" : [ {
          "timestamp" : 1498003200000,
          "value" : "1100.0"
        } ]
      } ],
      "name" : "target-reroute"
    } ],
    "name" : "test"
  } ]...
}

Cette réponse indique que 1 100 message a été reçu par un proxy d'API appelé "target-reroute" s'exécutant dans l'environnement de test entre le début du 20/06/2018 et la fin du 21/06/2018.

Pour obtenir des statistiques pour d'autres dimensions, spécifiez une autre dimension en tant que paramètre URI. Par exemple, vous pouvez spécifier la dimension developer_app pour récupérer les métriques des applications de développeur. L'appel d'API suivant renvoie le débit total (messages reçus) de toutes les applications pour l'intervalle de temps spécifié :

curl  https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/developer_app?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59&timeUnit=day" \
-u email:password

Exemple de réponse :

{
  "environments": [
    {
      "dimensions": [
        {
          "metrics": [
            {
              "name": "sum(message_count)",
              "values": [
                {
                  "timestamp": 1498003200000,
                  "value": "886.0"
                }
              ]
            }
          ],
          "name": "Test-App"
        },
        {
          "metrics": [
            {
              "name": "sum(message_count)",
              "values": [
                {
                  "timestamp": 1498003200000,
                  "value": "6645.0"
                }
              ]
            }
          ],
          "name": "johndoe_app"
        },
        {
          "metrics": [
            {
              "name": "sum(message_count)",
              "values": [
                {
                  "timestamp": 1498003200000,
                  "value": "1109.0"
                }
              ]
            }
          ],
          "name": "marys_app"
        }
  ]...
}

Trier les résultats par classement relatif

Bien souvent, lorsque vous récupérez des métriques, vous ne souhaitez obtenir des résultats que pour un sous-ensemble de données. Généralement, vous souhaitez obtenir un "top 10" (par exemple, les "10 API les plus lentes", les "10 applications les plus actives", etc.). Pour cela, vous pouvez utiliser le paramètre de requête topk dans le cadre de la requête.

Par exemple, vous voudrez peut-être savoir qui sont vos principaux développeurs, mesurés par leur débit, ou quelles sont vos API cibles aux pires performances (c'est-à-dire, les plus lentes) par latence.

Le paramètre topk (signifiant le "top k" des entités) permet de générer des rapports sur les entités associées à la valeur la plus élevée pour une métrique donnée. Cela vous permet de filtrer les métriques pour une liste d'entités illustrant une condition particulière. Par exemple, pour identifier l'URL cible la plus sujette aux erreurs la semaine dernière, le paramètre topk est ajouté à la requête, avec la valeur 1:

curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/target_url?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&topk=1" \
  -u email:password
{
  "environments": [
    {
      "dimensions": [
        {
          "metrics": [
            {
              "name": "sum(is_error)",
              "values": [
                {
                  "timestamp": 1494201600000,
                  "value": "12077.0"
                }
              ]
            }
          ],
          "name": "http://api.company.com"
        }
      ]...
}

Le résultat de cette requête est un ensemble de métriques indiquant que l'URL cible comportant le plus de bugs est http://api.company.com.

Vous pouvez également utiliser le paramètre topk pour trier les API présentant le débit le plus élevé. L'exemple suivant récupère des métriques sur l'API la mieux classée, définie par le débit le plus élevé de la semaine précédente :

curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(message_count)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=day&sortby=sum(message_count)&sort=DESC&topk=1" \
-u email:password

Exemple de réponse

{
  "environments": [
    {
      "dimensions": [
        {
          "metrics": [
            {
              "name": "sum(message_count)",
              "values": [
                {
                  "timestamp": 1494720000000,
                  "value": "5750.0"
                },
                {
                  "timestamp": 1494633600000,
                  "value": "5752.0"
                },
                {
                  "timestamp": 1494547200000,
                  "value": "5747.0"
                },
                {
                  "timestamp": 1494460800000,
                  "value": "5751.0"
                },
                {
                  "timestamp": 1494374400000,
                  "value": "5753.0"
                },
                {
                  "timestamp": 1494288000000,
                  "value": "5751.0"
                },
                {
                  "timestamp": 1494201600000,
                  "value": "5752.0"
                }
              ]
            }
          ],
          "name": "testCache"
        }
      ],
      "name": "test"
    }
  ]...
}

Filtrer les résultats

Pour plus de précision, vous pouvez filtrer les résultats afin de limiter les données renvoyées. Lorsque vous utilisez des filtres, vous devez utiliser les dimensions en tant que propriétés de filtre.

Par exemple, supposons que vous deviez récupérer le nombre d'erreurs des services de backend filtrées selon le verbe HTTP de la requête. Votre objectif est de déterminer combien de requêtes POST et PUT génèrent des erreurs par service de backend. Pour ce faire, utilisez la dimension target_url avec le filtre request_verb :

curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/target_url?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&filter=(request_verb%20in%20'POST','PUT')" \
-u email:password

Exemple de réponse :

{
  "environments" : [
    {
      "dimensions" : [
        {
          "metrics" : [
            {
              "name" : "sum(is_error)",
              "values" : [
                {
                  "timestamp" : 1519516800000,
                  "value" : "1.0"
                }
              ]
          }
        ],
        "name" : "testCache"
        }
      ],
      "name" : "test"
    }
  ]...
}

Pagination des résultats

Dans les environnements de production, certaines requêtes adressées à l'API d'analyse Edge renvoient des jeux de données très volumineux. Pour faciliter l'affichage de grands ensembles de données dans le contexte d'une application basée sur une interface utilisateur, l'API permet d'effectuer une pagination de manière native.

Pour paginer les résultats, utilisez les paramètres de requête offset et limit, ainsi que le paramètre de tri sortby pour garantir un ordre cohérent des éléments.

Par exemple, la requête suivante renverrait probablement un ensemble de données volumineux, car elle extrait les métriques de toutes les erreurs de toutes les API de l'environnement de produit pour la semaine écoulée.

curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)" \
-u email:password

Si votre application basée sur l'interface utilisateur peut raisonnablement afficher 50 résultats par page, vous pouvez définir la limite sur 50. Comme 0 compte comme premier élément, l'appel suivant renvoie les éléments 0 à 49 dans l'ordre décroissant (sort=DESC est la valeur par défaut).

curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&limit=50&offset=0" \
-u email:password

Pour la deuxième "page" de résultats, utilisez le paramètre de requête offset comme suit. Notez que les paramètres limit et offset sont identiques, car la valeur 0 est considérée comme étant le premier élément. Si le paramètre limit est défini sur 50 et que le paramètre offset est défini sur 0, les éléments 0 à 49 sont renvoyés. Si le paramètre offset est défini sur 50, les éléments 50 à 99 sont renvoyés.

curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&limit=50&offset=50" \
-u email:password