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 :

• start-querypour exécuter une requête.

• describe-querypour renvoyer des métadonnées relatives à une requête.

• get-query-resultspour renvoyer les résultats de la requête pour l'ID de requête spécifié.

• list-queriespour obtenir une liste de requêtes pour le magasin de données d'événements spécifié.

• cancel-querypour annuler une requête en cours d'exécution.

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 intégrations de CloudTrail Lake, consultezCommandes disponibles pour les intégrations de CloudTrail Lake.

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 --query-statement paramètre fournit une SQL requête 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 SQLContraintes liées au 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 accorder CloudTrail l'autorisation de transmettre les 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 indique également le S3 URI et l'état 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 avec 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'identification d'une ARN valeur 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.

Ce qui suit en est un CLI exemple.

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

Sortie

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