AWS CLI を使用して CloudTrail Lake クエリを実行および管理する

AWS CLI を使用して、CloudTrail Lake クエリを実行および管理することができます。AWS CLI を使用するときは、コマンドは自分のプロファイル用に設定された AWS リージョンで実行されることを忘れないようにしてください。別のリージョンでコマンドを実行する場合は、プロファイルのデフォルトのリージョンを変更するか、コマンドに --region パラメータを使用します。

CloudTrail Lake クエリで使用できるコマンド

CloudTrail Lake でクエリを実行および管理するためのコマンドは次のとおりです。

CloudTrail Lake イベントデータストアで使用できるコマンドのリストについては、「イベントデータストアで使用できるコマンド」を参照してください。

CloudTrail Lake ダッシュボードで使用できるコマンドのリストについては、「ダッシュボードで使用できるコマンド」を参照してください。

CloudTrail Lake 統合で使用できるコマンドのリストについては、「CloudTrail Lake 統合で使用できるコマンド」を参照してください。

AWS CLI を使用して自然言語プロンプトからクエリを生成する

generate-query コマンドを実行して、英語のプロンプトからクエリを生成します。--event-data-stores には、クエリを行うイベントデータストア ARN (または ARN の ID サフィックス) を指定します。指定できるイベントデータストアは 1 つだけです。--prompt の場合、プロンプトを英語で指定します。

aws cloudtrail generate-query 
--event-data-stores arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/EXAMPLE-ee54-4813-92d5-999aeEXAMPLE \
--prompt "Show me all console login events for the past week?"

成功すると、コマンドは SQL ステートメントを出力し、イベントデータストアに対してクエリを実行するために start-query コマンドで使用する QueryAlias を提供します。

{
  "QueryStatement": "SELECT * FROM $EDS_ID WHERE eventname = 'ConsoleLogin' AND eventtime >= timestamp '2024-09-16 00:00:00' AND eventtime <= timestamp '2024-09-23 00:00:00' AND eventSource = 'signin.amazonaws.com'",
  "QueryAlias": "AWSCloudTrail-UUID"
}

AWS CLI でクエリを開始する

次のサンプル AWS CLI start-query コマンドは、クエリステートメントで ID として指定されたイベントデータストアに対してクエリを実行し、指定された S3 バケットにクエリ結果を配信します。--query-statement パラメータは、一重引用符で囲まれた SQL クエリを提供します。オプションのパラメータには、指定された S3 バケットにクエリ結果を配信するための --delivery-s3-uri が含まれます。CloudTrail Lake で使用できるクエリ言語の詳細については、「CloudTrail Lake SQL の制約」を参照してください。

aws cloudtrail start-query
--query-statement 'SELECT eventID, eventTime FROM EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE LIMIT 10'
--delivery-s3-uri "s3://aws-cloudtrail-lake-query-results-123456789012-us-east-1"

レスポンスは QueryId 文字列です。クエリのステータスを取得するには、start-query によって返された QueryId 値を使用して describe-query を実行します。クエリが成功した場合は、get-query-results を実行して結果を取得できます。

出力

{
    "QueryId": "EXAMPLE2-0add-4207-8135-2d8a4EXAMPLE"
}

AWS CLI でクエリに関するメタデータを取得する

次の例にある AWS CLI describe-query コマンドは、ミリ秒単位のクエリ実行時間、スキャン済みの一致したイベント数、スキャン済み合計バイト数、クエリのステータスなど、クエリに関するメタデータを取得します。BytesScanned 値は、クエリが実行中でない限り、ユーザーのアカウントがクエリに対して請求されるバイト数と一致します。クエリ結果が S3 バケットに配信された場合、応答では S3 URI と配信ステータスも提供されます。

--query-id または --query-alias パラメータのいずれかの値を指定する必要があります。--query-alias パラメータを指定すると、エイリアスに対して最後に実行されたクエリに関する情報が返されます。

aws cloudtrail describe-query --query-id EXAMPLEd-17a7-47c3-a9a1-eccf7EXAMPLE

