本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 排程查詢入門
建立排程查詢時，您將設定數個關鍵元件，以定義查詢的執行方式以及交付結果的位置。了解這些元件可協助您設定有效的自動化日誌分析。
每個排程查詢都包含下列關鍵元件：
**查詢組態**
用於分析的 CloudWatch Logs Insights 查詢字串、目標日誌群組和查詢語言。
**排程表達式**
定義查詢執行時間的 Cron 表達式或頻率行事曆。您可以指定時區設定，以確保查詢在正確的本機時間執行。主控台會顯示排程的人類可讀描述，例如「在每個星期二的 15：10 執行查詢，時間範圍為 5 分鐘，立即在 UTC 上生效，直到無限期為止。」
**時間範圍**
每個查詢執行的回顧期間，由與執行時間偏移的開始時間所定義。這會決定每個查詢執行將分析多少歷史資料。
**執行排程預覽**
主控台會顯示接下來的三個排程查詢執行，其中包含確切的日期和時間 （例如 2025/10/28 15：10、UTC；2025/11/04 15：10、UTC；2025/11/11 15：10、UTC)，可協助您確認排程已正確設定。
**目的地**
查詢結果在成功執行後交付的位置。支援的目的地包括 Amazon S3 儲存貯體，預設會將結果中繼資料傳送至預設事件匯流排。
**執行角色**
CloudWatch Logs 擔任的 IAM 角色，可執行查詢並將結果交付至指定的目的地。
建立排程查詢之前，請確定您已設定必要的許可和資源。
# 建立排程查詢
建立排程查詢，以自動執行 CloudWatch Logs Insights 查詢，並將結果交付至您選擇的目的地。
## 先決條件
建立排程查詢之前，請確定您有下列項目：
+ **日誌群組** - 一或多個日誌群組，其中包含您要分析的資料
+ **執行 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\$1logsV2：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 會顯示所有排程查詢及其名稱、建立日期、上次執行狀態、上次觸發時間和重複頻率。
# 檢視和管理排程查詢
下列資訊適用於每個查詢：
**名稱**
您指派給排程查詢的唯一名稱。選取名稱以檢視詳細的組態和執行歷史記錄。
**Creation (建立) 日期**
建立排程查詢的日期，以 YYYY-MM-DD 格式顯示。
**上次執行的狀態**
最近查詢執行的執行狀態。可能的值包括：
+ **完成** - 已成功執行查詢，並將結果交付至所有設定的目的地。
+ **失敗** - 查詢執行或結果交付失敗。檢查執行歷史記錄以取得錯誤詳細資訊。
+ **無效查詢** - 查詢無效且具有語法問題
+ **逾時** - 查詢已逾時。查詢會在 60 分鐘後自動逾時
**上次觸發時間**
上次執行查詢的日期和時間，以 YYYY-MM-DD HH：MM：SS 格式顯示。如果查詢尚未執行，則會顯示**永不**。
**重複每個**
查詢的排程頻率。針對使用 Cron 表達式的查詢或更簡單排程的特定頻率描述，顯示**自訂**。
**排程查詢**頁面提供所有排程查詢的概觀，顯示其目前狀態和執行歷史記錄，以便您可以從集中位置檢視、監控和管理所有排程查詢。使用此資訊來監控查詢效能、識別問題，以及管理您的自動化日誌分析工作流程。
------
#### [ Console ]
**檢視排定的查詢 （主控台）**
1. 在 https：// 開啟 CloudWatch Logs 主控台？ [https://us-east-1.console.aws.amazon.com/cloudwatch/homeregion=us-east-1\$1logsV2：logs-insights](https://us-east-1.console.aws.amazon.com/cloudwatch/home?region=us-east-1#logsV2:logs-insights)。
1. 在 CloudWatch Logs 主控台中，選擇**排程查詢**、**檢視排程查詢**。
------
#### [ AWS CLI ]
**列出排程查詢 (AWS CLI)**
+ 使用 `list-scheduled-queries`命令列出所有排定的查詢：
```
aws logs list-scheduled-queries --max-results 10
```
------
#### [ API ]
**列出排程查詢 (API)**
+ 使用 `ListScheduledQueries`動作來擷取所有排定的查詢：
```
{
"maxResults": 10
}
```
------
**已排程查詢**頁面標頭會顯示您帳戶中已排程查詢的總數，協助您追蹤用量並有效管理自動化日誌分析工作流程。
# 檢視排定的查詢執行歷史記錄
使用執行歷史記錄來監控排程查詢的效能，並針對查詢執行或結果交付的任何問題進行疑難排解。
執行歷史記錄會顯示每個查詢執行的狀態，包括成功執行、失敗和目的地處理結果。您可以使用此資訊來識別模式、診斷問題，並確認查詢是否如預期般執行。
------
#### [ Console ]
**檢視執行歷史記錄 （主控台）**
1. 在 CloudWatch Logs 主控台中，選擇**排程查詢**、**檢視排程查詢**。
1. 選取您要檢查的排程查詢。
1. 選擇 **Execution history (執行歷程記錄)** 標記。
------
#### [ AWS CLI ]
**檢視執行歷史記錄 (AWS CLI)**
1. 使用 `get-scheduled-query-history`命令來擷取排程查詢的執行歷史記錄：
```
aws logs get-scheduled-query-history \
--identifier "DailyErrorMonitoring" \
--start-time 1743379200 \
--end-time 1743465600 \
--max-results 10
```
1. 若要依執行狀態篩選，請新增 `--execution-statuses` 參數：
```
aws logs get-scheduled-query-history \
--identifier "DailyErrorMonitoring" \
--start-time 1743379200 \
--end-time 1743465600 \
--max-results 1 \
--execution-statuses "SUCCEEDED"
```
------
#### [ API ]
**檢視執行歷史記錄 (API)**
+ 使用 `GetScheduledQueryHistory`動作來擷取執行歷史記錄：
```
{
"identifier": "DailyErrorMonitoring",
"startTime": 1743379200,
"endTime": 1743465600,
"maxResults": 10,
"executionStatuses": ["SUCCEEDED", "FAILED"]
}
```
------
執行歷史記錄會顯示：
+ **執行狀態** - 執行中、完成、失敗、逾時或 InvalidQuery
+ **觸發時間** - 執行查詢的時間
+ **目的地** - 每個已設定目的地的處理狀態，包括 S3 和 EventBridge
+ **錯誤訊息** - 有關查詢執行或目的地處理中任何失敗的詳細資訊
# 更新排程查詢
修改您的排程查詢組態，以隨著需求的變化變更查詢字串、排程、目的地或執行角色。
您可以更新排程查詢的任何方面，包括查詢字串、排程表達式、目的地和執行角色。對於未來的執行，變更會立即生效。
------
#### [ Console ]
**更新排程查詢 （主控台）**
1. 在 CloudWatch Logs 主控台中，選擇**排程查詢**、**檢視排程查詢**。
1. 選取您要更新的排程查詢。
1. 選擇**編輯**。
1. 視需要修改組態。
1. 選擇**儲存變更**。
------
#### [ AWS CLI ]
**更新排程查詢 (AWS CLI)**
+ 使用 `update-scheduled-query`命令來修改現有的排程查詢：
```
aws logs update-scheduled-query \
--identifier "arn:aws:logs:us-east-1:111122223333:scheduled-query:5e0c0228-1c29-4d26-904f-59f1f1ba3c8f" \
--description "Monitor for ERROR level logs daily" \
--query-language "LogsQL" \
--query-string "fields @timestamp, @message | filter @message like /ERROR/" \
--log-group-identifiers "/aws/lambda/my-function-1" "/aws/lambda/my-function-2"
```
------
#### [ API ]
**更新排程查詢 (API)**
1. 使用 `UpdateScheduledQuery`動作來修改排程查詢組態：
```
{
"identifier": "arn:aws:logs:us-east-1:111122223333:scheduled-query:5e0c0228-1c29-4d26-904f-59f1f1ba3c8f",
"queryString": "fields @timestamp, @message | filter @message like /WARNING|ERROR/ | stats count() by bin(5m)",
"scheduleExpression": "cron(0 */2 * * ? *)",
"state": "ENABLED"
}
```
1. 若要一次更新多個組態參數：
```
{
"identifier": "arn:aws:logs:us-east-1:111122223333:scheduled-query:5e0c0228-1c29-4d26-904f-59f1f1ba3c8f",
"queryString": "fields @timestamp, @message, @level | filter @level = 'ERROR'",
"scheduleExpression": "cron(0 8,12,16 * * ? *)",
"executionRoleArn": "arn:aws:iam::111122223333:role/UpdatedScheduledQueryRole",
"logGroupIdentifiers": ["/aws/lambda/my-function", "/aws/lambda/another-function"],
"destinationConfiguration": {
"s3Configuration": {
"destinationIdentifier": "s3://111122223333-sqn-results-bucket/processed-results",
"roleArn": "arn:aws:iam::111122223333:role/Admin"
}
}
}
```
------