本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 儲存並重新執行 CloudWatch Logs Insights 查詢
<a name="CWL_Insights-Saving-Queries"></a>

建立查詢之後，可以儲存該查詢，以便之後再次執行。查詢會儲存在資料夾結構中，因此您可以組織它們。每個區域和每個帳戶最多可儲存 1000 個查詢。

查詢會儲存在區域特定層級，而非使用者特定層級。如果您建立並儲存查詢，在同一區域中具有 CloudWatch Logs 存取權的其他使用者可以查看該區域中所有已儲存的查詢及其資料夾結構。

若要儲存查詢，您必須登入具有許可 `logs:PutQueryDefinition` 的角色。若要查看已儲存查詢的清單，您必須登入具有許可 `logs:DescribeQueryDefinitions` 的角色。

**注意**  
您可以使用 參數建立和儲存查詢 — 具有具名預留位置的可重複使用範本。與其使用不同的值儲存相同查詢的多個變化，請建立一個範本，並在執行時提供不同的參數值。此功能目前僅支援使用 Logs Insights 查詢語言的查詢。如需詳細資訊，請參閱[搭配參數使用已儲存的查詢](#CWL_Insights-Parameterized-Queries)。

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

**儲存查詢**

1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 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. 選擇**儲存**。

------
#### [ AWS 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.aws.amazon.com/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.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutQueryDefinition.html)。

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

**執行已儲存的查詢**

1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。

1. 在導覽窗格中，選擇 **Logs** (日誌)，然後選擇 **Logs Insights** (日誌洞察)。

1. 選擇右側的 **Queries (查詢)**。

1. 從**已儲存的查詢清單中選取您的查詢**。查詢文字會出現在查詢編輯器中。

1. （選用） 若要搭配參數使用查詢：

   1. 在**已儲存查詢**側邊面板中選擇查詢名稱旁的 **\+** 圖示。

   1. 具有參數的查詢會出現在查詢編輯器中。例如，如果您選擇 旁的 **\+** 圖示`ErrorsByLevel`，查詢編輯器會填入： `$ErrorsByLevel(level=, applicationName=)`

   1. 提供參數 (level、applicationName) 的值並執行查詢。例如：`$ErrorsByLevel(level= "ERROR", applicationName= "OrderService")`

1. 選擇**執行**。

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

**使用參數執行已儲存的查詢**

使用 `$QueryName()` `start-query`搭配 語法：

```
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 ]

**使用參數執行已儲存的查詢**

使用 `queryString` 欄位中的`$QueryName()`語法呼叫 [StartQuery](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_StartQuery.html)：

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

------

**儲存新版本的已儲存查詢**

1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 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. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。

1. 在導覽窗格中，選擇 **Logs** (日誌)，然後選擇 **Logs Insights** (日誌洞察)。

1. 選擇右側的 **Queries (查詢)**。

1. 從 **Saved queries (已儲存的查詢)** 清單中選取查詢。它會出現在查詢編輯器中。

1. 選擇 **Actions (動作)**、**Edit (編輯)** 或 **Actions (動作)**、**Delete (刪除)**。

## 搭配參數使用已儲存的查詢
<a name="CWL_Insights-Parameterized-Queries"></a>

具有參數的已儲存查詢是具有具名預留位置的可重複使用查詢範本。您可以儲存範本並在執行查詢時提供不同的參數值，而不是維護幾乎相同的查詢的多個副本。只有 CloudWatch Logs 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 查詢語言才支援參數 | 只有 CloudWatch Logs Insights 查詢語言才支援參數。 | 
| queryString 中找不到必要的參數 | 中的參數名稱在查詢字串`{{placeholder}}`中`--parameters`沒有相符項目。 | 
| 參數計數超過上限 20 | 儲存的查詢目前僅支援 20 個參數。 | 
| 重複的參數名稱 | 查詢定義在 中有重複的參數`parameters`。 | 

**注意**  
若要使用參數建立或更新儲存的查詢，您需要 `logs:PutQueryDefinition`許可。若要執行一個，您需要 `logs:StartQuery`和 `logs:DescribeQueryDefinitions`。