<ph type="x-smartling-placeholder"></ph>
Vous consultez la documentation Apigee Edge.
Accédez à la page
Documentation sur Apigee X. En savoir plus
Apigee Edge enregistre une grande variété aux 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é. En utilisant Edge API Analytics, vous pouvez, pour par exemple, les API qui enregistrent de bonnes ou de mauvaises performances, ou encore les développeurs qui fournissent les le trafic le plus important et les applications qui causent le plus 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 Utilisez l'API de métriques lorsque vous devez automatiser certaines fonctions Analytics, comme la récupération de métriques régulièrement à 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 apprendre à utiliser Analytics dans l'API Consultez la présentation de l'analyse d'API dans l'interface utilisateur de gestion Edge.
À propos des API de métriques
Edge fournit deux API de métriques:
Obtenir des métriques renvoie des métriques pour une organisation et 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 des métriques organisées par dimensions renvoie des métriques sur une période donnée pour une organisation et un environnement regroupés 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 accepte des fonctionnalités supplémentaires non compatibles avec l'API Obtenir des métriques, y compris :
À 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 la suivante:
"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}/statsPour 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/dimensionPar exemple, pour obtenir des 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/apiproxySpé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 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 à 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 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.
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 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 fonctions Obtenir des métriques et Obtenir des métriques organisées par dimensions API. Consultez les exemples de l'API Metrics pour obtenir des exemples supplémentaires.
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:passwordExemple 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
des entités qui illustrent
une condition particulière. Par exemple, pour identifier l'URL cible correspondant au
le plus sujette aux erreurs au cours de la semaine dernière, le paramètre topk est ajouté à la demande.
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 un nombre d'erreurs auprès des services de backend
filtrée 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://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"
}
]...
}Effectuer la pagination des résultats
Dans les environnements de production, certaines demandes adressées à l'API d'analyse Edge renvoient des données très volumineuses ensembles de données. 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