Execute e gerencie consultas do CloudTrail Lake com o AWS CLI

Você pode usar o AWS CLI para executar e gerenciar suas consultas CloudTrail do Lake. Ao usar o AWS CLI, lembre-se de que seus comandos são Região da AWS executados no configurado para o seu perfil. Se você deseja executar os comandos em uma região diferente, altere a região padrão para o seu perfil ou use o parâmetro --region com o comando.

Comandos disponíveis para consultas CloudTrail do Lake

Os comandos para executar e gerenciar consultas no CloudTrail Lake incluem:

• start-querypara executar uma consulta.

• describe-querypara retornar metadados sobre uma consulta.

• get-query-resultspara retornar os resultados da consulta para o ID de consulta especificado.

• list-queriespara obter uma lista de consultas para o armazenamento de dados de eventos especificado.

• cancel-querypara cancelar uma consulta em execução.

Para obter uma lista dos comandos disponíveis para armazenamentos de dados de eventos do CloudTrail Lake, consulteComandos disponíveis para armazenamentos de dados de eventos.

Para obter uma lista dos comandos disponíveis para integrações com o CloudTrail Lake, consulteComandos disponíveis para integrações com o CloudTrail Lake.

Inicie uma consulta com o AWS CLI

O AWS CLI start-query comando de exemplo a seguir executa uma consulta no armazenamento de dados de eventos especificado como um ID na instrução de consulta e entrega os resultados da consulta a um bucket do S3 especificado. O --query-statement parâmetro fornece uma SQL consulta, entre aspas simples. Os parâmetros opcionais incluem --delivery-s3uri, para entregar os resultados de consulta a um bucket especificado do S3. Para obter mais informações sobre a linguagem de consulta que você pode usar no CloudTrail Lake, consulteCloudTrail SQLRestrições do lago.

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

A resposta é uma string de QueryId. Para obter o status de uma consulta, execute describe-query usando o valor QueryId retornado por start-query. Se a consulta tiver êxito, você poderá executar get-query-results para obter os resultados.

Saída

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

nota

Consultas que são executadas por mais de uma hora podem expirar. No entanto, ainda é possível obter resultados parciais que foram processados antes do tempo limite da consulta esgotar.

Se você estiver entregando os resultados da consulta para um bucket do S3 usando o --delivery-s3uri parâmetro opcional, a política do bucket deverá conceder CloudTrail permissão para entregar os resultados da consulta ao bucket. Para obter informações sobre como editar manualmente a política de bucket, consulte Política de bucket do Amazon S3 para resultados de consulta CloudTrail do Lake.

Obtenha metadados sobre uma consulta com o AWS CLI

O AWS CLI describe-query comando de exemplo a seguir obtém metadados sobre uma consulta, incluindo tempo de execução da consulta em milissegundos, número de eventos verificados e correspondidos, número total de bytes verificados e status da consulta. O valor BytesScanned corresponde ao número de bytes pelos quais sua conta é cobrada pela consulta, a menos que a consulta ainda esteja em execução. Se os resultados da consulta foram entregues em um bucket do S3, a resposta também fornecerá o S3 URI e o status da entrega.

Você pode especificar um valor para o parâmetro --query-id ou --query-alias. A especificação do parâmetro --query-alias retorna informações sobre a última consulta executada para o alias.

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

O seguinte é um exemplo de resposta.

{
    "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"
    }
}

Obtenha os resultados da consulta com o AWS CLI

O comando da AWS CLI get-query-results do exemplo a seguir obtém resultados de dados de eventos de uma consulta. Você deve especificar o --query-id retornado pelo comando start-query. O valor BytesScanned corresponde ao número de bytes pelos quais sua conta é cobrada pela consulta, a menos que a consulta ainda esteja em execução. Parâmetros opcionais incluem --max-query-results para especificar um número máximo de resultados que você deseja que o comando retorne em uma única página. Se houver mais resultados do que o valor especificado para --max-query-results, execute o comando novamente adicionando o valor retornado NextToken para obter a próxima página de resultados.

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

Saída

{
    "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"
}

Liste todas as consultas em um armazenamento de dados de eventos com a AWS CLI

O comando da AWS CLI list-queries do exemplo a seguir retorna uma lista de consultas e status de consulta em um armazenamento de dados de eventos especificado nos últimos sete dias. Você deve especificar um ARN ou o sufixo de ID de um ARN valor para--event-data-store. Opcionalmente, para encurtar a lista de resultados, você pode especificar um intervalo de tempo, formatado como carimbos de data/hora, adicionando os parâmetros --start-time e --end-time e um valor --query-status. Os valores válidos para QueryStatus incluem QUEUED, RUNNING, FINISHED, FAILED ou CANCELLED.

list-queries também tem parâmetros de paginação opcionais. Use --max-results para especificar um número máximo de resultados que você deseja que o comando retorne em uma única página. Se houver mais resultados do que o valor especificado para --max-results, execute o comando novamente adicionando o valor retornado NextToken para obter a próxima página de resultados.

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

Saída

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

Cancelar uma consulta em execução com o AWS CLI

O AWS CLI cancel-query comando de exemplo a seguir cancela uma consulta com um status deRUNNING. Especifique um valor para --query-id. Quando você executa cancel-query, o status da consulta pode ser exibido como CANCELLED mesmo que a operação cancel-query ainda não esteja concluída.

nota

Uma consulta cancelada pode incorrer em cobranças. Sua conta ainda é cobrada pela quantidade de dados que foram examinados antes de você cancelar a consulta.

Veja a seguir um CLI exemplo.

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

Saída

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