翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# スケジュールされたクエリの概念を理解する
<a name="scheduled-queries-concepts"></a>

スケジュールされたクエリを作成する前に、クエリの実行方法と結果の配信先に影響するこれらの主要な概念を理解してください。

## IAM ロールの分離
<a name="scheduled-queries-iam-roles"></a>

スケジュールされたクエリには、クエリを実行するためのロールと、Amazon S3 または Amazon EventBridge イベントバスに結果を配信するためのロールの 2 つの異なる IAM ロールが必要です。この分離が存在する理由を理解することで、アクセス許可を正しく設定し、セキュリティと運用上の利点を活用できます。

2 ロールアーキテクチャは、データアクセスとデータ配信の責任を分けます。クエリ実行ロールはログデータにアクセスしてクエリを実行し、送信先配信ロールは選択した送信先に結果を書き込みます。この分離は最小特権の原則に従います。各ロールには、特定の関数に必要なアクセス許可のみがあります。

**クエリ実行ロール**  
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>

スケジュールされたクエリは特定のリージョンで作成され、そのリージョンで実行されます。ただし、ロググループをクエリし、リージョンとアカウント間で結果を配信できます。1 つ以上の 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)を使用して、複数のアカウントとリージョンのログデータを一元的なモニタリングアカウントにレプリケートします。これにより、すべての一元化されたログにアクセスするスケジュールされたクエリを 1 つのリージョンで作成できるため、リージョン間のクエリを回避し、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 時 UTC
+ `cron(0 18 ? * MON-FRI *)` - 平日の午後 6 時 UTC
+ `cron(0 0 1 * ? *)` - 毎月 1 日午前 0 時 UTC
+ `cron(0 12 ? * SUN *)` - 毎週日曜日の正午 UTC
+ `cron(30 8 1 1 ? *)` - 1 月 1 日午前 8:30 UTC

スケジュールされたクエリはすべて、ローカルのタイムゾーンや AWS リソースの場所に関係なく、UTC で実行されます。これは、営業時間や時間的制約のある分析のクエリをスケジュールするときに特に重要です。たとえば、米国東部標準時で事業を運営していて、東部標準時午前 9 時に日次レポートが必要な場合は、UTC オフセット (夏時間中は 14:00 UTC、それ以外の場合は 13:00 UTC) を考慮する必要があります。クエリが意図した時間に実行されるように、UTC を念頭に置いてスケジュール式を計画します。

## クエリ言語の選択
<a name="scheduled-queries-query-languages"></a>

スケジュールされたクエリは 3 つの異なるクエリ言語をサポートしており、クエリの作成方法とチームがクエリを簡単に維持できるかどうかの両方に影響します。適切な言語は、分析要件とチームの既存のスキルによって異なります。

主にログデータをフィルタリングおよび集約する場合、CloudWatch Logs Insights クエリ言語は最も単純な構文を提供します。複数のステップでデータを再形成または強化する必要がある複雑なデータ変換の場合、PPL のパイプラインアプローチにより、ロジックに従うのが容易になります。データベースオペレーションに似た結合や複雑な集計を実行する必要がある場合、SQL はデータベース経験豊富なチームがすばやく採用できる使い慣れた構文を提供します。

**CloudWatch Logs Insights クエリ言語 (CWLI)**  
直感的な構文を使用したログ分析専用です。以下に最適です。  
+ テキストベースのログ分析とフィルタリング
+ 時系列の集計と統計
+ ログ分析を初めて使用するチーム

**OpenSearch Service Piped Processing Language (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 日間保存する場合のみです。最適:  
+ クエリ結果への自動応答のトリガー
+ サーバーレスワークフローおよび Lambda 関数との統合
+ リアルタイムアラートおよび通知システム
+ イベント駆動型アーキテクチャとマイクロサービス

## クエリ結果の形式と構造
<a name="scheduled-queries-result-format"></a>

Amazon S3 送信先の場合 - クエリ結果はGetQueryResults API レスポンスと同じ構造で JSON 形式で配信されます。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` - クエリ実行ステータス (完了、失敗など)