Utiliser l'API de métriques

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

Consultez la documentation d'Apigee Edge.

Apigee enregistre une grande variété de données d'entreprise et opérationnelles qui transitent par des API. Les métriques dérivées de ces données sont utiles pour surveiller les opérations et l'activité. Apigee Analytics vous permet, par exemple, de déterminer quelles API fonctionnent correctement ou non, quels développeurs génèrent le trafic le plus important et quelles applications créent le plus de problèmes pour vos services de backend.

Pour faciliter l'accès à ces données de métriques, utilisez l'API de métriques lorsque vous devez automatiser certaines fonctions d'analyse, telles que l'extraction périodique de métriques à l'aide d'un client ou d'un script automatisé. 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 apprendre à utiliser Analytics dans l'UI Apigee, consultez la page Présentation de Apigee Analytics.

À propos de l'API de métriques

Vous pouvez utiliser l'API de métriques de deux manières :

  • Obtenir des métriques pour une organisation et un environnement sur une période donnée, par exemple une heure, un jour ou une semaine. Cette méthode renvoie des métriques brutes pour l'ensemble de l'organisation et de l'environnement.

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

    • Nombre d'erreurs de règle
    • Temps de réponse moyen
    • Trafic total

  • Obtenir des métriques classées par dimension sur une période donnée pour une organisation et un environnement.

    Par exemple, pour la semaine passée, vous pouvez utiliser les dimensions de produit d'API, de proxy d'API et d'adresse e-mail de développeur pour obtenir les métriques suivantes :

    • Nombre d'erreurs de règle par produit d'API
    • Temps de réponse moyen par proxy d'API
    • Trafic total par adresse e-mail de développeur

    Pour gérer le résultat renvoyé, l'API de métriques est compatible avec les fonctionnalités suivantes :

    Pour en savoir plus, consultez la documentation de référence sur l'API de métriques.

    Premiers pas avec l'API de métriques

    L'URL de requête pour l'API de métriques est la suivante :

    https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats[dimension]

    Par exemple, pour obtenir les métriques regroupées par proxy d'API, utilisez l'URL suivante pour appeler l'API Apigee :

    https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?timeRange=07/21/2018+00:00:00~08/23/2018+00:00:00

    Omettez la dimension de manière à renvoyer les statistiques brutes pour l'ensemble de l'organisation et de l'environnement au cours de la période spécifiée :

    https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats?timeRange=07/21/2019+00:00:00~08/23/2018+00:00:00

    Spécifier les métriques à renvoyer

    Utilisez le paramètre de requête select pour spécifier les métriques à récupérer ainsi qu'une fonction d'agrégation facultative, au format suivant :

    ?select=metric

    ou :

    ?select=aggFunction(metric)

    Où :

    • metric spécifie les données que vous souhaitez récupérer. Par exemple, le nombre de requêtes API, de succès de cache (hit) ou d'erreurs de règle. Reportez-vous à la section Métriques 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.
      • p50 : renvoie le 50e centile pour les latences de traitement.
      • p95 : renvoie le 95e centile pour les latences de traitement.
      • p99 : renvoie le 99e centile pour les latences de traitement.

      Les métriques ne prennent pas toutes en charge toutes les fonctions d'agrégation. La documentation sur les métriques 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 de 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 (6 mois maximum) pour spécifier la période, sous la forme :

    ?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.

    Exemples d'appel de l'API de métriques

    Cette section fournit des exemples d'utilisation de l'API de métriques. Consultez la section Exemples d'API de métriques pour plus d'exemples.

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

    Pour renvoyer le nombre total d'appels passés à toutes les API de votre organisation et environnement pendant un mois, utilisez un appel semblable à celui-ci :

    curl -v "https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/?select=sum(message_count)&timeRange=03/01/2018%2000:00~03/31/2018%2023:59" \
  -H "Authorization: Bearer $TOKEN"

    Où $TOKEN est défini sur votre jeton d'accès OAuth 2.0, comme décrit dans la section Obtenir un jeton d'accès OAuth 2.0. Pour en savoir plus sur les options curl utilisées dans cet exemple, consultez la section Utiliser curl. Pour obtenir une description des variables d'environnement utilisées, consultez la section Définir des variables d'environnement pour les requêtes API Apigee.

    Voici un exemple de réponse :

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

    Renvoyer 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://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59" \
  -H "Authorization: Bearer $TOKEN"

    Où $TOKEN est défini sur votre jeton d'accès OAuth 2.0, comme décrit dans la section Obtenir un jeton d'accès OAuth 2.0. Pour en savoir plus sur les options curl utilisées dans cet exemple, consultez la section Utiliser curl. Pour obtenir une description des variables d'environnement utilisées, consultez la section Définir des variables d'environnement pour les requêtes API Apigee.

    Voici un 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://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/developer_app?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59&timeUnit=day" \
  -H "Authorization: Bearer $TOKEN"

    Voici un 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 obtenir une liste d'entités illustrant une condition particulière.

    Par exemple, pour rechercher 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://apigee.googleapis.com/v1/organizations/$ORG/environments/$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" \
  -H "Authorization: Bearer $TOKEN"

    Où $TOKEN est défini sur votre jeton d'accès OAuth 2.0, comme décrit dans la section Obtenir un jeton d'accès OAuth 2.0. Pour en savoir plus sur les options curl utilisées dans cet exemple, consultez la section Utiliser curl. Pour obtenir une description des variables d'environnement utilisées, consultez la section Définir des variables d'environnement pour les requêtes API Apigee.

    Voici un exemple de réponse :

    {
  "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://apigee.googleapis.com/v1/organizations/$ORG/environments/$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" \
  -H "Authorization: Bearer $TOKEN"

    Voici un 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.

    Supposons par exemple que vous deviez récupérer un nombre d'erreurs provenant des services de backend filtré par 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://apigee.googleapis.com/v1/organizations/$ORG/environments/$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')" \
  -H "Authorization: Bearer $TOKEN"

    Où $TOKEN est défini sur votre jeton d'accès OAuth 2.0, comme décrit dans la section Obtenir un jeton d'accès OAuth 2.0. Pour en savoir plus sur les options curl utilisées dans cet exemple, consultez la section Utiliser curl. Pour obtenir une description des variables d'environnement utilisées, consultez la section Définir des variables d'environnement pour les requêtes API Apigee.

    Voici un exemple de réponse :

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

    Effectuer la pagination des résultats

    Dans les environnements de production, certaines requêtes adressées à l'API Apigee Analytics renvoient des ensembles 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://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)" \
  -H "Authorization: Bearer $TOKEN"

    Où $TOKEN est défini sur votre jeton d'accès OAuth 2.0, comme décrit dans la section Obtenir un jeton d'accès OAuth 2.0. Pour en savoir plus sur les options curl utilisées dans cet exemple, consultez la section Utiliser curl. Pour obtenir une description des variables d'environnement utilisées, consultez la section Définir des variables d'environnement pour les requêtes API Apigee.

    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://apigee.googleapis.com/v1/organizations/$ORG/environments/$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" \
  -H "Authorization: Bearer $TOKEN"

    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://apigee.googleapis.com/v1/organizations/$ORG/environments/$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" \
  -H "Authorization: Bearer $TOKEN"