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

# 建立排程查詢
<a name="create-scheduled-query"></a>

建立排程查詢，以自動執行 CloudWatch Logs Insights 查詢，並將結果交付至您選擇的目的地。

## 先決條件
<a name="create-scheduled-query-prerequisites"></a>

建立排程查詢之前，請確定您有下列項目：
+ **日誌群組** - 一或多個日誌群組，其中包含您要分析的資料
+ **執行 IAM 角色** - 具有下列許可的 IAM 角色：
  + `logs:StartQuery` - 啟動 CloudWatch Logs Insights 查詢的許可
  + `logs:GetQueryResults` - 擷取查詢結果的許可
  + `logs:DescribeLogGroups` - 存取日誌群組資訊的許可。這僅適用於日誌群組探索的字首型日誌群組
+ **目的地許可** - 所選目的地的其他 IAM 許可：
  + 對於 Amazon S3 目的地： `s3:PutObject`
+ **對於 AWS CLI 和 API 使用** - 具有呼叫 CloudWatch Logs APIs許可的已設定 AWS 登入資料

如需詳細的 IAM 政策範例，請參閱 [適用於 Amazon CloudWatch Logs 的 Identity and Access Management](auth-and-access-control-cwl.md)。另請注意，每個帳戶只能有 1000 個排程查詢。

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

**建立排程查詢 （主控台）**

1. 在 https：// 開啟 CloudWatch Logs 主控台？ [https://us-east-1.console.aws.amazon.com/cloudwatch/homeregion=us-east-1\#logsV2：logs-insights](https://us-east-1.console.aws.amazon.com/cloudwatch/home?region=us-east-1#logsV2:logs-insights)。

1. 在導覽窗格中，選擇 **Logs Insights**。

1. 選擇**建立排程查詢**。

1. 在**查詢定義**區段中：

   1. 針對**查詢語言**，從清單中選擇要使用的查詢語言。

   1. 針對**查詢字串**，在方塊中輸入您的 CloudWatch Logs Insights 查詢。

   1. 對於**日誌群組**，從清單中選擇要查詢的日誌群組。

1. 在**排程設定**區段中：

   1. 對於**排程表達**式，請在查詢執行時設定 。從預先定義的選項中選擇或輸入自訂 Cron 表達式。

   1. 對於**建立時生效**，請指定排程何時變成作用中。選擇立即開始，或使用 YYYY/MM/DD 格式在特定日期和時間開始。

   1. 針對**時間範圍**，指定每個查詢執行的回顧期間。以分鐘為單位輸入持續時間，以定義從執行時間開始查詢的時間。

   1. 對於**無限期繼續**，請指定排程何時結束。選擇無限期執行，或使用 YYYY/MM/DD 格式直到特定日期和時間。

1. 主控台會根據您的組態顯示接下來三個排程的查詢執行，以 UTC 顯示執行查詢的確切日期和時間。

1. 在將**查詢結果發佈至 S3 - 選用**區段中 （如果使用 S3 目的地）：

   1. 對於 **S3 儲存貯**體，如果目的地儲存貯體位於相同 AWS 帳戶，請選取**此帳戶**；如果儲存貯體位於不同 AWS 帳戶，請選取**另一個帳戶**，並提供儲存貯體擁有帳戶的帳戶 ID 做為輸入。

   1. 對於 **Amazon S3 URI**，輸入將存放結果的 Amazon S3 儲存貯體和字首 （例如 `s3://my-bucket/query-results/`)。如果您選取**此帳戶**，您可以選擇**瀏覽 Amazon S3** 以導覽並選取現有的 Amazon S3 位置。

   1. （選用） 對於 **KMS 金鑰 ARN**，輸入客戶受管 AWS KMS 金鑰的 ARN，以使用 SSE-KMS 加密查詢結果。金鑰必須與目的地 Amazon S3 儲存貯體位於相同的 AWS 區域。

1. 在**用於將查詢結果發佈至 Amazon S3 的 IAM 角色**區段中，選擇下列其中一個選項：

   1. 選擇**自動建立具有預設許可的新角色**，以自動設定具有 CloudWatch Logs 將查詢結果交付至 Amazon S3 所需許可的 IAM 角色。

   1. 選擇**使用現有角色**來選取具有所需政策的現有 IAM 角色，以便 CloudWatch Logs 將查詢結果交付至 Amazon S3。使用搜尋欄位，從清單中選擇適當的 IAM 角色。

1. 在**排程查詢執行的 IAM 角色**區段中，選擇下列其中一個選項：

   1. 選擇**自動建立具有預設許可的新角色**，以自動設定具有 CloudWatch Logs 執行排程查詢所需許可的 IAM 角色。

   1. 選擇**使用現有角色**來選取具有所需政策的現有 IAM 角色，以便 CloudWatch Logs 執行排程查詢。使用搜尋欄位，從清單中選擇適當的 IAM 角色。

1. 選擇**建立排程**以建立排程查詢。

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

**建立排程查詢 (AWS CLI)**
+ 使用 `create-scheduled-query`命令建立新的排程查詢：

  ```
  aws logs create-scheduled-query \
      --name "ErrorAnalysisQuery" \
      --query-language "CWLI" \
      --query-string "fields @timestamp, @message | filter @message like /ERROR/ | stats count() by bin(5m)" \
      --schedule-expression "cron(8 * * * ? *)" \
      --execution-role-arn "arn:aws:iam::123456789012:role/CloudWatchLogsScheduledQueryRole" \
      --log-group-identifiers "/aws/lambda/my-function" "/aws/apigateway/my-api" \
      --state "ENABLED"
  ```

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

**建立排程查詢 (API)**
+ 使用 `CreateScheduledQuery`動作建立新的排程查詢。下列範例會建立排程查詢，每小時執行一次：

  ```
  {
      "name": "ErrorAnalysisQuery",
      "queryLanguage": "CWLI",
      "queryString": "fields @timestamp, @message | filter @message like /ERROR/ | stats count() by bin(5m)",
      "scheduleExpression": "cron(8 * * * ? *)",
      "executionRoleArn": "arn:aws:iam::123456789012:role/CloudWatchLogsScheduledQueryRole",
      "logGroupIdentifiers": ["/aws/lambda/my-function", "/aws/apigateway/my-api"],
      "state": "ENABLED"
  }
  ```

------

建立排程查詢後，您可以從**排程查詢**頁面並使用 ListScheduledQueries API 來檢視和管理它，該 API 會顯示所有排程查詢及其名稱、建立日期、上次執行狀態、上次觸發時間和重複頻率。