Exécutez et gérez les requêtes CloudTrail Lake à l'aide du AWS CLI - AWS CloudTrail
Commandes disponibles pour les requêtes CloudTrail LakeProduisez une requête à partir d'une invite en langage naturel à l'aide du AWS CLILancez une requête avec AWS CLIObtenez les métadonnées relatives à une requête à l'aide du AWS CLIObtenez les résultats de vos requêtes à l'aide du AWS CLIRépertoriez toutes les requêtes sur un magasin de données d'événements à l'aide du AWS CLIAnnulez une requête en cours à l'aide du AWS CLI

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.

Exécutez et gérez les requêtes CloudTrail Lake à l'aide du AWS CLI

Vous pouvez utiliser le AWS CLI pour exécuter et gérer vos requêtes CloudTrail Lake. Lorsque vous utilisez le AWS CLI, n'oubliez pas que vos commandes s'exécutent dans la Région AWS configuration adaptée à votre profil. Si vous souhaitez exécuter les commandes dans une autre région, modifiez la région par défaut pour votre profil, ou utilisez le paramètre --region avec la commande.

Commandes disponibles pour les requêtes CloudTrail Lake

Les commandes permettant d'exécuter et de gérer les requêtes dans CloudTrail Lake incluent :

Pour obtenir la liste des commandes disponibles pour les magasins de données d'événements CloudTrail Lake, consultezCommandes disponibles pour les magasins de données d'événements.

Pour obtenir la liste des commandes disponibles pour les tableaux de bord CloudTrail Lake, consultezCommandes disponibles pour les tableaux de bord.

Pour obtenir la liste des commandes disponibles pour les intégrations de CloudTrail Lake, consultezCommandes disponibles pour les intégrations de CloudTrail Lake.

Produisez une requête à partir d'une invite en langage naturel à l'aide du AWS CLI

Exécutez la generate-query commande pour générer une requête à partir d'une invite en anglais. Pour--event-data-stores, indiquez l'ARN (ou le suffixe d'ID de l'ARN) du magasin de données d'événements que vous souhaitez interroger. Vous ne pouvez spécifier qu'un seul magasin de données d'événements. Pour--prompt, fournissez l'invite en anglais.

aws cloudtrail generate-query 
--event-data-stores arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/EXAMPLE-ee54-4813-92d5-999aeEXAMPLE \
--prompt "Show me all console login events for the past week?"

En cas de succès, la commande génère une instruction SQL et fournit une instruction QueryAlias que vous utiliserez avec la start-query commande pour exécuter la requête dans votre banque de données d'événements.

{
  "QueryStatement": "SELECT * FROM $EDS_ID WHERE eventname = 'ConsoleLogin' AND eventtime >= timestamp '2024-09-16 00:00:00' AND eventtime <= timestamp '2024-09-23 00:00:00' AND eventSource = 'signin.amazonaws.com'",
  "QueryAlias": "AWSCloudTrail-UUID"
}

Lancez une requête avec AWS CLI

L'exemple de AWS CLI start-query commande suivant exécute une requête sur le magasin de données d'événements spécifié sous forme d'ID dans l'instruction de requête et fournit les résultats de la requête à un compartiment S3 spécifié. Le paramètre --query-statement fournit une requête SQL, entre guillemets simples. Les paramètres facultatifs incluent --delivery-s3-uri, pour envoyer les résultats d’une requête à un compartiment S3 spécifié. Pour plus d'informations sur le langage de requête que vous pouvez utiliser dans CloudTrail Lake, consultezCloudTrail Contraintes SQL du lac.

aws cloudtrail start-query
--query-statement 'SELECT eventID, eventTime FROM EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE LIMIT 10'
--delivery-s3-uri "s3://aws-cloudtrail-lake-query-results-123456789012-us-east-1"

La réponse est une chaîne QueryId. Pour obtenir le statut d'une requête, exécutez describe-query en utilisant la valeur QueryId renvoyée par start-query. Si la requête est réussie, vous pouvez exécuter get-query-results pour obtenir des résultats.

Sortie

{
    "QueryId": "EXAMPLE2-0add-4207-8135-2d8a4EXAMPLE"
}
Note

Les requêtes qui s'exécutent pendant plus d'une heure peuvent prendre fin. Vous pouvez toujours obtenir des résultats partiels traités avant l’échéance de la requête.

Si vous transmettez les résultats de la requête à un compartiment S3 à l'aide du --delivery-s3-uri paramètre facultatif, la politique du compartiment doit CloudTrail autoriser la livraison des résultats de la requête au compartiment. Pour en savoir plus sur la modification manuelle de la politique de compartiment, consultez Politique relative aux compartiments Amazon S3 pour les résultats des requêtes CloudTrail Lake.

Obtenez les métadonnées relatives à une requête à l'aide du AWS CLI

