As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# 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 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-query` para realizar uma consulta.
+ `describe-query` para retornar metadados sobre uma consulta.
+ `generate-query` para produzir uma consulta a partir de um prompt em inglês. Para obter mais informações, consulte [Crie consultas CloudTrail do Lake a partir de solicitações em linguagem natural](lake-query-generator.md).
+ `get-query-results` para retornar os resultados da consulta do ID de consulta especificado.
+ `list-queries` para obter uma lista de consultas para o armazenamento de dados de eventos especificado.
+ `cancel-query` para cancelar uma consulta em execução.
Para obter uma lista dos comandos disponíveis para armazenamentos de dados de eventos do CloudTrail Lake, consulte[Comandos disponíveis para armazenamentos de dados de eventos](lake-eds-cli.md#lake-eds-cli-commands).
Para obter uma lista dos comandos disponíveis para painéis do CloudTrail Lake, consulte[Comandos disponíveis para painéis](lake-dashboard-cli.md#lake-dashboard-cli-commands).
Para obter uma lista dos comandos disponíveis para integrações com o CloudTrail Lake, consulte[Comandos disponíveis para integrações com o CloudTrail Lake](lake-integrations-cli.md#lake-integrations-cli-commands).
## Produza uma consulta a partir de um prompt de linguagem natural com o AWS CLI
Execute o comando `generate-query` para gerar uma consulta a partir de um prompt em inglês. Em `--event-data-stores`, forneça o ARN (ou o sufixo de ID do ARN) do datastore de eventos que você deseja consultar. Você pode especificar apenas um único datastore de eventos. Em `--prompt`, forneça o prompt em inglês.
```
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?"
```
Se for bem-sucedido, o comando gerará uma instrução SQL e fornecerá um `QueryAlias` que você usará com o comando `start-query` para executar a consulta em seu datastore de eventos.
```
{
"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"
}
```
## 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 parâmetro `--query-statement` fornece uma consulta de SQL entre aspas simples. Os parâmetros opcionais incluem `--delivery-s3-uri`, 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, consulte[CloudTrail Restrições do Lake SQL](query-limitations.md).
```
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"
```
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-s3-uri` 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](s3-bucket-policy-lake-query-results.md).
## 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 URI do S3 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 valor de ARN 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 de`RUNNING`. 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 exemplo da CLI.
```
aws cloudtrail cancel-query
--query-id EXAMPLEd-17a7-47c3-a9a1-eccf7EXAMPLE
```
**Saída**
```
QueryId -> (string)
QueryStatus -> (string)
```