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

# 保存并重新运行 Logs Insig CloudWatch hts 查询
<a name="CWL_Insights-Saving-Queries"></a>

创建查询后，可以将其保存，以便稍后再次运行查询。查询将以文件夹结构保存，因此您可以组织它们。每个账户每个区域可以保存多达 1000 个查询。

查询保存在特定区域级别，而不是特定用户级别。如果您创建并保存查询，则有权访问同一区域 CloudWatch 日志的其他用户可以在该区域中看到所有已保存的查询及其文件夹结构。

要保存查询，您必须登录到具有 `logs:PutQueryDefinition` 权限的角色。要查看已保存查询的列表，您必须登录到具有 `logs:DescribeQueryDefinitions` 权限的角色。

**注意**  
您可以使用参数创建和保存查询，这些参数是带有命名占位符的可重复使用的模板。与其保存具有不同值的同一个查询的多个变体，不如创建一个模板并在运行时提供不同的参数值。目前，仅使用 Logs Insights 查询语言的查询支持此功能。有关更多信息，请参阅[使用带参数的已保存查询](#CWL_Insights-Parameterized-Queries)。

------
#### [ Console ]

**保存查询**

1. 打开 CloudWatch 控制台，网址为[https://console.aws.amazon.com/cloudwatch/](https://console.amazonaws.cn/cloudwatch/)。

1. 在导航窗格中，选择 **Logs**（日志），然后选择 **Logs Insights**（日志洞察）。

1. 在查询编辑器中，创建查询。

1. 选择**保存**。

1. 输入查询的名称。

1. （可选）选择要保存查询的文件夹。选择 **Create new（新建）**以创建文件夹。如果创建新文件夹，则可以在文件夹名称中使用斜杠（/）字符来定义文件夹结构。例如，命名新文件夹 **folder-level-1/folder-level-2** 会创建一个名为 **folder-level-1** 的顶级文件夹，并在该文件夹中创建另一个名为 **folder-level-2** 的文件夹。查询保存在 **folder-level-2** 中。

1. （可选）更改查询的日志组或查询文本。

1. （可选）要在查询中使用参数，请执行以下额外步骤：

   1. **在查询中添加参数。**使用`{{parameter}}`语法（参数名称前后的双大括号）将静态值替换为占位符。

      示例：具有静态值的原始查询：

      ```
      fields @timestamp, @message
      | filter level = "Error"
      | filter applicationName = "OrderService"
      ```

      使用参数更新了查询：

      ```
      fields @timestamp, @message
      | filter level = {{logLevel}}
      | filter applicationName = {{applicationName}}
      ```

   1. **定义查询中使用的参数。**对于每个占位符参数，请指定：
      + **名称**：必须与占位符名称完全匹配（例如`logLevel`、`applicationName`）。
      + **默认值**（可选）：未提供参数值时使用的值。
      + **描述**（可选）：解释参数的用途。

   1. 通过使用带`$`前缀的查询名称并将参数名称作为键值对传递，可以运行带参数的查询。有关详细信息**，请参阅运行保存的查询**。

1. 选择**保存**。

------
#### [ Amazon CLI ]

**要保存查询，**请使用`put-query-definition`：

```
aws logs put-query-definition \
  --name "ErrorsByLevel" \
  --query-string "fields @timestamp, @message | filter level = \"ERROR\"" \
  --log-group-names "/aws/lambda/my-function" \
  --region us-east-1
```

（可选）要保存带参数的查询，请添加`--parameters`选项并在查询字符串中使用`{{parameterName}}`占位符：

```
aws logs put-query-definition \
  --name "ErrorsByLevel" \
  --query-string "fields @timestamp, @message | filter level = {{logLevel}} | filter applicationName = {{applicationName}}" \
  --parameters '[{"name":"logLevel","defaultValue":"ERROR","description":"Log level to filter"},{"name":"applicationName","defaultValue":"OrderService","description":"Application name to filter"}]' \
  --log-group-names "/aws/lambda/my-function" \
  --region us-east-1
```

要将查询保存在文件夹中，请在查询名称前加上文件夹路径：

```
aws logs put-query-definition \
  --name "my-folder/ErrorsByLevel" \
  --query-string "fields @timestamp, @message | filter level = {{logLevel}}" \
  --parameters '[{"name":"logLevel","defaultValue":"ERROR","description":"Log level to filter"}]' \
  --log-group-names "/aws/lambda/my-function" \
  --region us-east-1
```

------
#### [ API ]

**要保存查询，**请致电 [PutQueryDefinition](https://docs.amazonaws.cn/AmazonCloudWatchLogs/latest/APIReference/API_PutQueryDefinition.html)：

```
{
  "name": "ErrorsByLevel",
  "queryString": "fields @timestamp, @message | filter level = \"ERROR\"",
  "logGroupNames": ["/aws/lambda/my-function"]
}
```

（可选）要保存带参数的查询，请在查询字符串中包含该`parameters`字段并使用`{{parameterName}}`占位符：

```
{
  "name": "ErrorsByLevel",
  "queryString": "fields @timestamp, @message | filter level = {{logLevel}} | filter applicationName = {{applicationName}}",
  "logGroupNames": ["/aws/lambda/my-function"],
  "parameters": [
    {
      "name": "logLevel",
      "defaultValue": "ERROR",
      "description": "Log level to filter"
    },
    {
      "name": "applicationName",
      "defaultValue": "OrderService",
      "description": "Application name to filter"
    }
  ]
}
```

------

**提示**  
 您可以使用 `PutQueryDefinition` 为保存的查询创建文件夹。要为保存的查询创建文件夹，请使用正斜杠（/）在所需的查询名称前加上所需的文件夹名称：`<folder-name>/<query-name>`。有关此操作的更多信息，请参阅[PutQueryDefinition](https://docs.amazonaws.cn/AmazonCloudWatchLogs/latest/APIReference/API_PutQueryDefinition.html)。

------
#### [ Console ]

**运行保存的查询**

1. 打开 CloudWatch 控制台，网址为[https://console.aws.amazon.com/cloudwatch/](https://console.amazonaws.cn/cloudwatch/)。

1. 在导航窗格中，选择 **Logs**（日志），然后选择 **Logs Insights**（日志洞察）。

1. 在右侧，选择 **Queries（查询）**。

1. 从 “**已保存的查询” 列表中选择您的查询**。查询文本出现在查询编辑器中。

1. （可选）要使用带参数的查询，请执行以下操作：

   1. 在 “**已保存**的查询” 侧面板中，选择查询名称旁边的 **\$1** 图标。

   1. 带有参数的查询出现在查询编辑器中。例如，如果您选择旁边的 **\$1** 图标`ErrorsByLevel`，则查询编辑器中将填充以下内容：`$ErrorsByLevel(level=, applicationName=)`

   1. 提供参数（级别、应用程序名称）的值并运行查询。例如：`$ErrorsByLevel(level= "ERROR", applicationName= "OrderService")`

1. 选择**运行**。

------
#### [ Amazon CLI ]

**使用参数运行已保存的查询**

`start-query`使用以下`$QueryName()`语法：

```
aws logs start-query \
  --log-group-names "/aws/lambda/my-function" \
  --start-time 1707566400 --end-time 1707570000 \
  --query-string '$ErrorsByLevel(level= "ERROR", applicationName= "OrderService")' \
  --region us-east-1
```

------
#### [ API ]

**使用参数运行已保存的查询**

[StartQuery](https://docs.amazonaws.cn/AmazonCloudWatchLogs/latest/APIReference/API_StartQuery.html)使用`queryString`字段中的`$QueryName()`语法调用：

```
{
  "logGroupNames": ["/aws/lambda/my-function"],
  "startTime": 1707566400,
  "endTime": 1707570000,
  "queryString": "$ErrorsByLevel(level=\"ERROR\", applicationName= \"OrderService\")"
}
```

------

**保存已保存查询的新版本**

1. 打开 CloudWatch 控制台，网址为[https://console.aws.amazon.com/cloudwatch/](https://console.amazonaws.cn/cloudwatch/)。

1. 在导航窗格中，选择 **Logs**（日志），然后选择 **Logs Insights**（日志洞察）。

1. 在右侧，选择 **Queries（查询）**。

1. 从 **Saved queries（已保存的查询）**列表中选择您的查询。它显示在查询编辑器中。

1. 修改查询。如果您需要运行它来检查您的工作，请选择 **Run query（运行查询）**。

1. 准备好保存新版本后，选择 **Actions（操作）**、**Save as（另存为）**。

1. 输入查询的名称。

1. （可选）选择要保存查询的文件夹。选择 **Create new（新建）**以创建文件夹。如果创建新文件夹，则可以在文件夹名称中使用斜杠（/）字符来定义文件夹结构。例如，命名新文件夹 **folder-level-1/folder-level-2** 会创建一个名为 **folder-level-1** 的顶级文件夹，并在该文件夹中创建另一个名为 **folder-level-2** 的文件夹。查询保存在 **folder-level-2** 中。

1. （可选）更改查询的日志组或查询文本。

1. 选择**保存**。

要删除查询，您必须登录到具有 `logs:DeleteQueryDefinition` 权限的角色。

**编辑或删除已保存的查询**

1. 打开 CloudWatch 控制台，网址为[https://console.aws.amazon.com/cloudwatch/](https://console.amazonaws.cn/cloudwatch/)。

1. 在导航窗格中，选择 **Logs**（日志），然后选择 **Logs Insights**（日志洞察）。

1. 在右侧，选择 **Queries（查询）**。

1. 从 **Saved queries（已保存的查询）**列表中选择您的查询。它显示在查询编辑器中。

1. 选择 **Actions（操作）**、**Edit（编辑）**或 **Actions（操作）**、**Delete（删除）**。

## 使用带参数的已保存查询
<a name="CWL_Insights-Parameterized-Queries"></a>

带有参数的已保存查询是带有命名占位符的可重复使用的查询模板。您可以保存模板并在运行查询时提供不同的参数值，而不必维护几乎相同的查询的多个副本。只有 L CloudWatch ogs Insights 查询语言支持参数。

 **工作原理** 

保存查询时，占位符会标识您在执行查询时可以提供的值。占位符使用`{{parameterName}}`语法。以下是一个名为的已保存查询的示例，该查询名`ErrorsByLevel`为两个参数`logLevel`和`applicationName`。

```
fields @timestamp, @message
| filter level = {{logLevel}}
| filter applicationName = {{applicationName}}
```

要运行已保存的查询，您可以使用前缀为前缀的查询名称来调用该查询，`$`并传递参数值。 CloudWatch Logs Insights 查询引擎会替换每个占位符。如果参数包含默认值，则如果未提供其他值，则使用这些值。

```
# Run query by using query name and passing parameter values explicitly
$ErrorsByLevel(logLevel = "WARN", applicationName = "OrderService")

# Run query without specifying parameter values - default values are used in this case.
$ErrorsByLevel()
```

包含空格或特殊字符的已保存查询名称需要用反引号括起来：

```
$`Errors By Level`(logLevel = "WARN")
```

### 带参数的已保存查询示例
<a name="CWL_Insights-Parameterized-Queries-Examples"></a>

 **添加结果限制作为参数** 

查询名称：`ErrorsByLevel`带参数`logLevel`（默认：`"ERROR"`）、`applicationName`（默认：`"OrderService"`）和`maxResults`（默认：`50`）

```
fields @timestamp, @message, @logStream
| filter level = {{logLevel}}
| filter applicationName = {{applicationName}}
| sort @timestamp desc
| limit {{maxResults}}
```

```
# Run the query using the query name and passing parameter values
$ErrorsByLevel(logLevel = "WARN", applicationName = "OrderService", maxResults = 100)
```

 **使用多个已保存的带参数的查询** 

 下面的示例使用`ErrorsByLevel`了第二个保存的查询`RecentN`，该查询定义为`sort @timestamp desc | limit {{count}}`（带参数`count`，默认`20`）。 CloudWatch Logs Insights 查询引擎会在运行每个查询之前对其进行扩展。

```
# Using multiple queries with parameters in sequence
$ErrorsByLevel(logLevel = "WARN", applicationName = "OrderService")
| $RecentN(count = 10)

# Each of the queries is expanded, resulting in the following query when it is run.
fields @timestamp, @message
| filter level = "WARN"
| filter applicationName = "OrderService"
| sort @timestamp desc
| limit 10
```

### 配额和错误处理
<a name="CWL_Insights-Parameterized-Queries-Quotas"></a>

**注意**  
每个保存的查询最多可以有 20 个参数。

扩展后的查询字符串不能超过 10,000 个字符。参数名称必须以字母或下划线开头。已保存的查询不能引用其他已保存的查询（不支持嵌套调用）。


**常见错误**  

| 错误 | 原因 | 
| --- | --- | 
| 只有 CWLI 查询语言支持参数 | 只有 L CloudWatch ogs Insights 查询语言支持参数。 | 
| 在 QueryString 中找不到必需的参数 | 中的参数名称在查询字符串`{{placeholder}}`中`--parameters`没有匹配项。 | 
| 参数计数超过最大值 20 | 保存的查询目前仅支持 20 个参数。 | 
| 重复的参数名 | 查询定义中有重复的参数`parameters`。 | 

**注意**  
要使用参数创建或更新已保存的查询，您需要该`logs:PutQueryDefinition`权限。要运行一个，你需要`logs:StartQuery`和`logs:DescribeQueryDefinitions`。