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

# 了解排程查詢概念
<a name="scheduled-queries-concepts"></a>

在建立排程查詢之前，請了解這些會影響查詢執行方式和結果交付位置的關鍵概念。

## IAM 角色分離
<a name="scheduled-queries-iam-roles"></a>

排程查詢需要兩個不同的 IAM 角色：一個用於執行查詢，另一個用於將結果交付至 Amazon S3 或 Amazon EventBridge 事件匯流排。了解此分隔存在的原因可協助您正確設定許可，並使用其提供的安全性和操作優勢。

雙角色架構會劃分資料存取和資料交付之間的責任。查詢執行角色會存取您的日誌資料並執行查詢，而目的地交付角色會將結果寫入您選擇的目的地。此區隔遵循最低權限原則 - 每個角色只有其特定函數所需的許可。

**查詢執行角色**  
允許 CloudWatch Logs 代表您執行 CloudWatch Logs Insights 查詢。此角色需要存取日誌群組和執行查詢的許可，但不需要存取目的地資源。必要許可：  
+ `logs:StartQuery`
+ `logs:StopQuery`
+ `logs:GetQueryResults`
+ `logs:DescribeLogGroups`
+ `logs:Unmask` 如果需要取消遮罩資料
**對於 KMS 加密的日誌群組：**用於加密日誌群組的 KMS 金鑰的 `kms:Decrypt`和 `kms:DescribeKey`許可。也需要新增這些許可。  
**信任關係要求：**查詢執行角色必須包含允許 CloudWatch Logs 服務 (`logs.amazonaws.com`) 擔任角色的信任政策。如果沒有此信任關係，排程的查詢將會失敗並出現許可錯誤。  
查詢執行角色的信任政策範例：  

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "logs.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}
```
查詢執行角色的許可政策範例：  

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "logs:StartQuery",
                "logs:StopQuery",
                "logs:GetQueryResults",
                "logs:DescribeLogGroups"
            ],
            "Resource": "*"
        }
    ]
}
```

