Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Composants et syntaxe des requêtes dans CloudWatch Metrics Insights
CloudWatch La syntaxe de Metrics Insights est la suivante.
```
SELECT FUNCTION(metricName)
FROM namespace | SCHEMA(...)
[ WHERE labelKey OPERATOR labelValue [AND ... ] ]
[ GROUP BY labelKey [ , ... ] ]
[ ORDER BY FUNCTION() [ DESC | ASC ] ]
[ LIMIT number ]
```
Les clauses possibles dans une requête Metrics Insights sont les suivantes. Aucun des mots-clés n'est sensible à la casse, mais les identificateurs tels que les noms des métriques, des espaces de noms et des dimensions sont sensibles à la casse.
**SELECT**
Obligatoire. Spécifie la fonction à utiliser pour agréger les observations dans chaque compartiment temporel (déterminé par la période fournie). Spécifie également le nom de la métrique à interroger.
Les valeurs valides pour **FUNCTION** (FONCTION) sont `AVG`, `COUNT`, `MAX`, `MIN` et `SUM`.
+ `AVG` calcule la moyenne des observations correspondant à la requête.
+ `COUNT` renvoie le nombre d'observations correspondant à la requête.
+ `MAX` renvoie la valeur maximale des observations correspondant à la requête.
+ `MIN` renvoie la valeur minimale des observations correspondant à la requête.
+ `SUM` calcule la somme des observations correspondant à la requête.
**FROM**
Obligatoire. Spécifie la source de la métrique. Vous pouvez spécifier soit l'espace de noms de métrique qui contient la métrique à interroger, soit une fonction de table **SCHEMA** (SCHÉMA). Voici des exemples d'espaces de noms de métriques : `"AWS/EC2"`, `"AWS/Lambda"`, et des espaces de noms de métriques que vous avez créés pour vos métriques personnalisées.
Les espaces de noms de métriques qui incluent **/** ou tout autre caractère qui n'est pas une lettre, un chiffre ou un tiret bas doivent être entourés de guillemets doubles. Pour de plus amples informations, consultez [Qu'est-ce qui nécessite des guillemets ou des caractères d'échappement ?](#cloudwatch-metrics-insights-syntaxdetails).
**SCHEMA** (SCHÉMA)
Une fonction de table facultative pouvant être utilisée dans une clause **FROM** (À PARTIR DE). Utilisez **SCHEMA** (SCHÉMA) pour réduire les résultats de la requête aux métriques qui correspondent parfaitement à une liste de dimensions, ou aux métriques qui n'ont pas de dimensions.
Si vous utilisez une clause **SCHEMA** (SCHÉMA), elle doit contenir au moins un argument, et ce premier argument doit être l'espace de noms de la métrique interrogée. Si vous spécifiez **SCHEMA** (SCHÉMA) avec cet argument d'espace de noms uniquement, les résultats sont limités à des métriques qui n'ont aucune dimension.
Si vous spécifiez **SCHEMA** (SCHÉMA) avec des arguments supplémentaires, les arguments supplémentaires après l'argument d'espace de noms doivent être des clés d'*étiquette*. Les clés d'étiquette doivent être des noms de dimension. Si vous spécifiez une ou plusieurs de ces clés d'étiquette, les résultats sont limités uniquement aux métriques qui possèdent cet ensemble exact de dimensions. L'ordre de ces clés d'étiquette n'a pas d'importance.
Par exemple :
+ **SELECT AVG(CPUUtilization) FROM "AWS/EC2"** correspond à toutes les métriques `CPUUtilization` dans l'espace de noms `AWS/EC2`, quelles que soient leurs dimensions, et renvoie une série temporelle agrégée unique.
+ **SELECT AVG(CPUUtilization) FROM SCHEMA("AWS/EC2")** ne correspond qu'aux métriques `CPUUtilization` dans l'espace de noms `AWS/EC2` pour lequel aucune dimension n'est définie.
+ **SELECT AVG (CPUUtilization) FROM SCHEMA (« AWS/EC2 », InstanceId)** ne correspond qu'aux `CPUUtilization` CloudWatch métriques signalées avec exactement une dimension,. `InstanceId`
+ **SELECT SUM (RequestCount) FROM SCHEMA (« AWS/ApplicationElb » LoadBalancer,, AvailabilityZone)** correspond uniquement aux `RequestCount` métriques signalées à CloudWatch from `AWS/ApplicationELB` avec exactement deux dimensions, et. `LoadBalancer` `AvailabilityZone`
**WHERE**
Facultatif. Filtre les résultats en ne retenant que les métriques qui correspondent à l'expression spécifiée à l'aide de valeurs d'étiquette spécifiques pour une ou plusieurs clés d'étiquette. **Par exemple, **WHERE InstanceType = 'c3.4xlarge'** filtre les résultats uniquement pour les types d'`c3.4xlarge`instances, et WHERE \$1 InstanceType = 'c3.4xlarge'** filtre les résultats pour tous les types d'instances sauf. `c3.4xlarge`
Lorsque vous exécutez une requête dans un compte de surveillance, vous pouvez l’utiliser `WHERE AWS.AccountId` pour limiter les résultats au compte que vous spécifiez. Par exemple, `WHERE AWS.AccountId=444455556666` n’interroge les métriques que pour le compte `444455556666`. Pour limiter votre requête aux seuls indicateurs du compte de surveillance lui-même, utilisez `WHERE AWS.AccountId=CURRENT_ACCOUNT_ID()`.
Les valeurs des étiquettes doivent toujours être entourées de guillemets simples.
**Utilisation des balises dans les clauses WHERE**
Vous pouvez filtrer les résultats par balises de AWS ressources à l'aide de la syntaxe`tag.keyName`. Les filtres de balises suivent les mêmes règles d’opérateur que les filtres de dimension. Par exemple :
+ WHERE `tag.env = 'prod'` filtre les métriques des ressources balisées avec *env=prod*
+ WHERE `tag.department != 'test'` exclut les métriques des ressources balisées avec *department=test*
Les filtres de balises peuvent être combinés avec des filtres de dimension :
`WHERE tag.env = 'prod' AND InstanceType = 'm5.large'`
**Opérateurs pris en charge**
La clause **WHERE** (OÙ) prend en charge les opérateurs suivants :
+ **=** La valeur de l'étiquette doit correspondre à la chaîne spécifiée.
+ **\$1=** La valeur de l'étiquette ne doit pas correspondre à la chaîne spécifiée.
+ **AND** (ET) Les deux conditions spécifiées doivent être vraies pour correspondre. Vous pouvez utiliser plusieurs mots-clés **AND** (ET) afin de spécifier deux conditions ou plus.
**GROUP BY**
Facultatif. Regroupe les résultats de la requête en plusieurs séries temporelles, chacune correspondant à une valeur différente pour la ou les clés d'étiquette spécifiées. Par exemple, l'utilisation de `GROUP BY InstanceId` renvoie une série temporelle différente pour chaque valeur de `InstanceId`. L'utilisation de `GROUP BY ServiceName, Operation` crée une série temporelle différente pour chaque combinaison possible des valeurs de `ServiceName` et `Operation`.
Avec une clause **GROUP BY** (REGROUPER PAR), les résultats sont classés par ordre alphabétique croissant par défaut, en utilisant la séquence d'étiquettes spécifiée dans la clause **GROUP BY** (REGROUPER PAR). Pour modifier l'ordre des résultats, ajoutez une clause **ORDER BY** (CLASSER PAR) à votre requête.
Lorsque vous exécutez une requête dans un compte de surveillance, vous pouvez l’utiliser `GROUP BY AWS.AccountId` pour regrouper les résultats en fonction des comptes dont ils proviennent.
**Utilisation de balises dans les clauses GROUP BY**
Vous pouvez regrouper les résultats par valeurs de balise de AWS ressource à l'aide de la syntaxe`tag.keyName`. Par exemple :
+ *GROUP BY tag.environment* crée des séries temporelles distinctes pour chaque valeur de balise d’environnement
+ *GROUPER PAR TAG.team, InstanceType* groupes par balise et par valeurs de dimension
+ *GROUPER PAR tag.team, AWS. AccountId*groupes à la fois par tag et par compte source lié IDs
Si certaines des métriques correspondantes n'incluent pas de clé d'étiquette spécifique spécifiée dans la clause **GROUP BY** (REGROUPER PAR), un groupe nul nommé `Other` est renvoyé. Par exemple, si vous spécifiez `GROUP BY ServiceName, Operation` et que certaines des métriques renvoyées ne comprennent pas `ServiceName` en tant que dimension, alors ces métriques sont affichées comme ayant `Other` comme valeur pour `ServiceName`.
**ORDER BY**
Facultatif. Spécifie l'ordre à utiliser pour les séries temporelles renvoyées si la requête renvoie plusieurs séries temporelles. L'ordre est basé sur les valeurs trouvées par la clause **FUNCTION** (FONCTION) que vous spécifiez dans la clause **ORDER BY** (CLASSER PAR). La clause **FUNCTION** (FONCTION) est utilisée pour calculer une valeur scalaire unique à partir de chaque série temporelle renvoyée, et cette valeur est utilisée pour déterminer l'ordre.
Vous spécifiez également s'il faut utiliser l'ordre croissant **ASC** ou décroissant **DESC**. Si vous l'omettez, la valeur par défaut est croissante, **ASC**.
Par exemple, l'ajout d'une clause `ORDER BY MAX() DESC` classe les résultats en fonction du point de données maximal observé dans la plage temporelle, dans l'ordre décroissant. En d'autres mots, la série temporelle ayant le point de données maximal le plus élevé est renvoyée en premier.
Les fonctions valides à utiliser dans une clause **ORDER BY** (CLASSER PAR) sont `AVG()`, `COUNT()`, `MAX()`, `MIN()` et `SUM()`.
Si vous utilisez une clause **ORDER BY** (CLASSER PAR) avec une clause **LIMIT** (LIMITE), la requête résultante est une requête « Top N ». **ORDER BY** (CLASSER PAR) est également utile pour les requêtes qui peuvent renvoyer un grand nombre de métriques, car chaque requête ne peut pas renvoyer plus de 500 séries temporelles. Si une requête correspond à plus de 500 séries temporelles et que vous utilisez une clause **ORDER BY** (CLASSER PAR), les séries temporelles sont triées, puis les 500 séries temporelles qui arrivent en premier dans l'ordre de tri sont celles qui sont renvoyées.
**LIMIT**
Facultatif. Limite le nombre de séries temporelles renvoyées par la requête à la valeur que vous spécifiez. La valeur maximale que vous pouvez spécifier est 500, et une requête qui ne spécifie pas de **LIMIT** (LIMITE) ne peut pas non plus renvoyer plus de 500 séries temporelles.
L'utilisation d'une clause **LIMIT** (LIMITE) avec une clause **ORDER BY** (CLASSER PAR) vous donne une requête « Top N ».
## Qu'est-ce qui nécessite des guillemets ou des caractères d'échappement ?
Dans une requête, les valeurs d'étiquette doivent toujours être entourées de guillemets simples. Par exemple, **SELECT MAX (CPUUtilization) FROM « AWS/EC2"** WHERE = « ». AutoScalingGroupName my-production-fleet
Les espaces de noms de métriques, les noms de métriques et les clés d'étiquette contenant des caractères autres que des lettres, des chiffres et des tirets bas (\$1) doivent être entourés de guillemets doubles. Par exemple, **SELECT MAX("My.Metric")**.
Si l'un d'entre eux contient un guillemet double ou un guillemet simple lui-même (par exemple : `Bytes"Input"`), vous devez séparer chaque guillemet par une barre oblique inverse, comme dans **SELECT AVG("Bytes\$1"Input\$1"")**.
Si un espace de noms de métrique, un nom de métrique ou une clé d'étiquette contient un mot qui est un mot-clé réservé dans Metrics Insights, ceux-ci doivent également être entre guillemets doubles. Par exemple, si vous disposez d'une métrique nommée `LIMIT`, vous devez utiliser `SELECT AVG("LIMIT")`. Il est également valable de placer n'importe quel espace de noms, nom de métrique ou étiquette entre guillemets doubles, même s'il n'inclut pas de mot-clé réservé.
Pour obtenir la liste complète des mots-clés réservés, consultez [Mots-clés réservés](cloudwatch-metrics-insights-reserved-keywords.md).
## Créer une requête riche étape par étape
Cette section illustre la création d'un exemple complet qui utilise toutes les clauses possibles, étape par étape.
Vous pouvez commencer par la requête suivante, qui agrège toutes les métriques de l’Application Load Balancer `RequestCount` collectées avec les dimensions `LoadBalancer` et `AvailabilityZone`.
```
SELECT SUM(RequestCount)
FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone)
```
Pour ne voir que les métriques d’un équilibreur de charge spécifique, vous pouvez ajouter une clause **WHERE** pour limiter les métriques renvoyées aux seules métriques pour lesquelles la valeur de la dimension `LoadBalancer` est `app/load-balancer-1`.
```
SELECT SUM(RequestCount)
FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone)
WHERE LoadBalancer = 'app/load-balancer-1'
```
La requête précédente agrège les métriques `RequestCount` de toutes les zones de disponibilité de cet équilibreur de charge en une seule série temporelle. Si vous voulez voir des séries temporelles différentes pour chaque zone de disponibilité, nous pouvons ajouter une clause **GROUP BY**.
```
SELECT SUM(RequestCount)
FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone)
WHERE LoadBalancer = 'app/load-balancer-1'
GROUP BY AvailabilityZone
```
Vous pouvez ensuite ordonner les résultats de manière à afficher d’abord les valeurs les plus élevées. La clause **ORDER BY** (CLASSER PAR) suivante classe les séries temporelles par ordre décroissant, en fonction de la valeur maximale signalée par chaque série temporelle pendant la période de requête :
```
SELECT SUM(RequestCount)
FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone)
WHERE LoadBalancer = 'app/load-balancer-1'
GROUP BY AvailabilityZone
ORDER BY MAX() DESC
```
Vous pouvez également utiliser des balises pour filtrer davantage les résultats. Par exemple, si vous voulez voir les résultats uniquement pour les équilibreurs de charge balisés avec un environnement spécifique, nous pouvons ajouter le filtrage par balise à la clause WHERE :
```
SELECT SUM(RequestCount) FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone) WHERE LoadBalancer = 'app/load-balancer-1' AND tag.Environment = 'prod' GROUP BY AvailabilityZone ORDER BY MAX() DESC
```
Vous pouvez également regrouper les résultats en fonction des valeurs des balises au lieu (ou en plus) des dimensions. Par exemple, le regroupement par le balisage de l’application :
```
SELECT SUM(RequestCount) FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone) WHERE tag.Environment = 'prod' GROUP BY tag.Application ORDER BY MAX() DESC
```
Enfin, si nous sommes avant tout intéressés par un type de requête « Top N », nous pouvons utiliser une clause **LIMIT** (LIMITE). Cet exemple final limite les résultats aux séries temporelles avec les cinq valeurs `MAX` les plus élevées.
```
SELECT SUM(RequestCount)
FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone)
WHERE LoadBalancer = 'app/load-balancer-1'
GROUP BY AvailabilityZone
ORDER BY MAX() DESC
LIMIT 5
```
## Exemple de requête entre comptes
Ces exemples sont valides lorsqu'ils sont exécutés dans un compte configuré en tant que compte de surveillance dans le cadre de l' CloudWatchobservabilité entre comptes.
L’exemple suivant montre comment rechercher toutes les instances Amazon EC2 du compte source 123456789012 et en afficher la moyenne.
```
SELECT AVG(CpuUtilization)
FROM "AWS/EC2"
WHERE AWS.AccountId ='123456789012'
```
L’exemple suivant interroge la métrique `CPUUtilization` dans `AWS/EC2` pour tous les comptes source liés et regroupe les résultats par ID de compte et type d’instance.
```
SELECT AVG(CpuUtilization)
FROM "AWS/EC2"
GROUP BY AWS.AccountId, InstanceType
```
L’exemple suivant interroge le `CPUUtilization` dans le compte de surveillance lui-même.
```
SELECT AVG(CpuUtilization)
FROM "AWS/EC2"
WHERE AWS.AccountId = CURRENT_ACCOUNT_ID()
```