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

# CloudTrail 湖泊查询
<a name="cloudtrail-lake-queries"></a>

**注意**  
AWS CloudTrail 从 2026 年 5 月 31 日起，Lake 将不再向新客户开放。如果您想使用 CloudTrail Lake，请在该日期之前注册。现有客户可以继续正常使用该服务。有关更多信息，请参阅 [CloudTrail 湖泊可用性变更](cloudtrail-lake-service-availability-change.md)。

La CloudTrail ke 中的查询是用 SQL 编写的。您可以在 L CloudTrail ake E **ditor** 选项卡上生成查询，方法是从头开始用 SQL 编写查询，打开已保存的查询或示例查询并对其进行编辑，或者使用查询生成器根据英语提示生成查询。您无法用更改覆盖已包含的示例查询，但可以将其另存为新查询。有关允许的 SQL 查询语言的详细信息，请参阅[CloudTrail 湖泊 SQL 限制](query-limitations.md)。

无界查询（例如 `SELECT * FROM edsID`）会扫描事件数据存储中的所有数据。为了帮助控制成本，我们建议您通过为查询添加开始和结束 `eventTime` 时间戳，来限制查询。以下示例搜索指定事件数据存储中的所有事件，其中事件时间介于（`>`）2023 年 1 月 5 日下午 1:51 和（`<`）2023 年 1 月 19 日下午 1:51 之间。由于事件数据存储的保留期至少为七天，因此开始和结束 `eventTime` 值之间的最短时间跨度值也是七天。

```
SELECT *
FROM eds-ID
WHERE
     eventtime >='2023-01-05 13:51:00' and eventtime < ='2023-01-19 13:51:00'
```

有关如何优化查询的信息，请参阅 [优化 CloudTrail Lake 查询](lake-queries-optimization.md)。