**目的地交付角色**  
允許 CloudWatch Logs 將查詢結果交付至您選擇的目的地。根據最低權限原則，此角色只需要特定目的地服務的許可。必要許可因目的地類型而異。  
**信任關係需求：**目的地交付角色也必須包含信任政策，允許 CloudWatch Logs 服務 (`logs.amazonaws.com`) 擔任該角色。  
S3 目的地交付角色的許可政策範例：  

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject"
            ],
            "Resource": "arn:aws:s3:::your-scheduled-query-results-bucket/*"
        }
    ]
}
```

此區隔為您的操作提供實際的好處。從安全角度來看，如果您需要變更交付結果的位置，您只需修改目的地交付角色，而不變更查詢執行許可。為了合規和稽核，您可以清楚地追蹤哪些角色存取敏感日誌資料，以及哪些角色寫入外部系統。這可讓您更輕鬆地示範日誌分析基礎設施遵循安全最佳實務。

## 跨區域和跨帳戶用量
<a name="scheduled-queries-cross-account"></a>

排程查詢會在特定區域中建立，並在該區域中執行。不過，您可以查詢日誌群組，並跨區域和帳戶交付結果。您需要將一或多個 AWS 帳戶設定為*監控帳戶*，並將其連結至多個*來源帳戶*。監控帳戶是中央 AWS 帳戶，可檢視來源帳戶產生的可觀測性資料並與之互動。來源帳戶是個別 AWS 帳戶，可產生其中資源的可觀測性資料。來源帳戶會與監控帳戶共用其可觀察性資料。因此，您可以使用所有連結帳戶的日誌群組，從監控帳戶設定排程查詢。

**查詢跨區域日誌群組**  
您的排程查詢可以存取任何區域中的日誌群組。使用完整的 ARN 格式指定日誌群組：`arn:aws:logs:region:account-id:log-group:log-group-name`。查詢執行角色需要`logs:StartQuery`和所有目標區域中日誌群組的`logs:GetQueryResults`許可。

**重要**  
查詢日誌群組或跨區域交付結果時，日誌資料會跨越區域界限。考慮下列各項：  
**資料駐留要求** - 確保跨區域資料傳輸符合組織的資料控管政策和法規要求
**資料傳輸成本** - 跨區域資料傳輸會產生額外費用
**網路延遲** - 在遙遠區域中存取日誌群組的查詢可能會遇到較高的延遲
為了獲得最佳效能和成本效益，請在與主要日誌群組相同的區域中建立排程查詢。

**替代方法：**使用 [CloudWatch Logs 集中，](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatchLogs_Centralization.html)將多個帳戶和區域的日誌資料複寫至中央監控帳戶。這可讓您在存取所有集中式日誌的單一區域中建立排程查詢，避免跨區域查詢並簡化 IAM 許可管理。

## 排程表達式和時區處理
<a name="scheduled-queries-schedule-expressions"></a>

您定義的排程會決定查詢執行的時間及其執行頻率。選擇正確的排程表達式會影響您何時收到結果，以及您查詢的資料量。了解表達式類型可協助您在簡單性和精確度之間進行選擇。

Cron 表達式提供對計時的精確控制，可讓您指定確切的時間、星期幾或月份天數。當您需要在特定上班時間執行查詢或符合操作排程時，請使用 cron 表達式。在 主控台中，您也可以使用簡單的行事曆選項來排程查詢。

**Cron 表達式**  
在特定時間執行查詢。格式：`cron(minute hour day-of-month month day-of-week year)`。範例：  
+ `cron(0 9 * * ? *)` - 每日上午 9：00 UTC
+ `cron(0 18 ? * MON-FRI *)` - 工作日 UTC 下午 6：00
+ `cron(0 0 1 * ? *)` - 每月第一天午夜 UTC
+ `cron(0 12 ? * SUN *)` - 每週日中午 UTC
+ `cron(30 8 1 1 ? *)` - 1 月 1 日上午 8：30 UTC

所有排程查詢都會在 UTC 中執行，無論您的本機時區或 AWS 資源所在的位置為何。當您排定工作時間或時間敏感分析的查詢時，這尤其重要。例如，如果您的業務在美國東部時間營運，而且您想要在東部時間上午 9 點進行每日報告，您需要考慮 UTC 偏移 （夏令時間 14：00 UTC，否則為 13：00 UTC)。以 UTC 為考量來規劃排程表達式，以確保查詢在預期時間執行。

## 選擇查詢語言
<a name="scheduled-queries-query-languages"></a>

排程查詢支援三種不同的查詢語言，而且您的選擇會影響您撰寫查詢的方式，以及您的團隊可以輕鬆維護查詢的方式。正確的語言取決於您的分析需求和您團隊的現有技能。

如果您主要是篩選和彙總日誌資料，CloudWatch Logs Insights 查詢語言提供最直接的語法。對於您需要透過多個步驟重塑或豐富資料的複雜資料轉換，PL 的管道方法可讓您更輕鬆地遵循邏輯。當您需要執行與資料庫操作類似的聯結或複雜彙總時，SQL 會提供熟悉的語法，讓資料庫經驗豐富的團隊可以快速採用。

**CloudWatch Logs Insights 查詢語言 (CWLI)**  
專為使用直覺式語法進行日誌分析而打造。最適合：  
+ 文字型日誌分析和篩選
+ 時間序列彙總和統計資料
+ 記錄分析的新團隊

**OpenSearch Service 管道處理語言 (PPL)**  
具有強大資料轉換功能的管道型查詢語言。最適合：  
+ 複雜的資料轉換和擴充
+ 多步驟資料處理工作流程
+ 熟悉管道型處理的團隊

**OpenSearch Service 結構化查詢語言 (SQL)**  
熟悉資料庫樣式查詢的標準 SQL 語法。最適合：  
+ 複雜聯結和彙總
+ 商業智慧和報告
+ 具有強大 SQL 體驗的團隊

## 目的地選擇和使用案例
<a name="scheduled-queries-destinations"></a>

您傳送查詢結果的位置會決定您可以如何處理它們。無論您要建置長期分析、觸發自動回應或兩者，此選項都會塑造您的整個下游工作流程。了解每個目的地類型的強項，可協助您為使用案例設計正確的架構。

Amazon S3 目的地已針對儲存和批次處理進行最佳化。當您需要將查詢結果保留數月或數年、分析一段時間的趨勢，或將資料饋送至分析平台時，Amazon S3 會提供具有無限制保留的符合成本效益的儲存體。EventBridge 目的地已針對即時自動化進行最佳化。當查詢結果應觸發立即動作時，例如傳送提醒、啟動工作流程或更新系統時，EventBridge 會以您的應用程式可立即回應的事件的形式提供結果。根據預設，所有查詢完成事件都會自動做為事件傳送至預設事件匯流排，以便與下游處理系統、Lambda 函數或其他事件驅動型架構整合。結果只會在成功執行查詢時發佈到目的地。

**Amazon S3 目的地**  
將查詢結果儲存為 JSON 檔案，以進行長期保留和批次處理。最適合：  
+ 歷史分析和資料封存
+ 與資料湖和分析平台整合
+ 合規和稽核要求
+ 經濟實惠的大型結果集儲存

**EventBridge 目的地**  
將查詢結果做為事件傳送，以進行即時處理和自動化。您只能使用事件中傳送的 queryId 擷取查詢結果，最多 30 天，因為我們將結果存放 30 天。最適合：  
+ 觸發自動回應以查詢結果
+ 與無伺服器工作流程和 Lambda 函數整合
+ 即時提醒和通知系統
+ 事件驅動型架構和微服務

## 查詢結果格式和結構
<a name="scheduled-queries-result-format"></a>

對於 Amazon S3 目的地 - 查詢結果會以 JSON 格式交付，其結構與 GetQueryResults API 回應相同。為了讓 Amazon EventBridge 了解排程查詢結果的格式，可協助您設計下游處理和整合工作流程。

查詢結果會以 JSON 格式交付，結構如下：

```
{
    "version": "0",
    "id": "be72061b-eca2-e068-a7e1-83e01d6fe807",
    "detail-type": "Scheduled Query Completed",
    "source": "aws.logs",
    "account": "123456789012",
    "time": "2025-11-18T11:31:48Z",
    "region": "us-east-1",
    "resources": [
        "arn:aws:logs:us-east-1:123456789012:scheduled-query:477b4380-b098-474e-9c5e-e10a8cc2e6e7"
    ],
    "detail": {
        "queryId": "2038fd57-ab4f-4018-bb2f-61d363f4a004",
        "queryString": "fields @timestamp, @message, @logStream, @log\n| sort @timestamp desc\n| limit 10000",
        "logGroupIdentifiers": [
            "/aws/lambda/my-function"
        ],
        "status": "Complete",
        "startTime": 1763465460,
        "statistics": {
            "recordsMatched": 0,
            "recordsScanned": 0,
            "estimatedRecordsSkipped": 0,
            "bytesScanned": 0,
            "estimatedBytesSkipped": 0,
            "logGroupsScanned": 1
        }
    }
}
```

關鍵元素包括：
+ `statistics` - 查詢效能指標，包括相符、掃描、處理位元組和估計略過資料的記錄
+ `startTime` - 查詢執行開始的時間 (Unix 時間戳記）
+ `queryString` - 實際執行的查詢
+ `queryId` - 查詢的查詢 ID，可使用其擷取結果
+ `logGroupIdentifiers` - 查詢的日誌群組清單
+ `status` - 查詢執行狀態 （完成、失敗等）