本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用运行和管理 CloudTrail Lake 查询 AWS CLI
<a name="lake-queries-cli"></a>

您可以使用 AWS CLI 来运行和管理您的 CloudTrail Lake 查询。使用时 AWS CLI，请记住您的命令在 AWS 区域 配置文件中运行。如果您想要在不同的区域中运行命令，可以为配置文件更改默认区域，或者与命令一起使用 **--region** 参数。

## 可用于 L CloudTrail ake 查询的命令
<a name="lake-queries-cli-commands"></a>

用于在 L CloudTrail ake 中运行和管理查询的命令包括：
+ `start-query` 用于运行查询。
+ `describe-query` 用于返回有关查询的元数据。
+ `generate-query` 可根据英语提示生成查询。有关更多信息，请参阅 [根据自然语言提示创建 CloudTrail Lake 查询](lake-query-generator.md)。
+ `get-query-results` 用于返回指定查询 ID 的查询结果。
+ `list-queries` 用于获取指定事件数据存储的查询列表。
+ `cancel-query` 用于取消正在运行的查询。

有关 La CloudTrail ke 事件数据存储的可用命令列表，请参阅[可用于事件数据存储的命令](lake-eds-cli.md#lake-eds-cli-commands)。

有关 La CloudTrail ke 仪表板可用命令的列表，请参阅[可用于控制面板的命令](lake-dashboard-cli.md#lake-dashboard-cli-commands)。

有关 La CloudTrail ke 集成的可用命令列表，请参阅[L CloudTrail ake 集成的可用命令](lake-integrations-cli.md#lake-integrations-cli-commands)。

## 使用自然语言提示生成查询 AWS CLI
<a name="lake-cli-generate-query"></a>

运行 `generate-query` 命令以根据英语提示生成查询。对于 `--event-data-stores`，请提供要查询的事件数据存储的 ARN（或 ARN 的 ID 后缀）。您只能指定一个事件数据存储。对于 `--prompt`，请用英语提供提示。

```
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?"
```

如果成功，该命令将输出一条 SQL 语句，并提供一个 `QueryAlias`，您可以将其与 `start-query` 命令结合使用来针对事件数据存储运行查询。

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

## 使用开始查询 AWS CLI
<a name="lake-cli-start-query"></a>

以下示例 AWS CLI **start-query**命令对查询语句中指定为 ID 的事件数据存储运行查询，并将查询结果传送到指定的 S3 存储桶。`--query-statement` 参数提供 SQL 查询，用单引号括起来。可选参数包括 `--delivery-s3-uri`，用于将查询结果传送到指定的 S3 存储桶。有关您可以在 La CloudTrail ke 中使用的查询语言的更多信息，请参阅[CloudTrail 湖泊 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"
```

响应是 `QueryId` 字符串。要获取查询的状态，请使用 **start-query** 返回的值 `QueryId` 运行 **describe-query**。如果查询成功，您可以运行 **get-query-results** 以获取结果。

**输出**

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

**注意**  
运行时间超过一小时的查询可能会超时。您仍可获得在查询超时之前处理的部分结果。  
如果您使用可选`--delivery-s3-uri`参数将查询结果传送到 S3 存储桶，则存储桶策略必须授予将查询结果传送到该存储桶的 CloudTrail权限。有关手动编辑存储桶策略的信息，请参阅[适用于 CloudTrail Lake 查询结果的 Amazon S3 存储桶策略](s3-bucket-policy-lake-query-results.md)。

## 使用获取有关查询的元数据 AWS CLI
<a name="lake-cli-describe-query"></a>

以下示例 AWS CLI **describe-query**命令获取有关查询的元数据，包括以毫秒为单位的查询运行时间、扫描和匹配的事件数、扫描的总字节数以及查询状态。`BytesScanned` 值与账户支付查询费用的总字节数匹配，除非查询仍在运行。如果查询结果已传送到 S3 存储桶，则响应还会提供 S3 URI 和交付状态。

您可以指定 `--query-id` 或 `--query-alias` 参数的值。指定 `--query-alias` 参数会返回有关该别名的上次查询运行的信息。

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

以下为响应示例。

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

## 使用获取查询结果 AWS CLI
<a name="lake-cli-get-query-results"></a>

以下示例 AWS CLI **get-query-results** 命令获取查询的事件数据结果。您必须指定 `--query-id` 返回的 **start-query** 命令。`BytesScanned` 值与账户支付查询费用的总字节数匹配，除非查询仍在运行。可选参数包括 `--max-query-results`，以指定希望在单个页面上通过命令返回的最大结果数。如果结果数超过指定的 `--max-query-results` 值，请再次运行命令，添加返回 `NextToken` 值来获取下一页的结果。

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

**输出**

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

## 使用列出事件数据存储上的所有查询 AWS CLI
<a name="lake-cli-list-queries"></a>

以下示例 AWS CLI **list-queries** 命令返回过去七天内指定事件数据存储中的查询和查询状态的列表。您必须指定 ARN 或 `--event-data-store` ARN 值的 ID 后缀。或者，要缩短结果列表，您可以通过添加 `--start-time` 和 `--end-time` 参数和 `--query-status` 值来指定时间范围、格式化为时间戳。`QueryStatus` 的有效值包括 `QUEUED`、`RUNNING`、`FINISHED`、`FAILED` 或 `CANCELLED`。

**list-queries** 还有可选的分页参数。使用 `--max-results` 以指定希望在单个页面上通过命令返回的最大结果数。如果结果数超过指定的 `--max-results` 值，请再次运行命令，添加返回 `NextToken` 值来获取下一页的结果。

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

**输出**

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

## 使用取消正在运行的查询 AWS CLI
<a name="lake-cli-cancel-query"></a>

以下示例 AWS CLI **cancel-query**命令取消状态为的查询。`RUNNING`您必须为 `--query-id` 指定一个值。当您运行 **cancel-query** 时，即使尚未完成 **cancel-query** 操作，查询状态也可能会显示为 `CANCELLED`。

**注意**  
取消的查询可能会产生费用。您的账户仍需为取消查询之前扫描的数据量支付费用。

以下是 CLI 示例。

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

**输出**

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