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

# 了解计划查询的概念
<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:Decrypt`以及用于加密日志组的 KMS 密钥的`kms:DescribeKey`权限。还需要添加这些权限。  
**信任关系要求：**查询执行角色必须包含允许 CloudWatch 日志服务 (`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.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>

计划查询是在特定区域创建的，并在该区域运行。但是，您可以跨地区和账户查询日志组并交付结果。您需要将一个或多个 Amazon 账户设置为*监控账户*，并将它们与多个*源账户关*联。监控账户是一个中央账户，可以查看源 Amazon 账户生成的可观测性数据并与之交互。源账户是一个个人 Amazon 账户，用于为其中的资源生成可观测性数据。源账户与监控账户共享其可观测性数据。因此，您可以使用所有关联账户的日志组从监控账户设置计划查询。

**查询跨区域日志组**  
您的计划查询可以访问任何区域的日志组。使用日志组的完整 ARN 格式指定日志组：。`arn:aws:logs:region:account-id:log-group:log-group-name`所有目标区域中日志组的查询执行角色`logs:StartQuery`和`logs:GetQueryResults`权限。

**重要**  
在跨区域查询日志组或传送结果时，日志数据会跨越区域边界。请考虑以下事项：  
**数据驻留要求**-确保跨区域数据传输符合贵组织的数据治理政策和监管要求
**数据传输成本**-跨区域数据传输会产生额外费用
**网络延迟**-访问遥远区域日志组的查询可能会遇到更高的延迟
为了获得最佳性能和成本效益，请在与主日志组相同的区域中创建定时查询。

**替代方法：**使用[CloudWatch 日志集中化](https://docs.amazonaws.cn/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
+ `cron(0 18 ? * MON-FRI *)`-世界标准时间工作日下午 6:00
+ `cron(0 0 1 * ? *)`-每个月的第一天午夜（UTC）
+ `cron(0 12 ? * SUN *)`-世界标准时间每周日中午
+ `cron(30 8 1 1 ? *)`-世界标准时间 1 月 1 日上午 8:30

无论您的本地时区或 Amazon 资源位于何处，所有定时查询都以 UTC 运行。当您为工作时间或时间敏感型分析安排查询时，这一点尤其重要。例如，如果您的企业按美国东部时间运营，并且您想要在美国东部时间上午 9 点发布每日报告，则需要考虑世界标准时间偏移量（夏令时为 14:00 UTC，否则为 13:00 UTC）。在计划日程表达式时要考虑到 UTC，以确保查询在预期的时间运行。

## 选择查询语言
<a name="scheduled-queries-query-languages"></a>

计划查询支持三种不同的查询语言，您的选择会影响您编写查询的方式以及团队维护查询的难易程度。正确的语言取决于您的分析要求和团队的现有技能。

如果您主要筛选和聚合日志数据， CloudWatch 那么 Logs Insights 查询语言提供了最直接的语法。对于需要通过多个步骤重塑或丰富数据的复杂数据转换，PPL的管道方法使逻辑更易于理解。当你需要执行类似于数据库操作的联接或复杂聚合时，SQL 提供了熟悉的语法，有数据库经验的团队可以快速采用这些语法。

**CloudWatch 日志见解查询语言 (CWLI)**  
专为日志分析而设计，语法直观。最适合：  
+ 基于文本的日志分析和筛选
+ 时间序列聚合和统计数据
+ 刚接触日志分析的队伍

**OpenSearch 服务管道处理语言 (PPL)**  
基于管道的查询语言，具有强大的数据转换功能。最适合：  
+ 复杂的数据转换和扩充
+ 多步骤数据处理工作流程
+ 熟悉基于管道的处理的团队

**OpenSearch 服务结构化查询语言 (SQL)**  
用于熟悉的数据库式查询的标准 SQL 语法。最适合：  
+ 复杂的联接和聚合
+ 商业智能和报告
+ 具有强大 SQL 经验的团队

## 目的地选择和用例
<a name="scheduled-queries-destinations"></a>

将查询结果发送到何处决定了您可以如何处理这些结果。无论您是在构建长期分析、触发自动响应，还是两者兼而有之，这种选择都会影响您的整个下游工作流程。了解每种目的地类型的优势有助于您为自己的用例设计合适的架构。

Amazon S3 目标已针对存储和批处理进行了优化。当您需要将查询结果保存数月或数年、分析一段时间内的趋势或将数据输入分析平台时，Amazon S3 可提供具有成本效益且保留期不受限制的存储。 EventBridge 目的地已针对实时自动化进行了优化。当查询结果应触发即时操作（例如发送警报、启动工作流程或更新系统）时，将结果作为事件EventBridge 传递，您的应用程序可以立即响应这些事件。默认情况下，所有查询完成事件都会作为事件自动发送到默认事件总线，从而实现与下游处理系统、Lambda 函数或其他事件驱动架构的集成。只有成功执行查询后，才会将结果发布到目的地。

**Amazon S3 目标**  
将查询结果存储为 JSON 文件，以便长期保留和批处理。最适合：  
+ 历史分析和数据存档
+ 与数据湖和分析平台集成
+ 合规和审计要求
+ 经济高效地存储大型结果集

**EventBridge 目的地**  
将查询结果作为事件发送，以便进行实时处理和自动化。由于我们将结果存储 30 天，因此您只能使用事件中发送的 queryID 检索查询结果，最长只能在 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`-查询执行状态（完成、失败等）