L'exemple de AWS CLI describe-query commande suivant permet d'obtenir les métadonnées relatives à une requête, notamment le temps d'exécution de la requête en millisecondes, le nombre d'événements analysés et mis en correspondance, le nombre total d'octets analysés et le statut de la requête. La valeur BytesScanned correspond au nombre d’octets pour lesquels votre compte est facturé pour la requête, sauf si la requête est toujours en cours d’exécution. Si les résultats de la requête ont été transmis à un compartiment S3, la réponse fournit également l'URI S3 et le statut de livraison.

Vous devez spécifier une valeur pour le paramètre --query-id ou pour le paramètre --query-alias. La spécification du paramètre --query-alias renvoie des informations sur la dernière requête exécutée pour l'alias. 

aws cloudtrail describe-query --query-id EXAMPLEd-17a7-47c3-a9a1-eccf7EXAMPLE

Voici un exemple de réponse.

{
    "QueryId": "EXAMPLE2-0add-4207-8135-2d8a4EXAMPLE", 
    "QueryString": "SELECT eventID, eventTime FROM EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE LIMIT 10", 
    "QueryStatus": "RUNNING",
    "QueryStatistics": {
        "EventsMatched": 10,
        "EventsScanned": 1000,
        "BytesScanned": 35059,
        "ExecutionTimeInMillis": 3821,
        "CreationTime": "1598911142"
    }
}

Obtenez les résultats de vos requêtes à l'aide du AWS CLI

L'exemple de commande AWS CLI get-query-results suivant montre comment obtenir les résultats des données d'événement d'une requête. Vous devez spécifier le --query-id renvoyé par la commande start-query. La valeur BytesScanned correspond au nombre d'octets pour lesquels votre compte est facturé pour la requête, sauf si la requête est toujours en cours d'exécution. Les paramètres facultatifs incluent --max-query-results, pour spécifier un nombre maximal de résultats que la commande doit renvoyer sur une seule page. S'il y a plus de résultats que la valeur --max-query-results spécifiée, exécutez à nouveau la commande en ajoutant la valeur NextToken renvoyée pour obtenir la page suivante de résultats.

aws cloudtrail get-query-results
--query-id EXAMPLEd-17a7-47c3-a9a1-eccf7EXAMPLE

Sortie

{
    "QueryStatus": "RUNNING",
    "QueryStatistics": {
        "ResultsCount": 244,
        "TotalResultsCount": 1582,
        "BytesScanned":27044
    },
    "QueryResults": [
      {
        "key": "eventName",
        "value": "StartQuery",
      }
   ],
    "QueryId": "EXAMPLE2-0add-4207-8135-2d8a4EXAMPLE", 
    "QueryString": "SELECT eventID, eventTime FROM EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE LIMIT 10",
    "NextToken": "20add42078135EXAMPLE"
}

Répertoriez toutes les requêtes sur un magasin de données d'événements à l'aide du AWS CLI

L'exemple de commande AWS CLI list-queries suivant montre comment renvoyer une liste de requêtes et d'états de requête sur un magasin de données d'événement spécifié au cours des sept derniers jours. Vous devez spécifier un ARN ou le suffixe d'ID d'une valeur ARN pour --event-data-store. Pour raccourcir la liste des résultats, vous pouvez également spécifier une plage de temps, formatée en horodatage, en ajoutant les paramètres --start-time et --end-time, et une valeur --query-status. Les valeurs valides pour QueryStatus incluent QUEUED, RUNNING, FINISHED, FAILED ou CANCELLED.

list-queries dispose également de paramètres de pagination facultatifs. Utilisez --max-results pour spécifier un nombre maximal de résultats que la commande doit renvoyer sur une seule page. S'il y a plus de résultats que la valeur --max-results spécifiée, exécutez à nouveau la commande en ajoutant la valeur NextToken renvoyée pour obtenir la page suivante de résultats.

aws cloudtrail list-queries
--event-data-store EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE
--query-status CANCELLED
--start-time 1598384589
--end-time 1598384602
--max-results 10

Sortie

{
    "Queries": [
        {
          "QueryId": "EXAMPLE2-0add-4207-8135-2d8a4EXAMPLE", 
          "QueryStatus": "CANCELLED",
          "CreationTime": 1598911142
        },
        {
          "QueryId": "EXAMPLE2-4e89-9230-2127-5dr3aEXAMPLE", 
          "QueryStatus": "CANCELLED",
          "CreationTime": 1598296624
        }
     ],
    "NextToken": "20add42078135EXAMPLE"
}

Annulez une requête en cours à l'aide du AWS CLI

L'exemple de AWS CLI cancel-query commande suivant annule une requête dont le statut est deRUNNING. Vous devez spécifier une valeur pour --query-id. Lorsque vous exécutez cancel-query, l’état de la requête peut être CANCELLED même si l’opération cancel-query n’est pas encore terminée.

Note

Une requête annulée peut entraîner des frais. Votre compte est toujours facturé pour la quantité de données analysées avant l'annulation de la requête.

Voici un exemple de CLI.

aws cloudtrail cancel-query
--query-id EXAMPLEd-17a7-47c3-a9a1-eccf7EXAMPLE

Sortie

QueryId -> (string)
QueryStatus -> (string)