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.
# chercher
`lookup`À utiliser pour enrichir les résultats de votre requête avec des données de référence issues d'une table de recherche. Une table de recherche contient des données CSV que vous chargez sur Amazon CloudWatch Logs. Lorsqu'une requête est exécutée, la `lookup` commande fait correspondre un champ de votre journal des événements à un champ de la table de recherche et ajoute les champs de sortie spécifiés aux résultats.
Utilisez les tables de recherche pour les scénarios d'enrichissement des données, tels que le mappage des informations utilisateur IDs à utilisateur, les codes de produit aux informations sur le produit ou les codes d'erreur aux descriptions d'erreurs.
## Création et gestion de tables de recherche
Avant de pouvoir utiliser la `lookup` commande dans une requête, vous devez créer une table de recherche. Vous pouvez créer et gérer des tables de recherche depuis la CloudWatch console ou à l'aide de l'API Amazon CloudWatch Logs.
**Pour créer une table de recherche (console)**
1. Ouvrez la CloudWatch console à l'adresse [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Dans le volet de navigation, choisissez **Paramètres**, puis l'onglet **Journaux**.
1. Accédez aux **tables de recherche**, puis sélectionnez **Gérer**.
1. Choisissez **Créer une table de recherche**.
1. Entrez un nom pour la table de recherche. Le nom ne peut contenir que des caractères alphanumériques, des traits d'union et des traits de soulignement.
1. (Facultatif) Entrez une description.
1. Téléchargez un fichier CSV. Le fichier doit inclure une ligne d'en-tête avec les noms de colonnes, utiliser le codage UTF-8 et ne pas dépasser 10 Mo.
1. (Facultatif) Spécifiez une AWS KMS clé pour chiffrer les données de la table.
1. Choisissez **Créer**.
Après avoir créé une table de recherche, vous pouvez l'afficher dans l'éditeur de requêtes CloudWatch Logs Insights. Cliquez sur l'onglet **Tables de recherche** pour parcourir les tables disponibles et leurs champs.
Pour mettre à jour une table de recherche, sélectionnez-la et choisissez **Actions**, **Mettre à jour**. Téléchargez un nouveau fichier CSV pour remplacer tout le contenu existant. Pour supprimer une table de recherche, choisissez **Actions**, **Supprimer**.
**Note**
Vous pouvez créer jusqu'à 100 tables de recherche par compte et par compte Région AWS. Les fichiers CSV peuvent peser jusqu'à 10 Mo. Vous pouvez également gérer les tables de recherche à l'aide de l'API Amazon CloudWatch Logs. Pour plus d'informations, consultez [CreateLookupTable](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_CreateLookupTable.html)le manuel *Amazon CloudWatch Logs API Reference*.
**Note**
Si la table de recherche est chiffrée à l'aide d'une clé KMS, l'appelant doit avoir l'`kms:Decrypt`autorisation sur la clé (la clé KMS utilisée pour chiffrer la table de recherche) d'utiliser l'`StartQuery`API avec une requête faisant référence à cette table de recherche. Pour de plus amples informations, veuillez consulter [Chiffrez les tables de recherche dans les CloudWatch journaux à l'aide de AWS Key Management Service](encrypt-lookup-tables-kms.md).
## Syntaxe de requête pour la recherche
**Structure de commande**
Le format de cette commande est illustré ci-dessous.
```
lookup {{table}} {{lookup-field}} as {{log-field}} [,...] {{output-mode}} {{output-field}}[,...]
```
La commande utilise les arguments suivants :
+ `{{table}}`— Nom de la table de recherche à utiliser.
+ `{{lookup-field}}`— Le champ de la table de recherche à comparer.
+ `{{log-field}}`— Le champ correspondant dans votre journal des événements. La correspondance est exacte et distingue les majuscules et minuscules.
+ `{{lookup-field}} as {{log-field}} [,...]`— Vous pouvez spécifier plusieurs paires de champs de correspondance séparées par des virgules. Lorsque plusieurs paires sont spécifiées, une ligne de la table de recherche doit correspondre à tous les champs pour produire un résultat (logique AND).
+ `{{output-mode}}`— Spécifie la manière dont les champs de sortie sont ajoutés aux résultats. Utilisez l'une des options suivantes :
+ `OUTPUT`— Ajoute les champs de sortie aux résultats. Si un champ portant le même nom existe déjà dans le journal des événements, il est remplacé par la valeur de la table de recherche. Si aucune correspondance n'est trouvée, le champ est défini sur null.
+ `OUTPUTNEW`— Ajoute les champs de sortie aux résultats uniquement si le champ n'existe pas déjà dans le journal des événements. Si le champ possède déjà une valeur, la valeur d'origine est conservée. Si aucune correspondance n'est trouvée, le champ reste inchangé.
+ `{{output-field}}`— Un ou plusieurs champs de la table de recherche à ajouter aux résultats.
**Exemple : enrichir les événements du journal avec les détails de l'utilisateur**
Supposons que vous disposiez d'un groupe de journaux contenant des événements contenant un `id` champ et d'une table de recherche nommée `user_data` par des colonnes `id``name`,`email`, et`department`. La requête suivante enrichit chaque événement du journal avec le nom, l'adresse e-mail et le service de l'utilisateur à partir de la table de recherche.
```
fields action, status, name, email, department
| lookup user_data id OUTPUT name, email, department
```
**Exemple : utilisation de la recherche avec agrégation**
Vous pouvez utiliser des champs de sortie de recherche avec des fonctions d'agrégation. La requête suivante enrichit les événements du journal avec les détails de l'utilisateur, puis compte les événements regroupés par adresse e-mail.
```
fields user_id, action, username, email, department
| lookup user_data user_id OUTPUT username, email, department
| stats count(*) by email
```
**Exemple : utiliser la recherche avec filtre**
Vous pouvez filtrer les résultats en fonction des champs renvoyés par la recherche. La requête suivante enrichit les événements du journal, puis filtre pour n'afficher que les événements d'un département spécifique.
```
fields user_id, action
| lookup user_data user_id OUTPUT username, email, department
| filter department = "Engineering"
```
**Exemple : utilisez OUTPUTNEW pour enrichir sans remplacer**
Si les événements de votre journal contiennent déjà un `hostname` champ mais qu'il est parfois vide, utilisez-le `OUTPUTNEW` pour remplir les valeurs manquantes sans remplacer les valeurs existantes.
```
fields srcAddr, hostname
| lookup known_hosts ip_address as srcAddr OUTPUTNEW hostname, region
```
**Exemple : utiliser la recherche avec plusieurs champs de correspondance**
Vous pouvez correspondre sur plusieurs champs. La requête suivante `dstPort` compare `srcAddr` les deux à la table de recherche afin d'identifier les services réseau connus.
```
fields @timestamp, srcAddr, dstAddr, dstPort
| lookup network_services ip_address as srcAddr, port as dstPort OUTPUT service_name, owner
| filter ispresent(service_name)
```