以下に、応答の例を示します。

{
    "QueryId": "EXAMPLE2-0add-4207-8135-2d8a4EXAMPLE", 
    "QueryString": "SELECT eventID, eventTime FROM EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE LIMIT 10", 
    "QueryStatus": "RUNNING",
    "QueryStatistics": {
        "EventsMatched": 10,
        "EventsScanned": 1000,
        "BytesScanned": 35059,
        "ExecutionTimeInMillis": 3821,
        "CreationTime": "1598911142"
    }
}

AWS CLI でクエリ結果を取得する

次のサンプル AWS CLI get-query-results コマンドは、クエリのイベントデータ結果を取得します。start-query コマンドによって返される --query-id 値を指定します。BytesScanned 値は、クエリが実行中でない限り、ユーザーのアカウントがクエリに対して請求されるバイト数と一致します。オプションのパラメータには、コマンドが単一のページに返す結果の最大数を指定する --max-query-results が含まれます。指定した --max-query-results 値よりも多くの結果がある場合は、返された NextToken 値を追加してコマンドを再度実行し、結果の次のページを取得します。

aws cloudtrail get-query-results
--query-id EXAMPLEd-17a7-47c3-a9a1-eccf7EXAMPLE

出力:

{
    "QueryStatus": "RUNNING",
    "QueryStatistics": {
        "ResultsCount": 244,
        "TotalResultsCount": 1582,
        "BytesScanned":27044
    },
    "QueryResults": [
      {
        "key": "eventName",
        "value": "StartQuery",
      }
   ],
    "QueryId": "EXAMPLE2-0add-4207-8135-2d8a4EXAMPLE", 
    "QueryString": "SELECT eventID, eventTime FROM EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE LIMIT 10",
    "NextToken": "20add42078135EXAMPLE"
}

AWS CLI でイベントデータストアに対するすべてのクエリを一覧表示する

次のサンプル AWS CLI list-queries コマンドは、指定されたイベントデータストアについて、過去 7 日間のクエリとクエリステータスのリストを返します。--event-data-store には、ARN、または ARN 値の ID サフィックスを指定する必要があります。オプションで、結果のリストを短くするために、--start-time と --end-time パラメータ、および --query-status 値を追加することで、タイムスタンプとしてフォーマットされた時間範囲を指定できます。QueryStatus に有効な値には、QUEUED、RUNNING、FINISHED、FAILED、または CANCELLED が含まれます。

list-queries には、オプションのページ分割パラメータもあります。--max-results を使用して、コマンドが単一のページに返す結果の最大数を指定します。指定した --max-results 値よりも多くの結果がある場合は、返された NextToken 値を追加してコマンドを再度実行し、結果の次のページを取得します。

aws cloudtrail list-queries
--event-data-store EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE
--query-status CANCELLED
--start-time 1598384589
--end-time 1598384602
--max-results 10

出力:

{
    "Queries": [
        {
          "QueryId": "EXAMPLE2-0add-4207-8135-2d8a4EXAMPLE", 
          "QueryStatus": "CANCELLED",
          "CreationTime": 1598911142
        },
        {
          "QueryId": "EXAMPLE2-4e89-9230-2127-5dr3aEXAMPLE", 
          "QueryStatus": "CANCELLED",
          "CreationTime": 1598296624
        }
     ],
    "NextToken": "20add42078135EXAMPLE"
}

AWS CLI で実行中のクエリをキャンセルする

次のサンプル AWS CLI cancel-query コマンドは、ステータスが RUNNING のクエリをキャンセルします。--query-id に値を指定する必要があります。cancel-query を実行すると、cancel-query 操作がまだ終了していない場合でも、クエリのステータスに CANCELLED が表示されることがあります。

以下は CLI の例です。

aws cloudtrail cancel-query
--query-id EXAMPLEd-17a7-47c3-a9a1-eccf7EXAMPLE

出力:

QueryId -> (string)
QueryStatus -> (string)