本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 使用查看路径的见解事件 Amazon CLI
本节介绍如何使用 Amazon CLI `lookup-events`和`list-insights-data`命令为启用了 Insights 事件的跟踪查找过去 90 天的 Insights 事件。有关如何在跟踪上启用 CloudTrail Insights 的信息，请参阅[使用记录跟踪的见解事件 Amazon CLI](insights-events-CLI-enable.md#insights-events-CLI-enable-trails)。
**注意**
您不能使用`lookup-events`或`list-insights-data`命令为事件数据存储查找 Insights 事件，但是，La CloudTrail ke 提供了许多针对 Insights 事件数据存储的示例查询。有关更多信息，请参阅 [查看 Insights 事件的示例查询](insights-events-view-lake.md#insights-events-lake-queries)。
此 `lookup-events` 命令具有以下选项：
+ `--end-time`
+ `--event-category`
+ `--max-results`
+ `--start-time`
+ `--lookup-attributes`
+ `--next-token`
+ `--generate-cli-skeleton`
+ `--cli-input-json`
此 `list-insights-data` 命令具有以下选项：
+ `--end-time`
+ `--data-type`
+ `--max-results`
+ `--start-time`
+ `--dimensions`
+ `--next-token`
+ `--generate-cli-skeleton`
+ `--cli-input-json`
有关使用的一般信息 Amazon Command Line Interface，请参阅《[Amazon Command Line Interface 用户指南》](https://docs.amazonaws.cn/cli/latest/userguide/)。
**Contents**
+ [先决条件](#aws-cli-prerequisites-for-insights)
+ [获取命令行帮助](#getting-command-line-help-insights)
+ [查找管理事件的 Insights 事件](#looking-up-management-insights-with-the-aws-cli)
+ [查找数据事件的 Insights 事件](#looking-up-data-insights-with-the-aws-cli)
+ [指定要返回的管理事件的 Insights 事件的数量](#specify-the-number-of-management-insights-to-return)
+ [指定要返回的数据事件的 Insights 事件数量](#specify-the-number-of-data-insights-to-return)
+ [按时间范围查找管理事件的 Insights 事件](#look-up-management-insights-by-time-range)
+ [按时间范围查找数据事件的 Insights 事件](#look-up-data-insights-by-time-range)
+ [按属性查找管理事件的 Insights 事件](#look-up-management-insights-by-attributes)
+ [属性查找示例](#attribute-lookup-example-insights)
+ [按维度查找数据事件的 Insights 事件](#look-up-data-insights-by-attributes)
+ [维度查询示例](#dimension-lookup-example-insights)
+ [为管理事件指定 Insights 事件的下一页结果](#specify-next-page-of-management-results)
+ [为管理事件指定 Insights 事件的下一页结果](#specify-next-page-of-data-results)
+ [从文件中获取管理事件的 Insights 事件的 JSON 输入](#json-input-from-file-managemenet-insights)
+ [从文件中获取数据事件的 Insights 事件的 JSON 输入](#json-input-from-file-data-insights)
+ [查找输出字段](#view-insights-events-cli-output-fields)
## 先决条件
+ 要运行 Amazon CLI 命令，必须安装 Amazon CLI。有关更多信息，请参阅 [Get started with the Amazon CLI](https://docs.amazonaws.cn/cli/latest/userguide/cli-chap-getting-started.html)。
+ 确保您的 Amazon CLI 版本高于 1.6.6。要验证 CLI 版本，请在命令行上运行 **aws --version**。
+ 要为 Amazon CLI 会话设置账户、区域和默认输出格式，请使用**aws configure**命令。有关更多信息，请参阅[配置 Amazon 命令行界面](https://docs.amazonaws.cn/cli/latest/userguide/cli-chap-getting-started.html)。
+ 要针对 API 调用率记录 Insights 事件，跟踪必须记录 `write` 管理事件。要针对 API 错误率记录 Insights 事件，跟踪必须记录 `read` 或 `write` 管理事件。
**注意**
这些 CloudTrail Amazon CLI 命令区分大小写。
## 获取命令行帮助
要查看 `lookup-events` 的命令行帮助，请键入以下命令。
```
aws cloudtrail lookup-events help
```
## 查找管理事件的 Insights 事件
要查看 50 个最新的 Insights 事件，请键入以下命令。
```
aws cloudtrail lookup-events --event-category insight
```
返回的事件看起来与下面的示例相似，
```
{
"NextToken": "kbOt5LlZe++mErCebpy2TgaMgmDvF1kYGFcH64JSjIbZFjsuvrSqg66b5YGssKutDYIyII4lrP4IDbeQdiObkp9YAlju3oXd12juEXAMPLE=",
"Events": [
{
"eventVersion": "1.09",
"eventTime": "2024-12-11T16:52:00Z",
"awsRegion": "us-east-1",
"eventID": "18378b1e-3653-433d-ba1e-aa11a5958f0c",
"eventType": "AwsCloudTrailInsight",
"recipientAccountId": "888888888888",
"sharedEventID": "fccb064f-dd07-4822-97c0-11115d8b91d4",
"insightDetails": {
"state": "Start",
"eventSource": "cloudtrail.amazonaws.com",
"eventName": "DescribeQuery",
"insightType": "ApiErrorRateInsight",
"errorCode": "QueryIdNotFoundException",
"sourceEventCategory": "Management",
"insightContext": {
"statistics": {
"baseline": {
"average": 0
},
"insight": {
"average": 1.2
},
"insightDuration": 5,
"baselineDuration": 11092
},
"attributions": [
{
"attribute": "userIdentityArn",
"insight": [
{
"value": "arn:aws:sts::888888888888:assumed-role/Admin",
"average": 1.2
}
],
"baseline": []
},
{
"attribute": "userAgent",
"insight": [
{
"value": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
"average": 1.2
}
],
"baseline": []
}
]
}
},
"eventCategory": "Insight"
},
{
"eventVersion": "1.09",
"eventTime": "2024-12-11T16:53:00Z",
"awsRegion": "us-east-1",
"eventID": "b32f10a0-f039-419a-bad7-e95468930a4f",
"eventType": "AwsCloudTrailInsight",
"recipientAccountId": "888888888888",
"sharedEventID": "fccb064f-dd07-4822-97c0-11115d8b91d4",
"insightDetails": {
"state": "End",
"eventSource": "cloudtrail.amazonaws.com",
"eventName": "DescribeQuery",
"insightType": "ApiErrorRateInsight",
"errorCode": "QueryIdNotFoundException",
"sourceEventCategory": "Management",
"insightContext": {
"statistics": {
"baseline": {
"average": 0
},
"insight": {
"average": 6
},
"insightDuration": 1,
"baselineDuration": 11092
},
"attributions": [
{
"attribute": "userIdentityArn",
"insight": [
{
"value": "arn:aws:sts::888888888888:assumed-role/Admin",
"average": 6
}
],
"baseline": []
},
{
"attribute": "userAgent",
"insight": [
{
"value": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
"average": 6
}
],
"baseline": []
}
]
}
},
"eventCategory": "Insight"
}
]
}
```
有关输出中与查找相关的字段的说明，请参阅这一主题中的[查找输出字段](#view-insights-events-cli-output-fields)部分。有关 Insights 事件中的字段的说明，请参阅 [CloudTrail 记录路径的 Insights 事件的内容](cloudtrail-insights-fields-trails.md)。
## 查找数据事件的 Insights 事件
要查看 50 个最新的 Insights 事件，请键入以下命令。
```
aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName
```
返回的事件看起来与下面的示例相似，
```
{
"NextToken": "kbOt5LlZe++mErCebpy2TgaMgmDvF1kYGFcH64JSjIbZFjsuvrSqg66b5YGssKutDYIyII4lrP4IDbeQdiObkp9YAlju3oXd12juEXAMPLE=",
"Events": [
{
"eventVersion": "1.09",
"eventTime": "2024-12-11T16:52:00Z",
"awsRegion": "us-east-2",
"eventID": "18378b1e-3653-433d-ba1e-aa11a5958f0c",
"eventType": "AwsCloudTrailInsight",
"recipientAccountId": "123456789012",
"sharedEventID": "fccb064f-dd07-4822-97c0-11115d8b91d4",
"insightDetails": {
"state": "Start",
"eventSource": "s3.amazonaws.com",
"eventName": "PutObject",
"insightType": "ApiErrorRateInsight",
"errorCode": "InvalidRequest",
"sourceEventCategory": "Data",
"insightContext": {
"statistics": {
"baseline": {
"average": 0
},
"insight": {
"average": 1.2
},
"insightDuration": 5,
"baselineDuration": 11092
},
"attributions": [
{
"attribute": "userIdentityArn",
"insight": [
{
"value": "arn:aws:sts::123456789012:assumed-role/Admin",
"average": 1.2
}
],
"baseline": []
},
{
"attribute": "userAgent",
"insight": [
{
"value": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
"average": 1.2
}
],
"baseline": []
}
]
},
"insightSource": "arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName"
},
"eventCategory": "Insight"
},
{
"eventVersion": "1.09",
"eventTime": "2024-12-11T16:53:00Z",
"awsRegion": "us-east-1",
"eventID": "b32f10a0-f039-419a-bad7-e95468930a4f",
"eventType": "AwsCloudTrailInsight",
"recipientAccountId": "123456789012",
"sharedEventID": "fccb064f-dd07-4822-97c0-11115d8b91d4",
"insightDetails": {
"state": "End",
"eventSource": "s3.amazonaws.com",
"eventName": "PutObject",
"insightType": "ApiErrorRateInsight",
"errorCode": "InvalidRequest",
"sourceEventCategory": "Data",
"insightContext": {
"statistics": {
"baseline": {
"average": 0
},
"insight": {
"average": 6
},
"insightDuration": 1,
"baselineDuration": 11092
},
"attributions": [
{
"attribute": "userIdentityArn",
"insight": [
{
"value": "arn:aws:sts::123456789012:assumed-role/Admin",
"average": 6
}
],
"baseline": []
},
{
"attribute": "userAgent",
"insight": [
{
"value": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
"average": 6
}
],
"baseline": []
}
]
},
"insightSource": "arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName"
},
"eventCategory": "Insight"
}
]
}
```
## 指定要返回的管理事件的 Insights 事件的数量
要指定要返回的管理事件的 Insights 事件数量，请键入以下命令。
```
aws cloudtrail lookup-events --event-category insight --max-results
```
的默认值（如果未指定）为 50。**可能的值介于 1 和 50 之间。以下示例返回一个结果。
```
aws cloudtrail lookup-events --event-category insight --max-results 1
```
## 指定要返回的数据事件的 Insights 事件数量
要指定要返回的数据事件的 Insights 事件数量，请键入以下命令。
```
aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName --max-results
```
的默认值（如果未指定）为 50。**可能的值介于 1 和 50 之间。以下示例返回一个结果。
```
aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName --max-results 1
```
## 按时间范围查找管理事件的 Insights 事件
过去 90 天内管理事件的见解事件可供查找。要指定时间范围，请键入以下命令。
```
aws cloudtrail lookup-events --event-category insight --start-time --end-time
```
`--start-time ` 指定仅返回在指定时间或之后（采用 UTC）发生的 Insights 事件。如果指定的开始时间晚于指定的结束时间，则将返回错误。
`--end-time ` 指定仅返回在指定时间或之前（采用 UTC）发生的 Insights 事件。如果指定的结束时间早于指定的开始时间，则将返回错误。
默认开始时间为过去 90 天内提供数据的最早日期。默认结束时间为在最接近当前时间发生事件的时间。
所有时间戳均采用 UTC 显示。
## 按时间范围查找数据事件的 Insights 事件
过去 90 天的数据事件洞察事件可供查找。要指定时间范围，请键入以下命令。
```
aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName --start-time --end-time
```
`--start-time ` 指定仅返回在指定时间或之后（采用 UTC）发生的 Insights 事件。如果指定的开始时间晚于指定的结束时间，则将返回错误。
`--end-time ` 指定仅返回在指定时间或之前（采用 UTC）发生的 Insights 事件。如果指定的结束时间早于指定的开始时间，则将返回错误。
默认开始时间为过去 90 天内提供数据的最早日期。默认结束时间为在最接近当前时间发生事件的时间。
所有时间戳均采用 UTC 显示。
## 按属性查找管理事件的 Insights 事件
要按属性进行筛选，请键入以下命令。
```
aws cloudtrail lookup-events --event-category insight --lookup-attributes AttributeKey=,AttributeValue=
```
您只能为每个 **lookup-events** 命令指定一个属性密钥-值对。以下是 `AttributeKey` 的有效 Insights 事件值。值的名称区分大小写。
+ `EventId`
+ `EventName`
+ `EventSource`
`AttributeValue` 的最大长度为 2000 个字符。在 2000 个字符限制中，以下字符（“`_`”、“` `”、“`,`”、“`\\n`”）算作两个字符。
### 属性查找示例
以下示例命令返回 `EventName` 值为 `PutRule` 的 Insights 事件。
```
aws cloudtrail lookup-events --event-category insight --lookup-attributes AttributeKey=EventName, AttributeValue=PutRule
```
以下示例命令返回 `EventId` 值为 `b5cc8c40-12ba-4d08-a8d9-2bceb9a3e002` 的 Insights 事件。
```
aws cloudtrail lookup-events --event-category insight --lookup-attributes AttributeKey=EventId, AttributeValue=b5cc8c40-12ba-4d08-a8d9-2bceb9a3e002
```
以下示例命令返回 `EventSource` 值为 `iam.amazonaws.com` 的 Insights 事件。
```
aws cloudtrail lookup-events --event-category insight --lookup-attributes AttributeKey=EventSource, AttributeValue=iam.amazonaws.com
```
## 按维度查找数据事件的 Insights 事件
要按维度筛选，请键入以下命令。
```
aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName
--dimensions =
```
您只能为每个**list-insights-events**命令指定一个维度键值对。以下是 `DimensionKey` 的有效 Insights 事件值。值的名称区分大小写。
+ `EventId`
+ `EventName`
+ `EventSource`
`DimensionValue` 的最大长度为 2000 个字符。在 2000 个字符限制中，以下字符（“`_`”、“` `”、“`,`”、“`\\n`”）算作两个字符。
### 维度查询示例
以下示例命令返回 `EventName` 值为 `PutObject` 的 Insights 事件。
```
aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName --dimensions EventName=PutObject
```
以下示例命令返回 `EventId` 值为 `b5cc8c40-12ba-4d08-a8d9-2bceb9a3e002` 的 Insights 事件。
```
aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName --dimensions EventId=b5cc8c40-12ba-4d08-a8d9-2bceb9a3e002
```
以下示例命令返回 `EventSource` 值为 `s3.amazonaws.com` 的 Insights 事件。
```
aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName --dimensions EventSource=s3.amazonaws.com
```
## 为管理事件指定 Insights 事件的下一页结果
要从 `lookup-events` 命令获取下一页结果，请键入以下命令。
```
aws cloudtrail lookup-events --event-category insight --next-token=
```
在此命令中，的**值取自上一个命令输出的第一个字段。
在命令中使用 `--next-token` 时，您必须使用与上一个命令中相同的参数。例如，假设您运行以下命令。
```
aws cloudtrail lookup-events --event-category insight --lookup-attributes AttributeKey=EventName, AttributeValue=PutRule
```
要获取下一页结果，您的下一个命令将如下所示。
```
aws cloudtrail lookup-events --event-category insight --lookup-attributes AttributeKey=EventName,AttributeValue=PutRule --next-token=EXAMPLEZe++mErCebpy2TgaMgmDvF1kYGFcH64JSjIbZFjsuvrSqg66b5YGssKutDYIyII4lrP4IDbeQdiObkp9YAlju3oXd12juEXAMPLE=
```
## 为管理事件指定 Insights 事件的下一页结果
要从 `list-insights-data` 命令获取下一页结果，请键入以下命令。
```
aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName --next-token=
```
在此命令中，的**值取自上一个命令输出的第一个字段。
在命令中使用 `--next-token` 时，您必须使用与上一个命令中相同的参数。例如，假设您运行以下命令。
```
aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName --dimensions EventName=PutObject
```
要获取下一页结果，您的下一个命令将如下所示。
```
aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName --dimensions EventName=PutObject --next-token=EXAMPLEZe++mErCebpy2TgaMgmDvF1kYGFcH64JSjIbZFjsuvrSqg66b5YGssKutDYIyII4lrP4IDbeQdiObkp9YAlju3oXd12juEXAMPLE=
```
## 从文件中获取管理事件的 Insights 事件的 JSON 输入
Amazon CLI 对于某些 Amazon 服务，有两个参数，即`--generate-cli-skeleton`和`--cli-input-json`，可用于生成 JSON 模板，您可以修改该模板并将其用作`--cli-input-json`参数的输入。本部分介绍如何将这些参数和 `aws cloudtrail lookup-events` 结合使用。有关更多信息，请参阅 [Amazon CLI skeletons and input files](https://docs.amazonaws.cn/cli/latest/userguide/cli-usage-skeleton.html)。
**通过从文件中获取 JSON 输入来查找 Insights 事件**
1. 通过将 `lookup-events` 输出重定向到文件来创建与 `--generate-cli-skeleton` 结合使用的输入模板，如以下示例所示。
```
aws cloudtrail lookup-events --event-category insight --generate-cli-skeleton > LookupEvents.txt
```
生成的模板文件（在本例中为 LookupEvents .txt）如下所示。
```
{
"LookupAttributes": [
{
"AttributeKey": "",
"AttributeValue": ""
}
],
"StartTime": null,
"EndTime": null,
"MaxResults": 0,
"NextToken": ""
}
```
1. 可使用文本编辑器根据需要修改 JSON。JSON 输入只能包含指定的值。
**重要**
必须先从模板中删除所有空值，然后才能使用该模板。
以下示例指定一个时间范围和要返回的结果的最大数目。
```
{
"StartTime": "2023-11-01",
"EndTime": "2023-12-12",
"MaxResults": 10
}
```
1. 要使用编辑后的文件作为输入，请使用语法 `--cli-input-json file://`**，如下例所示。
```
aws cloudtrail lookup-events --event-category insight --cli-input-json file://LookupEvents.txt
```
**注意**
您可在 `--cli-input-json` 所在的命令行中使用其他参数。
## 从文件中获取数据事件的 Insights 事件的 JSON 输入
Amazon CLI 对于某些 Amazon 服务，有两个参数，即`--generate-cli-skeleton`和`--cli-input-json`，可用于生成 JSON 模板，您可以修改该模板并将其用作`--cli-input-json`参数的输入。本部分介绍如何将这些参数和 `aws cloudtrail list-insights-data` 结合使用。有关更多信息，请参阅 [Amazon CLI skeletons and input files](https://docs.amazonaws.cn/cli/latest/userguide/cli-usage-skeleton.html)。
**通过从文件中获取 JSON 输入来查找 Insights 事件**
1. 通过将 `list-insights-data` 输出重定向到文件来创建与 `--generate-cli-skeleton` 结合使用的输入模板，如以下示例所示。
```
aws cloudtrail list-insights-data --data-type InsightsEvents --generate-cli-skeleton > ListInsightsData.txt
```
生成的模板文件（在本例中为 ListInsightsData .txt）如下所示。
```
{
"InsightSource": "",
"DataType": "InsightsEvents",
"Dimensions":
{
"KeyName": ""
},
"StartTime": null,
"EndTime": null,
"MaxResults": 0,
"NextToken": ""
}
```
1. 可使用文本编辑器根据需要修改 JSON。JSON 输入只能包含指定的值。
**重要**
必须先从模板中删除所有空值，然后才能使用该模板。
以下示例指定一个时间范围和要返回的结果的最大数目。
```
{
"InsightSource": "arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName",
"DataType": "InsightsEvents",
"Dimensions":
{
"EventName": "PutObject"
},
"StartTime": "2025-11-01",
"EndTime": "2025-11-05",
"MaxResults": 1
}
```
1. 要使用编辑后的文件作为输入，请使用语法 `--cli-input-json file://`**，如下例所示。
```
aws cloudtrail list-insights-data --data-type InsightsEvents --cli-input-json file://ListInsightsData.txt
```
**注意**
您可在 `--cli-input-json` 所在的命令行中使用其他参数。
## 查找输出字段
**Events**
基于查找属性和已指定的时间范围的查找事件的列表。该事件列表按时间进行排序，最新的事件排在第一位。每个条目都包含有关查找请求的信息，并包含检索到 CloudTrail 的事件的字符串表示形式。
以下条目描述每个查找事件中的字段。
**CloudTrailEvent**
一个包含已返回事件的对象表示形式的 JSON 字符串。有关已返回的每个元素的信息，请参阅[记录正文内容](https://docs.amazonaws.cn/awscloudtrail/latest/userguide/cloudtrail-event-reference-record-contents.html)。
**EventId**
一个包含已返回事件的 GUID 的字符串。
**EventName**
一个包含已返回事件的名称的字符串。
**EventSource**
向其发出请求的 Amazon 服务。
**EventTime**
事件的日期和时间（采用 UNIX 时间格式）。
**资源**
由已返回的事件引用的资源列表。每个资源条目指定一个资源类型和一个资源名称。
**ResourceName**
一个包含由事件引用的资源名称的字符串。
**ResourceType**
一个包含由事件引用的资源类型的字符串。如果无法确定资源类型，则返回 null。
**用户名**
一个包含已返回事件的账户用户名称的字符串。
**NextToken**
用于从上一个 `lookup-events` 命令获取下一页结果的字符串。要使用该令牌，参数必须与原始命令中的参数相同。如果输出中未显示任何 `NextToken` 条目，则不再返回结果。
有关 CloudTrail Insights 事件的更多信息，请参阅本指南[使用见 CloudTrail 解](logging-insights-events-with-cloudtrail.md)中的。