**Topics**
+ [查询编辑器工具](#query-editor-format-controls)
+ [根据自然语言提示创建 CloudTrail Lake 查询](lake-query-generator.md)
+ [使用 CloudTrail 控制台查看示例查询](lake-console-queries.md)
+ [使用 CloudTrail 控制台创建或编辑查询](query-create-edit-query.md)
+ [使用控制台运行查询并保存查询结果](query-run-query.md)
+ [使用控制台查看查询结果](query-results.md)
+ [用自然语言汇总查询结果](query-results-summary.md)
+ [下载已保存的查询结果](view-download-cloudtrail-lake-query-results.md)
+ [验证 CloudTrail Lake 保存的查询结果](cloudtrail-query-results-validation.md)
+ [优化 CloudTrail Lake 查询](lake-queries-optimization.md)
+ [使用运行和管理 CloudTrail Lake 查询 AWS CLI](lake-queries-cli.md)

## 查询编辑器工具
<a name="query-editor-format-controls"></a>

查询编辑器右上角的工具栏提供多个命令，以帮助编写 SQL 查询和对其进行格式化。

![\[查询编辑器工具栏\]](http://docs.aws.amazon.com/zh_cn/awscloudtrail/latest/userguide/images/query-editor-toolbar.png)


下表介绍了工具栏上的命令。
+ **撤消**：恢复在查询编辑器中所做的上次内容更改。
+ **重做**：重复在查询编辑器中所做的上次内容更改。
+ **已选择格式**：根据 SQL 格式和间距惯例，排列查询编辑器内容。
+ **已选择注释/取消注释**：如果尚未注释查询的选定部分，则对其进行注释。如果选定部分已进行注释，则选择此选项会删除注释。

# 根据自然语言提示创建 CloudTrail Lake 查询
<a name="lake-query-generator"></a>

您可以使用 CloudTrail Lake 查询生成器根据您提供的英语提示生成查询。查询生成器使用生成式人工智能（生成式 AI）根据您的提示生成 ready-to-use SQL 查询，然后您可以选择在 Lake 的查询编辑器中运行该查询，也可以进行进一步微调。您无需对 SQL 或 CloudTrail 事件字段有广泛了解即可使用查询生成器。

提示可以是关于 La CloudTrail ke 事件数据存储中事件数据的问题或陈述。例如，您可以输入 "What are my top errors in the past month?" 和 “Give me a list of users that used SNS.” 等提示

提示的长度至少为 3 个字符，最多为 500 个字符。

生成查询不收取任何费用；但是，当您运行查询时，需要根据扫描的优化和压缩数据量支付费用。为了帮助控制成本，我们建议您通过为查询添加开始和结束 `eventTime` 时间戳来限制查询。

**注意**  
您可以通过选择生成的查询下方的大拇指向上或大拇指向下按钮来提供有关生成的查询的反馈。当您提供反馈时， CloudTrail 保存您的提示和生成的查询。  
请勿在提示中包含任何个人身份信息、机密信息或敏感信息。  
此功能使用生成式 AI 大型语言模型 (LLMs)；我们建议仔细检查 LLM 响应。

**注意**  
CloudTrail 将在生成查询时自动选择您所在地理区域内处理推理请求的最佳区域。这样可以最大限度地提高可用计算资源和模型可用性，并提供最佳的客户体验。您的数据将仅存储在请求发起的区域，但是，输入提示和输出结果可能会在该区域之外进行处理。所有数据都将通过 Amazon 的安全网络进行加密传输。  
 CloudTrail 会将您的推理请求安全地路由到发出请求的地理区域内的可用计算资源，如下所示：  
来自美国的推理请求将在美国境内处理
来自日本境内的推理请求将在日本国内处理
来自澳大利亚的推理请求将在澳大利亚境内处理。
来自欧盟的推理请求将在欧盟内部处理
来自印度的推理请求将在印度境内处理
 要选择退出查询生成功能，您可以明确拒绝或从正在使用的 iam 策略中删除该`cloudtrail:GenerateQuery`操作。

您可以使用 CloudTrail 控制台和访问查询生成器 AWS CLI。

------
#### [ CloudTrail console ]

**在 CloudTrail 控制台上使用查询生成器**

1. 登录 AWS 管理控制台 并打开 CloudTrail 控制台，网址为[https://console.aws.amazon.com/cloudtrail/](https://console.aws.amazon.com/cloudtrail/)。

1.  在导航窗格中，在 **Lake** 下，选择**查询**。

1. 在**查询**页面上，选择**编辑器**选项卡。

1. 选择要为其创建查询的事件数据存储。

1. 在**查询生成器**区域中，使用纯英语输入提示。有关示例，请参阅 [提示示例](#lake-query-generator-examples)。

1. 选择**生成查询**。查询生成器将尝试根据您的提示生成查询。如果成功，查询生成器将在编辑器中提供 SQL 查询。如果提示失败，请改写提示并重试。

1. （可选）您可以提供有关生成的查询的反馈。要提供反馈，请选择提示下方出现的竖起大拇指或竖起大拇指按钮。当您提供反馈时， CloudTrail 保存您的提示和生成的查询。

1. （可选）选择**运行**以运行查询。
**注意**  
运行查询时，您需要根据扫描的优化和压缩数据量支付费用。为了帮助控制成本，我们建议您通过为查询添加开始和结束 `eventTime` 时间戳来限制查询。

1. （可选）如果您运行查询并得到结果，则可以选择**汇总结果**来以英语生成查询结果的自然语言摘要。此选项使用生成式人工智能来生成摘要。有关此选项的更多信息，请参阅 [用自然语言汇总查询结果](query-results-summary.md)。

   您可以通过选择显示在所生成摘要下方的赞或踩按钮，来提供有关此摘要的反馈。
**注意**  
La CloudTrail ke 的查询摘要功能处于预览版，可能会发生变化。此功能在以下区域可用：亚太地区（东京）、美国东部（弗吉尼亚州北部）和美国西部（俄勒冈州）。

------
#### [ AWS CLI ]

**使用生成查询 AWS CLI**

运行 `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**

使用上一个示例中的 `start-query` 命令输出的 `QueryAlias` 运行 `generate-query` 命令。您还可以选择通过提供 `QueryStatement` 来运行 `start-query` 命令。

```
aws cloudtrail start-query --query-alias AWSCloudTrail-UUID
```

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

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

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

------

## 所需的权限
<a name="lake-query-generator-permissions."></a>

[https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSCloudTrail_FullAccess.html](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSCloudTrail_FullAccess.html) 和 [https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AdministratorAccess.html](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AdministratorAccess.html) 托管式策略都提供了使用此功能所需的权限。

您也可以将 `cloudtrail:GenerateQuery` 操作包含在新的或现有的客户托管策略或内联策略中。

## 区域支持
<a name="lake-query-generator-regions"></a>

以下版本支持此功能 AWS 区域：
+ 亚太地区（孟买）区域（ap-south-1）
+ 亚太地区（悉尼）区域（ap-southeast-2）
+ 亚太地区（东京）区域（ap-northeast-1）
+ 加拿大（中部）区域（ca-central-1）
+ 欧洲（伦敦）区域（eu-west-2）
+ 美国东部（弗吉尼亚州北部）区域（us-east-1）
+ 美国西部（俄勒冈州）区域（us-west-2）

## 限制
<a name="lake-query-generator-limitations"></a>

下面是查询生成器的限制：
+ 查询生成器只能接受英文提示。
+ 查询生成器只能对收集事件（管理事件、数据 CloudTrail 事件、网络活动事件）的事件数据存储生成查询。
+ 查询生成器无法为与 La CloudTrail ke 事件数据无关的提示生成查询。

## 提示示例
<a name="lake-query-generator-examples"></a>

本节提供示例提示以及根据提示生成的结果 SQL 查询。

如果您选择运行本节中的示例查询，请*eds-id*替换为要查询的事件数据存储的 ID，并将时间戳替换为适合您的用例的时间戳。时间戳采用以下格式：`YYYY-MM-DD HH:MM:SS`。

**提示**：What are my top errors in the past month?

**SQL 查询：**

```
SELECT
    errorMessage,
    COUNT(*) as eventCount
FROM
    eds-id
WHERE
    errorMessage IS NOT NULL
AND eventTime >= timestamp '2024-05-01 00:00:00'
AND eventTime <= timestamp '2024-05-31 23:59:59'
GROUP BY 1
ORDER BY 2 DESC
LIMIT 2;
```

**提示**：Give me a list of users that used Amazon SNS.

**SQL 查询：**

```
SELECT
    DISTINCT userIdentity.arn AS user
FROM
    eds-id
WHERE
    eventSource = 'sns.amazonaws.com'
```

**提示**：What are my API counts each day for read and write events in the past month?

**SQL 查询：**

```
SELECT date(eventTime) AS event_date,
    SUM(
        CASE
            WHEN readonly = true THEN 1
            ELSE 0
        END
    ) AS read_events,
    SUM(
        CASE
            WHEN readonly = false THEN 1
            ELSE 0
        END
    ) AS write_events
FROM
    eds-id
WHERE
    eventTime >= timestamp '2024-05-04 00:00:00'
AND eventTime <= timestamp '2024-06-04 23:59:59'
GROUP BY 1
ORDER BY 1 ASC;
```

**提示**：Show any events with access denied errors for the past three weeks.

**SQL 查询：**

```
SELECT *
FROM 
  eds-id
WHERE
  WHERE (errorCode = 'AccessDenied' OR errorMessage = 'Access Denied')
AND eventTime >= timestamp '2024-05-16 01:00:00'
AND eventTime <= timestamp '2024-06-06 01:00:00'
```

**提示**：Query the number of calls each operator performed on the date *2024-05-01*. The operator is a principal tag.

**SQL 查询：**

```
SELECT element_at(
        eventContext.tagContext.principalTags,
        'operator'
    ) AS operator,
    COUNT(*) AS eventCount
FROM
    eds-id
WHERE eventtime >= '2024-05-01 00:00:00'
    AND eventtime < '2024-05-01 23:59:59'
GROUP BY 1
ORDER BY 2 DESC;
```

**提示**：Give me all event IDs that touched resources within the CloudFormation stack with name *myStack* on the date *2024-05-01*.

**SQL 查询：**

```
SELECT eventID
FROM
    eds-id
WHERE any_match(
        eventContext.tagcontext.resourcetags,
        rt->element_at(rt.tags, 'aws:cloudformation:stack-name') = 'myStack'
    )
    AND eventtime >= '2024-05-01 00:00:00'
    AND eventtime < '2024-05-01 23:59:59'
```

**提示**：Count the number of events grouped by resource tag '*solution*' values, listing them in descending order of count.

**SQL 查询：**

```
SELECT element_at(rt.tags, 'solution'),
    count(*) as event_count
FROM
    eds-id,
    unnest(eventContext.tagContext.resourceTags) as rt
WHERE eventtime < '2025-05-14 19:00:00'
GROUP BY 1
ORDER BY 2 DESC;
```

**提示**：Find all Amazon S3 data events where resource tag Environment has value *prod*.

**SQL 查询：**

```
SELECT *
FROM
    eds-id
WHERE eventCategory = 'Data'
    AND eventSource = 's3.amazonaws.com'
    AND eventtime >= '2025-05-14 00:00:00'
    AND eventtime < '2025-05-14 20:00:00'
    AND any_match(
        eventContext.tagContext.resourceTags,
        rt->element_at(rt.tags, 'Environment') = 'prod'
    )
```

# 使用 CloudTrail 控制台查看示例查询
<a name="lake-console-queries"></a>

 CloudTrail 控制台提供了许多示例查询，可以帮助您开始编写自己的查询。

CloudTrail 查询会根据扫描的数据量收取费用。为了帮助控制成本，我们建议您通过为查询添加开始和结束 `eventTime` 时间戳，来限制查询。有关 CloudTrail 定价的更多信息，请参阅[AWS CloudTrail 定价](https://aws.amazon.com/cloudtrail/pricing/)。

**注意**  
您还可以查看 GitHub 社区创建的查询。有关更多信息，请参阅 GitHub 网站上的 [CloudTrailLake 示例查询](https://github.com/aws-samples/cloud-trail-lake-query-samples)。 AWS CloudTrail 尚未评估中的查询 GitHub。

**查看和运行示例查询**

1. 登录 AWS 管理控制台 并打开 CloudTrail 控制台，网址为[https://console.aws.amazon.com/cloudtrail/](https://console.aws.amazon.com/cloudtrail/)。

1.  在导航窗格中，在 **Lake** 下，选择**查询**。

1. 在**查询**页面上，选择**示例查询**选项卡。

1. 从列表中选择一个示例查询，或者输入要搜索的短语。在此示例中，我们将通过选择**查询名称**来打开**调查谁对控制台进行了更改**查询。这将在 **Editor**（编辑器）选项卡中打开此查询。
**注意**  
默认情况下，此页面使用基本搜索功能。如果您的权限策略尚未提供权限，则可以通过为 `cloudtrail:SearchSampleQueries` 操作添加权限来改进搜索功能。[https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSCloudTrail_FullAccess.html](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSCloudTrail_FullAccess.html) 托管式策略提供执行 `cloudtrail:SearchSampleQueries` 操作的权限。  
![\[示例查询选项卡\]](http://docs.aws.amazon.com/zh_cn/awscloudtrail/latest/userguide/images/query-sample-console.png)

1. 在**编辑器**选项卡上，选择要为其运行查询的事件数据存储。当您从列表中选择事件数据存储时， CloudTrail 会在查询编辑器的`FROM`行中自动填充事件数据存储 ID。  
![\[为查询选择事件数据存储\]](http://docs.aws.amazon.com/zh_cn/awscloudtrail/latest/userguide/images/query-editor-console.png)

1. 选择**运行**以运行查询。

   **命令输出**选项卡显示有关查询的元数据，例如查询是否成功、匹配的记录数量以及查询的运行时间。  
![\[查看查询状态\]](http://docs.aws.amazon.com/zh_cn/awscloudtrail/latest/userguide/images/query-console-status.png)

   **查询结果**选项卡显示选定事件数据存储中与查询匹配的事件数据。  
![\[查看查询结果\]](http://docs.aws.amazon.com/zh_cn/awscloudtrail/latest/userguide/images/query-console-results.png)

有关编辑查询的更多信息，请参阅 [使用 CloudTrail 控制台创建或编辑查询](query-create-edit-query.md)。有关运行查询和保存查询结果的更多信息，请参阅[使用控制台运行查询并保存查询结果](query-run-query.md)。

# 使用 CloudTrail 控制台创建或编辑查询
<a name="query-create-edit-query"></a>

在本演练中，我们打开其中一个示例查询，对其进行编辑，以查找名为 `Alice` 的特定用户执行的操作，然后将其另存为新查询。如果您已保存查询，您也可以在 **Saved queries**（保存的查询）选项卡上编辑已保存的查询。为了帮助控制成本，我们建议您通过为查询添加开始和结束 `eventTime` 时间戳，来限制查询。

1. 登录 AWS 管理控制台 并打开 CloudTrail 控制台，网址为[https://console.aws.amazon.com/cloudtrail/](https://console.aws.amazon.com/cloudtrail/)。

1.  在导航窗格中，在 **Lake** 下，选择**查询**。

1. 在**查询**页面上，选择**示例查询**选项卡。

1. 通过选择**查询名称**打开示例查询。这将在 **Editor**（编辑器）选项卡中打开此查询。在此示例中，我们将选择名为**调查用户操作**的查询，然后编辑查询，以查找名为 `Alice` 的特定用户的操作。

1. 在**编辑器**选项卡中，编辑 `WHERE` 行以指定要调查的用户，并根据需要更新 `eventTime` 值。的值`FROM`是事件数据存储 ARN 的 ID 部分，在您选择事件数据存储 CloudTrail 时会自动填充。

   ```
   SELECT
       eventID, eventName, eventSource, eventTime, userIdentity.arn AS user
   FROM
       event-data-store-id
   WHERE
       userIdentity.arn LIKE '%Alice%'
       AND eventTime > '2023-06-23 00:00:00' AND eventTime < '2023-06-26 00:00:00'
   ```

1. 您可以运行查询，然后再保存，以验证查询是否有效。要运行查询，请从 **Event data store**（事件数据存储）下拉列表中选择事件数据存储，然后选择 **Run**（运行）。查看 **Command output**（命令输出）选项卡的 **Status**（状态）列中的活跃查询，以验证查询是否成功运行。

1. 在您更新示例查询后，请选择**保存**。

1. 在 **Save query**（保存查询）中，输入查询的名称和描述。选择 **Save query**（保存查询），将您的更改保存为新查询。要放弃对查询的更改，请选择 **Cancel**（取消），或者关闭 **Save query**（保存查询）窗口。  
![\[保存已更改的查询\]](http://docs.aws.amazon.com/zh_cn/awscloudtrail/latest/userguide/images/query-save.png)
**注意**  
保存的查询与您的浏览器绑定；如果您使用不同的浏览器或不同的设备访问 CloudTrail 控制台，则保存的查询不可用。

1. 打开 **Saved queries**（已保存查询）选项卡，以查看表中的新查询。  
![\[显示新保存的查询的“已保存的查询”选项卡\]](http://docs.aws.amazon.com/zh_cn/awscloudtrail/latest/userguide/images/query-saved-table.png)

# 使用控制台运行查询并保存查询结果
<a name="query-run-query"></a>

选择或保存查询后，您可以在事件数据存储中运行查询。

 运行查询时，您可以选择将查询结果保存到 Amazon S3 存储桶。在 CloudTrail Lake 中运行查询时，会根据查询扫描的数据量产生费用。将查询结果保存到 S3 存储桶不会产生额外的 CloudTrail Lake 费用，但会收取 S3 存储费用。有关 S3 定价的更多信息，请参阅 [Amazon S3 定价](https://aws.amazon.com/s3/pricing/)。

 保存查询结果时，查询结果可能会先显示在 CloudTrail 控制台中，然后才能在 S3 存储桶中查看，因为查询扫描完成后才会 CloudTrail 提供查询结果。虽然大多数查询会在几分钟内完成，但根据事件数据存储的大小，将查询结果传送 CloudTrail 到 S3 存储桶可能需要更长的时间。 CloudTrail 以压缩的 gzip 格式将查询结果传送到 S3 存储桶。平均而言，查询扫描完成后，传送到 S3 存储桶的每 GB 数据预计将出现 60 至 90 秒的延迟。

**使用 La CloudTrail ke 运行查询**

1. 登录 AWS 管理控制台 并打开 CloudTrail 控制台，网址为[https://console.aws.amazon.com/cloudtrail/](https://console.aws.amazon.com/cloudtrail/)。

1.  在导航窗格中，在 **Lake** 下，选择**查询**。

1. 在**已保存查询**或**示例查询**选项卡中，通过选择**查询名称**来选择要运行的查询。

1. 在 **Editor**（编辑器）选项卡的 **Event data store**（事件数据存储）中，从下拉列表中选择事件数据存储。

1. （可选）在 **Editor**（编辑器）选项卡上，选择 **Save results to S3**（将结果保存到 S3）以将查询结果保存到 S3 存储桶。当您选择默认 S3 存储桶时， CloudTrail 会创建并应用所需的存储桶策略。如果您选择默认 S3 存储桶，则您的 IAM 策略需要包含 `s3:PutEncryptionConfiguration` 操作的权限，因为默认情况下，存储桶已启用服务器端加密。有关保存查询结果的更多信息，请参阅 [有关已保存查询结果的其他信息](#save-query-results)。
**注意**  
 要使用其他存储桶，请指定存储桶名称，或选择 **Browse S3**（浏览 S3）以选择存储桶。存储桶策略必须授予向存储桶传送查询结果的 CloudTrail 权限。有关手动编辑存储桶策略的信息，请参阅[适用于 CloudTrail Lake 查询结果的 Amazon S3 存储桶策略](s3-bucket-policy-lake-query-results.md)。

1. 在 **Editor**（编辑器）选项卡上，选择 **Run**（运行）。

   根据事件数据存储的大小及其包含的数据天数，运行查询可能需要几分钟时间。**Command output**（命令输出）选项卡用于显示查询的状态以及查询是否已完成运行。在完成运行查询后，打开 **Query results**（查询结果）选项卡，以查看活跃查询（编辑器中当前显示的查询）的结果表。

**注意**  
运行时间超过一小时的查询可能会超时。您仍然可以获得在查询超时之前处理的部分结果。 CloudTrail 不会将部分查询结果传送到 S3 存储桶。要避免超时，您可以通过指定较短的时间范围来优化查询，从而限制扫描的数据量。

## 有关已保存查询结果的其他信息
<a name="save-query-results"></a>

保存查询结果后，可从 S3 存储桶下载已保存的查询结果。有关寻找和下载已保存查询结果的更多信息，请参阅 [下载已保存的查询结果](view-download-cloudtrail-lake-query-results.md)。

您还可以验证已保存的查询结果，以确定查询结果在 CloudTrail 传送查询结果后是已修改、删除还是未更改。有关验证已保存查询结果的更多信息，请参阅 [验证 CloudTrail Lake 保存的查询结果](cloudtrail-query-results-validation.md)。

## 示例：将查询结果保存到 Amazon S3 存储桶
<a name="scenario-lake-save-queries"></a>

此演练为您展示如何将查询结果保存到 S3 存储桶中，然后下载这些查询结果。

**将查询结果保存到 Amazon S3 存储桶中**

1. 登录 AWS 管理控制台 并打开 CloudTrail 控制台，网址为[https://console.aws.amazon.com/cloudtrail/](https://console.aws.amazon.com/cloudtrail/)。

1.  在导航窗格中，在 **Lake** 下，选择**查询**。

1. 在**示例查询**或**已保存的查询**选项卡上，通过选择**查询名称**来选择要运行的查询。在此示例中，我们将选择名为**调查用户操作**的示例查询。

1. 在 **Editor**（编辑器）选项卡的 **Event data store**（事件数据存储）中，从下拉列表中选择事件数据存储。从列表中选择事件数据存储时， CloudTrail 会自动填充`From`行中的事件数据存储 ID。

1. 在此示例查询中，我们将编辑 `userIdentity.ARN` 值以指定名为 `Admin` 的用户，并保留 `eventTime` 的默认值。运行查询时，您需要按扫描的数据量付费。为了帮助控制成本，我们建议您通过为查询添加开始和结束 `eventTime` 时间戳，来限制查询。  
![\[编辑示例查询中的 userIdentity.ARN 值\]](http://docs.aws.amazon.com/zh_cn/awscloudtrail/latest/userguide/images/sample-query-edit.png)

1. 选择**将结果保存到 S3 中**以将查询结果保存到 S3 存储桶中。当您选择默认 S3 存储桶时， CloudTrail 会创建并应用所需的存储桶策略。如果您选择默认 S3 存储桶，则您的 IAM 策略需要包含 `s3:PutEncryptionConfiguration` 操作的权限，因为默认情况下，存储桶已启用服务器端加密。在此示例中，我们将使用默认的 S3 存储桶。
**注意**  
 要使用其他存储桶，请指定存储桶名称，或选择 **Browse S3**（浏览 S3）以选择存储桶。存储桶策略必须授予向存储桶传送查询结果的 CloudTrail 权限。有关手动编辑存储桶策略的信息，请参阅[适用于 CloudTrail Lake 查询结果的 Amazon S3 存储桶策略](s3-bucket-policy-lake-query-results.md)。  
![\[为保存的查询结果选择了 S3 存储桶。\]](http://docs.aws.amazon.com/zh_cn/awscloudtrail/latest/userguide/images/save-query-results.png)

1. 选择**运行**。根据事件数据存储的大小及其包含的数据天数，运行查询可能需要几分钟时间。**Command output**（命令输出）选项卡用于显示查询的状态以及查询是否已完成运行。在完成运行查询后，打开 **Query results**（查询结果）选项卡，以查看活跃查询（编辑器中当前显示的查询）的结果表。

1. 将保存的查询结果传送到您的 S3 存储桶 CloudTrail 后，“**交付状态**” 列将提供指向 S3 存储桶的链接，其中包含您保存的查询结果[文件以及可用于验证保存的查询结果的签名文件](cloudtrail-query-results-validation.md#cloudtrail-results-file-validation-sign-file-structure)。选择**在 S3 中查看**以查看 S3 存储桶中的查询结果文件和签名文件。
**注意**  
 保存查询结果时，查询结果可能会先显示在 CloudTrail 控制台中，然后才能在 S3 存储桶中查看，因为查询扫描完成后才会 CloudTrail 提供查询结果。虽然大多数查询会在几分钟内完成，但根据事件数据存储的大小，将查询结果传送 CloudTrail 到 S3 存储桶可能需要更长的时间。 CloudTrail 以压缩的 gzip 格式将查询结果传送到 S3 存储桶。平均而言，查询扫描完成后，传送到 S3 存储桶的每 GB 数据预计将出现 60 至 90 秒的延迟。  
![\[命令输出选项卡上的查询传送状态\]](http://docs.aws.amazon.com/zh_cn/awscloudtrail/latest/userguide/images/query-delivery-status.png)

1. 要下载查询结果，请选择查询结果文件（在此示例中为 `result_1.csv.gz`），然后选择**下载**。  
![\[下载查询结果文件\]](http://docs.aws.amazon.com/zh_cn/awscloudtrail/latest/userguide/images/download-query-results.png)

有关验证保存的查询结果的信息，请参阅 [验证 CloudTrail Lake 保存的查询结果](cloudtrail-query-results-validation.md)。

# 使用控制台查看查询结果
<a name="query-results"></a>

查询完成后，您可以查看其结果。查询结果在查询完成后的七天内可用。您可以在 **Query results**（查询结果）选项卡上查看活跃查询的结果，也可以在 **Lake** 主页的 **Results history**（结果历史记录）选项卡上访问所有最近查询的结果。

查询结果可以从较早的查询运行更改为较新的查询，因为可以在查询之间记录查询期间较新的事件。

保存查询结果时，查询结果可能会先显示在 CloudTrail 控制台中，然后才能在 S3 存储桶中查看，因为查询扫描完成后才会 CloudTrail 提供查询结果。虽然大多数查询会在几分钟内完成，但根据事件数据存储的大小，将查询结果传送 CloudTrail 到 S3 存储桶可能需要更长的时间。 CloudTrail 以压缩的 gzip 格式将查询结果传送到 S3 存储桶。 平均而言，查询扫描完成后，您预计每 GB 数据传输到 S3 存储桶就会有 60 到 90 秒的延迟。有关寻找和下载已保存查询结果的更多信息，请参阅 [下载已保存的查询结果](view-download-cloudtrail-lake-query-results.md)。

**注意**  
运行时间超过一小时的查询可能会超时。您仍然可以获得在查询超时之前处理的部分结果。 CloudTrail 不会将部分查询结果传送到 S3 存储桶。要避免超时，您可以通过指定较短的时间范围来优化查询，从而限制扫描的数据量。

**查看查询结果**

1. 如果尚未选中查询编辑器上的**查询结果**选项卡，请选择它。在活跃查询的 **Query results**（查询结果）选项卡中，每行表示与查询匹配的事件结果。通过在搜索栏中输入全部或部分事件字段值来筛选结果。要复制事件，请选择要复制的事件，然后选择**复制**。

1. （可选）选择**汇总结果**，以生成查询结果的自然语言摘要。摘要以英文提供。此选项使用生成式人工智能来生成摘要。有关此选项的更多信息，请参阅 [用自然语言汇总查询结果](query-results-summary.md)。

   您可以通过选择显示在所生成摘要下方的赞或踩按钮，来提供有关此摘要的反馈。
**注意**  
La CloudTrail ke 的查询摘要功能处于预览版，可能会发生变化。此功能在以下区域可用：亚太地区（东京）、美国东部（弗吉尼亚州北部）和美国西部（俄勒冈州）。

1. 在 **Command output**（命令输出）选项卡中，查看有关已运行查询的元数据，例如事件数据存储 ID、运行时间、扫描的结果数以及查询是否成功。如果您将查询结果保存到 Amazon S3 存储桶，则元数据还将包括指向包含已保存查询结果的 S3 存储桶的链接。

# 用自然语言汇总查询结果
<a name="query-results-summary"></a>

**注意**  
La CloudTrail ke 的查询摘要功能处于预览版，可能会发生变化。

**注意**  
CloudTrail 将在汇总查询的同时自动选择您所在地理区域内处理推理请求的最佳区域。这样可以最大限度地提高可用计算资源和模型可用性，并提供最佳的客户体验。您的数据将仅存储在请求发起的区域，但是，输入提示和输出结果可能会在该区域之外进行处理。所有数据都将通过 Amazon 的安全网络进行加密传输。  
 CloudTrail 会将您的推理请求安全地路由到发出请求的地理区域内的可用计算资源，如下所示：  
来自美国的推理请求将在美国境内处理
来自日本境内的推理请求将在日本国内处理
 要选择退出查询摘要功能，您可以明确拒绝或从正在使用的 iam 策略中删除该`cloudtrail:GenerateQueryResultsSummary`操作。

查询完成后，您可以从查询编辑器中的**查询结果**选项卡获取自然语言的查询结果摘要。此选项使用生成式人工智能来生成摘要。

**汇总查询结果**

1. 在查询编辑器的**查询结果**选项卡中，选择**汇总结果**以生成查询结果的自然语言摘要。摘要以英文提供。

1. （可选）通过选择显示在所生成摘要下方的赞或踩按钮，来提供有关此摘要的反馈。

如果相关的事件数据存储是使用 KMS 密钥加密的，则不能使用 KMS 密钥来对查询结果和摘要进行加密。查询结果和摘要由加密 CloudTrail。

对生成的摘要的访问权限是根据 `GetQueryResults`、`GenerateQueryResultsSummary` 和 KMS 权限进行授权的（如果相关的事件日期存储已使用 KMS 密钥加密）。生成摘要时，会 CloudTrail 记录一个`GenerateQueryResultsSummary`为可见性而命名的事件。

## 所需的权限
<a name="query-results-summary-permissions."></a>

[https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSCloudTrail_FullAccess.html](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSCloudTrail_FullAccess.html) 和 [https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AdministratorAccess.html](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AdministratorAccess.html) 托管式策略都提供了使用此功能所需的权限。

您也可以将 `cloudtrail:GenerateQueryResultsSummary` 和 `cloudtrail:GetQueryResults` 操作包含在新的或现有的客户托管策略或内联策略中。

如果与要汇总的查询结果相关的事件数据存储使用 KMS 密钥进行加密，则您还需要 KMS 密钥的权限。

## 区域支持
<a name="query-results-summary-regions"></a>

此功能在以下版本中可用 AWS 区域：
+ 亚太地区（东京）区域（ap-northeast-1）
+ 美国东部（弗吉尼亚州北部）区域（us-east-1）
+ 美国西部（俄勒冈州）区域（us-west-2）

## 限制
<a name="query-results-summary-limitations"></a>

此功能存在以下限制：
+ 摘要仅提供英文版本。
+ 摘要仅限于收集 CloudTrail 事件（管理事件、数据事件、网络活动事件）的事件数据存储。
+ 每个摘要都针对单个查询的结果。
+ 查询结果大小必须小于 250 KB。
+ 每月可汇总的查询结果配额为 3 MB。

# 下载已保存的查询结果
<a name="view-download-cloudtrail-lake-query-results"></a>

保存查询结果后，您需要能够找到包含查询结果的文件。 CloudTrail 将您的查询结果传送到您在保存查询结果时指定的 Amazon S3 存储桶。

**注意**  
 保存查询结果时，查询结果可能会先显示在控制台中，然后才能在 S3 存储桶中查看，因为查询扫描完成后才会 CloudTrail 提供查询结果。虽然大多数查询会在几分钟内完成，但根据事件数据存储的大小，将查询结果传送 CloudTrail 到 S3 存储桶可能需要更长的时间。 CloudTrail 以压缩的 gzip 格式将查询结果传送到 S3 存储桶。平均而言，查询扫描完成后，传送到 S3 存储桶的每 GB 数据预计将出现 60 至 90 秒的延迟。

**Topics**
+ [查找您的 CloudTrail Lake 已保存查询结果](#cloudtrail-find-lake-query-results)
+ [下载您的 CloudTrail Lake 已保存的查询结果](#cloudtrail-download-lake-query-results)

## 查找您的 CloudTrail Lake 已保存查询结果
<a name="cloudtrail-find-lake-query-results"></a>

CloudTrail 将查询结果发布到您的 S3 存储桶并签署文件。查询结果文件包含已保存查询的输出，并且签名文件会提供查询结果的签名和哈希值。您可以使用签名文件验证查询结果。有关验证查询结果的更多信息，请参阅[验证 CloudTrail Lake 保存的查询结果](cloudtrail-query-results-validation.md)。

要检索查询结果或签名文件，您可以使用 Amazon S3 控制台、Amazon S3 命令行界面（CLI）或 API。

**使用 Amazon S3 控制台查找查询结果和签名文件**

1. 打开 Simple Storage Service（Amazon S3）控制台。

1. 选择您指定的存储桶。

1. 在对象层次结构中导航，直至找到查询结果和签名文件。查询结果文件的扩展名为 .csv.gz，签名文件的扩展名为 .json。

您将看到一个与下面示例类似的对象层次结构，但具体存储桶名称、账户 ID、日期和查询 ID 有所不同。

```
All Buckets
    amzn-s3-demo-bucket
        AWSLogs
            Account_ID;
                CloudTrail-Lake
                    Query
                        2022
                            06
                              20
                                Query_ID
```

## 下载您的 CloudTrail Lake 已保存的查询结果
<a name="cloudtrail-download-lake-query-results"></a>

保存查询结果时，会将两种类型的文件 CloudTrail 传送到您的 Amazon S3 存储桶。
+ JSON 格式的签名文件，可用于验证查询结果文件。该签名文件名为 result\$1sign.json。有关签名文件的更多信息，请参阅[CloudTrail 签名文件结构](cloudtrail-query-results-validation.md#cloudtrail-results-file-validation-sign-file-structure)。
+ 一个或多个 CSV 格式的查询结果文件，其中包含查询结果。传送的查询结果文件数量取决于查询结果的总大小。查询结果文件的最大文件大小为 1 TB。每个查询结果文件都命名为 result\$1 *number* .csv.gz。例如，如果查询结果的总大小为 2 TB，则您将有两个查询结果文件，result\$11.csv.gz 和 result\$12.csv.gz。

 CloudTrail 查询结果和签名文件是 Amazon S3 对象。您可以使用 S3 控制台、 AWS Command Line Interface (CLI) 或 S3 API 来检索查询结果并签署文件。

 以下过程介绍了如何使用 Amazon S3 控制台下载查询结果和签名文件。

**使用 Amazon S3 控制台下载查询结果或签名文件**

1. 打开 Amazon S3 控制台。

1. 选择存储桶并选择要下载的文件。  
![\[CloudTrail 查询结果文件\]](http://docs.aws.amazon.com/zh_cn/awscloudtrail/latest/userguide/images/lake_query_results_S3.png)

1. 选择 **Download**（下载），然后按照提示保存文件。
**注意**  
某些浏览器（例如 Chrome）会自动为您提取查询结果文件。如果您的浏览器有这种功能，请跳到步骤 5。

1. 使用 [7-Zip](https://www.7-zip.org/) 等产品提取查询结果文件。

1. 打开查询结果或签名文件。

# 验证 CloudTrail Lake 保存的查询结果
<a name="cloudtrail-query-results-validation"></a>

要确定查询结果在 CloudTrail 传送查询结果后是修改、删除还是未更改，您可以使用 CloudTrail 查询结果完整性验证。该功能是使用业界标准算法构建的：哈希采用 SHA-256，数字签名采用带 RSA 的 SHA-256。这使得在不被发现的情况下修改、删除或伪造 CloudTrail 查询结果文件在计算上是不可行的。您可以使用命令行验证查询结果文件。

## 为什么使用它？
<a name="cloudtrail-query-results-validation-use-cases"></a>

在安全和事故调查中，经验证的查询结果文件非常重要。例如，经验证的查询结果文件可帮助您明确地断言查询结果文件未经更改。 CloudTrail 查询结果文件完整性验证过程还会让您知道查询结果文件是否已被删除或更改。

**Topics**
+ [为什么使用它？](#cloudtrail-query-results-validation-use-cases)
+ [使用验证保存的查询结果 AWS CLI](#cloudtrail-query-results-validation-cli)
+ [CloudTrail 签名文件结构](#cloudtrail-results-file-validation-sign-file-structure)
+ [CloudTrail 查询结果文件完整性验证的自定义实现](#cloudtrail-results-file-custom-validation)

## 使用验证保存的查询结果 AWS CLI
<a name="cloudtrail-query-results-validation-cli"></a>

您可以使用 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudtrail/verify-query-results.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudtrail/verify-query-results.html) 命令验证查询结果和签名文件的完整性。

### 先决条件
<a name="cloudtrail-query-results-validation-cli-prerequisites"></a>

要使用命令行验证查询结果的完整性，必须满足以下条件：
+ 您必须联机连接到 AWS。
+ 您必须使用 AWS CLI 版本 2。
+ 要在本地验证查询结果文件和签名文件，应满足以下条件：
  + 必须将查询结果文件和签名文件放入指定的文件路径。将文件路径指定为 **--local-export-path** 参数的值。
  + 不得重命名查询结果文件和签名文件。
+ 要在 S3 存储桶中验证查询结果文件和签名文件，应满足以下条件：
  + 不得重命名查询结果文件和签名文件。
  + 必须拥有包含查询结果文件和签名文件的 Amazon S3 存储桶的读取访问权限。
  + 指定的 S3 前缀必须包含查询结果文件和签名文件。将 S3 前缀指定为 **--s3-prefix** 参数的值。

### verify-query-results
<a name="cloudtrail-query-results-validation-cli-command"></a>

 **verify-query-results** 命令将每个查询结果文件的哈希值与签名文件中的 `fileHashValue` 进行比对，再验证签名文件中的 `hashSignature`，从而验证前述哈希值。

验证查询结果时，您可以使用 **--s3-bucket** 和 **--s3-prefix** 命令行选项来验证存储在 S3 存储桶中的查询结果文件和签名文件，也可以使用 **--local-export-path** 命令行选项对下载的查询结果文件和签名文件执行本地验证。

**注意**  
**verify-query-results** 命令与特定区域相关。必须指定**--region**全局选项才能验证特定项的查询结果 AWS 区域。

**verify-query-results** 命令的选项如下：

**--s3-bucket** *<string>*  
指定存储查询结果文件和签名文件的 S3 存储桶名称。此参数不能与 **--local-export-path** 一起使用。

**--s3-prefix** *<string>*  
指定包含查询结果文件和签名文件的 S3 文件夹的 S3 路径（例如 `s3/path/`）。此参数不能与 **--local-export-path** 一起使用。如果文件位于 S3 存储桶的根目录中，则无需提供此参数。

**--local-export-path** *<string>*  
指定包含查询结果文件和签名文件的本地目录（例如 `/local/path/to/export/file/`）。此参数不能与 **--s3-bucket** 或 **--s3-prefix** 一起使用。

#### 示例
<a name="cloudtrail-query-results-validation-cli-examples"></a>

以下示例使用 **--s3-bucket** 和 **--s3-prefix** 命令行选项来指定包含查询结果文件和签名文件的 S3 存储桶名称和前缀，从而验证查询结果。

```
aws cloudtrail verify-query-results --s3-bucket amzn-s3-demo-bucket --s3-prefix prefix --region region
```

以下示例使用 **--local-export-path** 命令行选项来指定查询结果文件和签名文件的本地路径，从而验证下载的查询结果。有关下载查询结果文件的更多信息，请参阅[下载您的 CloudTrail Lake 已保存的查询结果](view-download-cloudtrail-lake-query-results.md#cloudtrail-download-lake-query-results)。

```
aws cloudtrail verify-query-results --local-export-path local_file_path --region region
```

#### 验证结果
<a name="cloudtrail-query-results-validation-cli-command-messages"></a>

下表描述了查询结果文件和签名文件可能会出现的验证消息。


****  

| 文件类型 | 验证消息 | 说明 | 
| --- | --- | --- | 
| Sign file | Successfully validated sign and query result files | 签名文件的签名有效。其引用的查询结果文件可供检查。 | 
| Query result file |  `ValidationError: "File file_name has inconsistent hash value with hash value recorded in sign file, hash value in sign file is expected_hash, but get computed_hash`  | 验证失败，因为查询结果文件的哈希值与签名文件中的 fileHashValue 不相符。 | 
| Sign file |  `ValidationError: Invalid signature in sign file`  | 签名文件验证失败，因为签名无效。 | 

## CloudTrail 签名文件结构
<a name="cloudtrail-results-file-validation-sign-file-structure"></a>

签名文件包含保存查询结果时传送到 Amazon S3 存储桶的每个查询结果文件的名称、每个查询结果文件的哈希值以及文件的数字签名。数字签名和哈希值用于验证查询结果文件和签名文件本身的完整性。

### 签名文件位置
<a name="cloudtrail-results-file-validation-sign-file-location"></a>

签名文件将传送到遵循以下语法的 Amazon S3 存储桶位置。

```
s3://amzn-s3-demo-bucket/optional-prefix/AWSLogs/aws-account-ID/CloudTrail-Lake/Query/year/month/date/query-ID/result_sign.json
```

### 示例签名文件内容
<a name="cloudtrail-results-file-validation-sign-file-contents"></a>

以下示例签名文件包含 La CloudTrail ke 查询结果的信息。

```
{
  "version": "1.0",
  "region": "us-east-1",
  "files": [
    {
      "fileHashValue" : "de85a48b8a363033c891abd723181243620a3af3b6505f0a44db77e147e9c188",
      "fileName" : "result_1.csv.gz"
    }
  ],
  "hashAlgorithm" : "SHA-256",
  "signatureAlgorithm" : "SHA256withRSA",
  "queryCompleteTime": "2022-05-10T22:06:30Z",
  "hashSignature" : "7664652aaf1d5a17a12ba50abe6aca77c0ec76264bdf7dce71ac6d1c7781117c2a412e5820bccf473b1361306dff648feae20083ad3a27c6118172a81635829bdc7f7b795ebfabeb5259423b2fb2daa7d1d02f55791efa403dac553171e7ce5f9307d13e92eeec505da41685b4102c71ec5f1089168dacde702c8d39fed2f25e9216be5c49769b9db51037cb70a84b5712e1dffb005a74580c7fdcbb89a16b9b7674e327de4f5414701a772773a4c98eb008cca34228e294169901c735221e34cc643ead34628aabf1ba2c32e0cdf28ef403e8fe3772499ac61e21b70802dfddded9bea0ddfc3a021bf2a0b209f312ccee5a43f2b06aa35cac34638f7611e5d7",
  "publicKeyFingerprint" : "67b9fa73676d86966b449dd677850753"
}
```

### 签名文件字段描述
<a name="cloudtrail-results-file-validation-sign-file-descriptions"></a>

以下是对签名文件中每个字段的描述：

`version`  
签名文件的版本。

`region`  
用于保存查询结果的 AWS 账户的区域。

`files.fileHashValue`  
已压缩的查询结果文件内容的十六进制编码哈希值。

`files.fileName`  
查询结果文件的名称。

`hashAlgorithm`  
用于对查询结果文件进行哈希处理的哈希算法。

`signatureAlgorithm`  
用于对文件进行签名的算法。

`queryCompleteTime`  
表示何时将查询结果 CloudTrail 传送到 S3 存储桶。您可以使用此值来查找公钥。

`hashSignature`  
文件的哈希签名。

`publicKeyFingerprint`  
用于对文件进行签名的公钥的十六进制编码指纹。

## CloudTrail 查询结果文件完整性验证的自定义实现
<a name="cloudtrail-results-file-custom-validation"></a>

由于 CloudTrail 使用行业标准、公开可用的加密算法和哈希函数，因此您可以创建自己的工具来验证 CloudTrail 查询结果文件的完整性。当您将查询结果保存到 Amazon S3 存储桶时，会 CloudTrail 将签名文件发送到您的 S3 存储桶。您可以实施自己的验证解决方案以验证签名和查询结果文件。有关签名文件的更多信息，请参阅[CloudTrail 签名文件结构](#cloudtrail-results-file-validation-sign-file-structure)。

本主题介绍了签名文件的签名方式，并详述了实施验证签名文件及签名文件所引用查询结果文件的解决方案所需采取的步骤。

### 了解 CloudTrail 签名文件的签名方式
<a name="cloudtrail-results-file-custom-validation-how-cloudtrail-sign-files-are-signed"></a>

CloudTrail 签名文件使用 RSA 数字签名进行签名。对于每个签名文件，执行以下 CloudTrail操作：

1. 创建一个哈希列表，其中包含每个查询结果文件的哈希值。

1. 获取区域唯一的私钥。

1. 将此字符串的 SHA-256 哈希值和私钥传递给 RSA 签名算法（生成数字签名）。

1. 将签名的字节代码编码成十六进制格式。

1. 将数字签名放入签名文件中。

#### 数据签名字符串的内容
<a name="cloudtrail-results-file-custom-validation-data-signing-string-summary"></a>

数据签名字符串包含以空格分隔的每个查询结果文件的哈希值。签名文件列出了每个查询结果文件的 `fileHashValue`。

### 自定义验证实现步骤
<a name="cloudtrail-results-file-custom-validation-steps"></a>

实施自定义验证解决方案时，需要验证签名文件及其引用的查询结果文件。

#### 验证签名文件
<a name="cloudtrail-results-file-custom-validation-steps-sign"></a>

要验证签名文件，您需要其签名、与用于对其进行签名的私钥对应的公钥以及您计算的数据签名字符串。

1. 获取签名文件。

1. 验证是否已从签名文件的原始位置检索到签名文件。

1. 获取签名文件的十六进制编码签名。

1. 获取与用于对签名文件进行签名的私钥对应的公钥的十六进制编码指纹。

1. 检索与签名文件中的 `queryCompleteTime` 对应的时间范围的公钥。对于时间范围，请选择早于 `queryCompleteTime` 的 `StartTime` 和晚于 `queryCompleteTime` 的 `EndTime`。

1. 从检索到的公钥中，选择指纹与签名文件中的 `publicKeyFingerprint` 值匹配的公钥。

1. 使用包含以空格分隔的每个查询结果文件哈希值的哈希列表，重新创建用于验证签名文件签名的数据签名字符串。签名文件列出了每个查询结果文件的 `fileHashValue`。

   例如，如果签名文件的 `files` 数组包含以下三个查询结果文件，则哈希列表为“aaa bbb ccc”。

   ```
   “files": [

      {

           "fileHashValue" : “aaa”,

           "fileName" : "result_1.csv.gz"

      },
      {
      
           "fileHashValue" : “bbb”,
      
           "fileName" : "result_2.csv.gz"
     
      },
      {

           "fileHashValue" : “ccc”,
      
           "fileName" : "result_3.csv.gz"

      }
   ],
   ```

1. 将此字符串的 SHA-256 哈希值、公钥及签名作为参数传递给 RSA 签名验证算法，以验证签名。如果结果为 true，则签名文件有效。

#### 验证查询结果文件
<a name="cloudtrail-results-file-custom-validation-steps-logs"></a>

如果签名文件有效，请验证签名文件引用的查询结果文件。要验证查询结果文件的完整性，请计算其压缩内容的 SHA-256 哈希值，并将结果与签名文件中记录的查询结果文件中的 `fileHashValue` 进行比较。如果哈希值匹配，则查询结果文件有效。

以下部分详细介绍了验证过程。

#### A. 获取签名文件
<a name="cloudtrail-results-file-custom-validation-steps-get-the-sign-file"></a>

第一步是获取签名文件并获取公钥的指纹。

1. 从 Amazon S3 存储桶中获取要验证的查询结果的签名文件。

1. 接下来，从签名文件中获取 `hashSignature` 值。

1. 在签名文件中，从 `publicKeyFingerprint` 字段中获取与用于对文件进行签名的私钥对应的公钥的指纹。

#### B. 检索用于验证签名文件的公钥
<a name="cloudtrail-results-file-custom-validation-steps-retrieve-public-key"></a>

要获取用于验证签名文件的公钥，您可以使用 AWS CLI 或 CloudTrail API。在这两种情况下，您都需要指定要验证的签名文件的时间范围（即起始时间和结束时间）。使用与签名文件中的 `queryCompleteTime` 对应的时间范围。对于您指定的时间范围，可能会返回一个或多个公钥。返回的密钥的有效时间范围可能会发生重叠。

**注意**  
由于每个区域 CloudTrail 使用不同的 private/public 密钥对，因此每个签名文件都使用其区域独有的私钥进行签名。因此，当您验证来自特定区域的签名文件时，必须从同一区域检索其公钥。

##### 使用检 AWS CLI 索公钥
<a name="cloudtrail-results-file-custom-validation-steps-retrieve-public-key-cli"></a>

要使用检索签名文件的公钥 AWS CLI，请使用`cloudtrail list-public-keys`命令。此命令采用以下格式：

 `aws cloudtrail list-public-keys [--start-time <start-time>] [--end-time <end-time>]` 

start-time 和 end-time 参数为 UTC 时间戳且是可选的。如果未指定，则使用当前时间，且返回当前有效的一个或多个公钥。

 **示例响应** 

响应是代表所返回的一个或多个密钥的 JSON 对象的列表：

##### 使用 CloudTrail API 检索公钥
<a name="cloudtrail-results-file-custom-validation-steps-retrieve-public-key-api"></a>

要使用 CloudTrail API 检索签名文件的公钥，请将开始时间和结束时间值传递给 `ListPublicKeys` API。`ListPublicKeys` API 会返回与用于在指定时间范围对文件进行签名的私钥对应的公钥。对于每个公钥，此 API 还返回相应的指纹。

##### `ListPublicKeys`
<a name="cloudtrail-results-file-custom-validation-steps-list-public-keys"></a>

本部分介绍 `ListPublicKeys` API 的请求参数和响应元素。

**注意**  
`ListPublicKeys` 的二进制字段的编码可能随时发生变化。

 **请求参数** 


****  

| Name | 说明 | 
| --- | --- | 
|  StartTime  |  （可选）以 UTC 为单位指定查找 CloudTrail 签名文件公钥的时间范围的起始时间。如果 StartTime 未指定，则使用当前时间，并返回当前的公钥。 类型： DateTime   | 
|  EndTime  |  （可选）以 UTC 为单位指定查找 CloudTrail 签名文件公钥的时间范围的结束时间。如果 EndTime 未指定，则使用当前时间。 类型： DateTime   | 

 **响应元素** 

`PublicKeyList`：`PublicKey` 对象数组，包含：


****  

|  |  | 
| --- |--- |
|  名称  |  描述  | 
|  Value  |  DER 编码的公钥值（采用 PKCS \$11 格式）。 类型：Blob   | 
|  ValidityStartTime  |  公钥有效的起始时间。 类型： DateTime   | 
|  ValidityEndTime  |  公钥有效的结束时间。 类型： DateTime   | 
|  Fingerprint  |  公钥的指纹。指纹可用于识别验证签名文件所必需的公钥。 类型：字符串   | 

#### C. 选择要用于验证的公钥
<a name="cloudtrail-results-file-custom-validation-steps-choose-public-key"></a>

从 `list-public-keys` 或 `ListPublicKeys` 检索到的公钥中，选择指纹与签名文件的 `publicKeyFingerprint` 字段中记录的指纹匹配的公钥。此即为用于验证签名文件的公钥。

#### D. 重新创建数据签名字符串
<a name="cloudtrail-results-file-custom-validation-steps-recreate-data-signing-string"></a>

现在，您已拥有签名文件的签名及关联公钥，接下来，您需要计算数据签名字符串。算出数据签名字符串后，您就有了验证签名所需的输入。

数据签名字符串包含以空格分隔的每个查询结果文件的哈希值。重新创建此字符串后，您可以验证签名文件。

#### E. 验证签名文件
<a name="cloudtrail-results-file-custom-validation-steps-validate-sign-file"></a>

将重新创建的数据签名字符串、数字签名和公钥传递给 RSA 签名验证算法。如果输出为 true，则已验证签名文件的签名，且签名文件有效。

#### F. 验证查询结果文件
<a name="cloudtrail-results-file-custom-validation-steps-validate-log-files"></a>

验证签名文件后，您可以验证其引用的查询结果文件。签名文件包含查询结果文件的 SHA-256 哈希值。如果其中一个查询结果文件在 CloudTrail 交付后被修改，则 SHA-256 哈希值将发生变化，并且签名文件的签名将不匹配。

使用以下步骤验证签名文件的 `files` 数组中列出的查询结果文件。

1. 从签名文件中的 `files.fileHashValue` 字段检索文件的原始哈希值。

1. 使用 `hashAlgorithm` 中指定的哈希算法计算压缩的查询结果文件内容的哈希值。

1. 将您为每个查询结果文件生成的哈希值与签名文件中的 `files.fileHashValue` 进行比较。如果哈希值匹配，则查询结果文件有效。

### 离线验证签名和查询结果文件
<a name="cloudtrail-results-file-custom-validation-offline"></a>

离线验证签名和查询结果文件时，您通常可以按照前述部分中介绍的流程进行。但是，您必须考虑以下有关公钥的信息。

#### 公钥
<a name="cloudtrail-results-file-custom-validation-offline-public-keys"></a>

要进行离线验证，首先必须在线获取验证给定时间范围内的查询结果文件所需的公钥（例如，通过调用 `ListPublicKeys` 实现），然后将其离线存储。每当您需要验证超出指定的初始时间范围的其他文件时，都必须重复执行这一步。

### 示例验证代码段
<a name="cloudtrail-results-file-custom-validation-sample-code"></a>

以下示例片段提供了用于验证 CloudTrail 签名和查询结果文件的基本代码。基本代码是 online/offline 不可知论的；也就是说，由你来决定是否在联机连接的情况下实现它。 AWS建议在实现中使用 [Java Cryptography Extension（JCE）](https://en.wikipedia.org/wiki/Java_Cryptography_Extension)和 [Bouncy Castle](https://www.bouncycastle.org/) 作为安全提供程序。

示例代码段：
+ 如何创建用于验证签名文件签名的数据签名字符串。
+ 如何验证签名文件的签名。
+ 如何计算查询结果文件的哈希值，并将其与签名文件中列出的 `fileHashValue` 进行比较，以验证查询结果文件的真实性。

```
import org.apache.commons.codec.binary.Hex;
import org.bouncycastle.asn1.pkcs.PKCSObjectIdentifiers;
import org.bouncycastle.asn1.pkcs.RSAPublicKey;
import org.bouncycastle.asn1.x509.AlgorithmIdentifier;
import org.bouncycastle.asn1.x509.SubjectPublicKeyInfo;
import org.bouncycastle.jce.provider.BouncyCastleProvider;
import org.json.JSONArray;
import org.json.JSONObject;
 
import java.security.KeyFactory;
import java.security.MessageDigest;
import java.security.PublicKey;
import java.security.Security;
import java.security.Signature;
import java.security.spec.X509EncodedKeySpec;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import java.util.stream.Collectors;
 
 
public class SignFileValidationSampleCode {
 
    public void validateSignFile(String s3Bucket, String s3PrefixPath) throws Exception {
        MessageDigest messageDigest = MessageDigest.getInstance("SHA-256");
 
        // Load the sign file from S3 (using Amazon S3 Client) or from your local copy
        JSONObject signFile = loadSignFileToMemory(s3Bucket, String.format("%s/%s", s3PrefixPath, "result_sign.json"));
 
        // Using the Bouncy Castle provider as a JCE security provider - http://www.bouncycastle.org/
        Security.addProvider(new BouncyCastleProvider());
 
        List<String> hashList = new ArrayList<>();
 
        JSONArray jsonArray = signFile.getJSONArray("files");
 
        for (int i = 0; i < jsonArray.length(); i++) {
            JSONObject file = jsonArray.getJSONObject(i);
            String fileS3ObjectKey = String.format("%s/%s", s3PrefixPath, file.getString("fileName"));
 
            // Load the export file from S3 (using Amazon S3 Client) or from your local copy
            byte[] exportFileContent = loadCompressedExportFileInMemory(s3Bucket, fileS3ObjectKey);
            messageDigest.update(exportFileContent);
            byte[] exportFileHash = messageDigest.digest();
            messageDigest.reset();
            byte[] expectedHash = Hex.decodeHex(file.getString("fileHashValue"));
 
            boolean signaturesMatch = Arrays.equals(expectedHash, exportFileHash);
            if (!signaturesMatch) {
                System.err.println(String.format("Export file: %s/%s hash doesn't match.\tExpected: %s Actual: %s",
                        s3Bucket, fileS3ObjectKey,
                        Hex.encodeHexString(expectedHash), Hex.encodeHexString(exportFileHash)));
            } else {
                System.out.println(String.format("Export file: %s/%s hash match",
                        s3Bucket, fileS3ObjectKey));
            }
 
            hashList.add(file.getString("fileHashValue"));
        }
        String hashListString = hashList.stream().collect(Collectors.joining(" "));
 
        /*
            NOTE:
            To find the right public key to verify the signature, call CloudTrail ListPublicKey API to get a list
            of public keys, then match by the publicKeyFingerprint in the sign file. Also, the public key bytes
            returned from ListPublicKey API are DER encoded in PKCS#1 format:
 
            PublicKeyInfo ::= SEQUENCE {
                algorithm       AlgorithmIdentifier,
                PublicKey       BIT STRING
            }
 
            AlgorithmIdentifier ::= SEQUENCE {
                algorithm       OBJECT IDENTIFIER,
                parameters      ANY DEFINED BY algorithm OPTIONAL
            }
        */
        byte[] pkcs1PublicKeyBytes = getPublicKey(signFile.getString("queryCompleteTime"),
                signFile.getString("publicKeyFingerprint"));
        byte[] signatureContent = Hex.decodeHex(signFile.getString("hashSignature"));
 
        // Transform the PKCS#1 formatted public key to x.509 format.
        RSAPublicKey rsaPublicKey = RSAPublicKey.getInstance(pkcs1PublicKeyBytes);
        AlgorithmIdentifier rsaEncryption = new AlgorithmIdentifier(PKCSObjectIdentifiers.rsaEncryption, null);
        SubjectPublicKeyInfo publicKeyInfo = new SubjectPublicKeyInfo(rsaEncryption, rsaPublicKey);
 
        // Create the PublicKey object needed for the signature validation
        PublicKey publicKey = KeyFactory.getInstance("RSA", "BC")
                .generatePublic(new X509EncodedKeySpec(publicKeyInfo.getEncoded()));
 
        // Verify signature
        Signature signature = Signature.getInstance("SHA256withRSA", "BC");
        signature.initVerify(publicKey);
        signature.update(hashListString.getBytes("UTF-8"));
 
        if (signature.verify(signatureContent)) {
            System.out.println("Sign file signature is valid.");
        } else {
            System.err.println("Sign file signature failed validation.");
        }
 
        System.out.println("Sign file validation completed.");
    }
}
```

# 优化 CloudTrail Lake 查询
<a name="lake-queries-optimization"></a>

本页提供有关如何优化 CloudTrail Lake 查询以提高性能和可靠性的指导。它涵盖特定优化技术以及常见查询失败的解决方法。

**Topics**
+ [优化查询的建议](#lake-queries-tuning)
+ [查询失败的解决方法](#lake-queries-troubleshooting)

## 优化查询的建议
<a name="lake-queries-tuning"></a>

请按照本节中的建议优化您的查询。

**Topics**
+ [优化聚合](#query-optimization-aggregation)
+ [使用近似技术](#query-optimization-approximation)
+ [限制查询结果](#query-optimization-limit)
+ [优化 LIKE 查询](#query-optimization-like)
+ [使用 `UNION ALL` 代替 `UNION`](#query-optimization-union)
+ [仅包含必需列](#query-optimization-reqcolumns)
+ [缩小窗口函数范围](#query-optimization-windows)

### 优化聚合
<a name="query-optimization-aggregation"></a>

在 `GROUP BY` 子句中排除冗余列可以提高性能，因为列越少，所需的内存就越少。例如，在以下查询中，我们可以在冗余列上使用 `arbitrary` 函数（如 `eventType`）来提高性能。`eventType` 上的 `arbitrary` 函数用于从组中随机选择字段值，因为该值是相同的，不需要包含在 `GROUP BY` 子句中。

```
SELECT eventName, eventSource, arbitrary(eventType), count(*) 
FROM $EDS_ID 
GROUP BY eventName, eventSource
```

可以通过将 `GROUP BY` 中的字段列表按其唯一值计数（基数）降序进行排序来提高 `GROUP BY` 函数的性能。例如，在获取每种类型的事件数量时 AWS 区域，可以通过在函数中使用`eventName`、`awsRegion`顺序来提高性能`awsRegion`，`eventName`因为的唯一值`eventName`比`GROUP BY`函数的唯一值多`awsRegion`。

```
SELECT eventName, awsRegion, count(*) 
FROM $EDS_ID 
GROUP BY eventName, awsRegion
```

### 使用近似技术
<a name="query-optimization-approximation"></a>

每当不需要精确值来统计不同值时，请使用[近似聚合函数](https://trino.io/docs/current/functions/aggregate.html#approximate-aggregate-functions)来查找最频繁值。例如，[https://trino.io/docs/current/functions/aggregate.html#approx_distinct](https://trino.io/docs/current/functions/aggregate.html#approx_distinct) 使用的内存更少，运行速度比 `COUNT(DISTINCT fieldName)` 操作快。

### 限制查询结果
<a name="query-optimization-limit"></a>

如果查询只需要示例响应，请使用 `LIMIT` 条件将结果限制为少量行。否则，查询将返回大量结果，并且查询执行时间会更长。

将 `LIMIT` 与 `ORDER BY` 结合使用可更快地提供前 N 条或后 N 条记录的结果，因为它减少了所需的内存量和排序所需的时间。

```
SELECT * FROM $EDS_ID
ORDER BY eventTime 
LIMIT 100;
```

### 优化 LIKE 查询
<a name="query-optimization-like"></a>

您可以使用 `LIKE` 来查找匹配的字符串，但是对于长字符串，这将占用大量计算资源。大多数情况下，[https://trino.io/docs/current/functions/regexp.html#regexp_like](https://trino.io/docs/current/functions/regexp.html#regexp_like) 函数是一种更快的替代方案。

通常，您可以通过锚定要查找的子字符串来优化搜索。例如，如果您要查找某个前缀，则最好将“`substr`%”（而不是 %`substr`%）和 `LIKE` 运算符结合使用，并将“^`substr`”与 `regexp_like` 函数结合使用。

### 使用 `UNION ALL` 代替 `UNION`
<a name="query-optimization-union"></a>

`UNION ALL` 和 `UNION` 有两种方法可以将两个查询的结果合并为一个结果，但是 `UNION` 会移除重复项。`UNION` 需要处理所有记录并找到重复项，这需要占用大量内存和计算，但 `UNION ALL` 操作速度相对较快。除非需要对记录进行重复数据删除，否则请使用 `UNION ALL` 以获得最佳性能。

### 仅包含必需列
<a name="query-optimization-reqcolumns"></a>

如果您不需要某一列，请不要将其包含在查询中。查询需要处理的数据越少，运行速度就越快。如果您的查询在最外层查询中执行 `SELECT *`，则应将 `*` 更改为包含所需列的列表。

`ORDER BY` 子句按排序顺序返回查询结果。当对大量数据进行排序时，如果所需的内存不可用，则会将中间排序结果写入磁盘，这可能会减慢查询执行速度。如果您不严格要求对结果进行排序，请避免添加 `ORDER BY` 子句。此外，如果不是严格必需的，请避免将 `ORDER BY` 添加到内部查询中。

### 缩小窗口函数范围
<a name="query-optimization-windows"></a>

[窗口函数](https://trino.io/docs/current/functions/window.html)将它们操作的所有记录保存在内存中，以便计算其结果。当窗口非常大时，窗口函数可能会耗尽内存。要确保查询在可用内存限制内运行，请通过添加 `PARTITION BY` 子句来减小窗口函数操作的窗口的大小。

有时，使用窗口函数的查询可以在没有窗口函数的情况下重写。例如，您可以使用 [https://trino.io/docs/current/functions/aggregate.html#max_by](https://trino.io/docs/current/functions/aggregate.html#max_by) 或 [https://trino.io/docs/current/functions/aggregate.html#min_by](https://trino.io/docs/current/functions/aggregate.html#min_by) 等聚合函数，而不是使用 `row_number` 或 `rank`。

以下查询使用 `max_by` 来查找最近分配给每个 KMS 密钥的别名。

```
SELECT element_at(requestParameters, 'targetKeyId') as keyId, 
max_by(element_at(requestParameters, 'aliasName'), eventTime) as mostRecentAlias 
FROM $EDS_ID 
WHERE eventsource = 'kms.amazonaws.com' 
AND eventName in ('CreateAlias', 'UpdateAlias') 
AND eventTime > DATE_ADD('week', -1, CURRENT_TIMESTAMP) 
GROUP BY element_at(requestParameters, 'targetKeyId')
```

在这种情况下，`max_by` 函数会返回记录的别名以及组内的最新事件时间。与使用窗口函数的等效查询相比，此查询运行速度更快，占用的内存也更少。

## 查询失败的解决方法
<a name="lake-queries-troubleshooting"></a>

本节提供了常见查询失败的解决方法。

**Topics**
+ [由于响应太大，查询失败](#large-responses)
+ [由于资源耗尽，查询失败](#exhausted-resources)

### 由于响应太大，查询失败
<a name="large-responses"></a>

如果响应太大，导致出现消息 `Query response is too large`，则查询可能会失败。如果发生这种情况，您可以缩小聚合范围。

`array_agg` 等聚合函数可能导致查询响应中至少有一行非常大，从而导致查询失败。例如，由于所选 CloudTrail 事件的事件名称重复，使用`array_agg(eventName)`代替`array_agg(DISTINCT eventName)`会大大增加响应大小。

### 由于资源耗尽，查询失败
<a name="exhausted-resources"></a>

如果在执行联接、聚合和窗口函数等内存密集型操作期间，可用内存不足，则中间结果会溢出到磁盘，但是溢出会减慢查询执行速度，可能不足以防止查询失败并出现 `Query exhausted resources at this scale factor`。重试查询即可解决此问题。

如果即使在优化查询后仍存在上述错误，则可以使用事件的 `eventTime` 缩小查询范围，并按照原始查询时间范围的较小间隔多次执行查询。

# 使用运行和管理 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)
```