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

# 使用 執行和管理 CloudTrail Lake 查詢 AWS CLI
<a name="lake-queries-cli"></a>

您可以使用 AWS CLI 來執行和管理 CloudTrail Lake 查詢。使用 時 AWS CLI，請記住，您的命令會在為設定檔 AWS 區域 設定的 中執行。如果您想在不同區域中執行命令，則可變更設定檔的預設區域，或搭配 **--region** 參數使用命令。

## CloudTrail Lake 查詢的可用命令
<a name="lake-queries-cli-commands"></a>

在 CloudTrail Lake 中執行和管理查詢的命令包括：
+ `start-query` 執行查詢。
+ `describe-query` 傳回有關查詢的中繼資料。
+ `generate-query` 從英文提示產生查詢。如需詳細資訊，請參閱[從自然語言提示建立 CloudTrail Lake 查詢](lake-query-generator.md)。
+ `get-query-results` 傳回指定查詢 ID 的查詢結果。
+ `list-queries` 以取得指定事件資料存放區的清單查詢。
+ `cancel-query` 取消執行中的查詢。

如需 CloudTrail Lake 事件資料存放區的可用命令清單，請參閱 [事件資料存放區的可用命令](lake-eds-cli.md#lake-eds-cli-commands)。

如需 CloudTrail Lake 儀表板的可用命令清單，請參閱 [儀表板的可用命令](lake-dashboard-cli.md#lake-dashboard-cli-commands)。

如需 CloudTrail Lake 整合的可用命令清單，請參閱 [CloudTrail Lake 整合的可用命令](lake-integrations-cli.md#lake-integrations-cli-commands)。

## 使用 從自然語言提示產生查詢 AWS CLI
<a name="lake-cli-generate-query"></a>

執行 `generate-query`命令，從英文提示產生查詢。針對 `--event-data-stores`，提供您要查詢的事件資料存放區的 ARN （或 ARN 的 ID 尾碼）。您只能指定一個事件資料存放區。對於 `--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
<a name="lake-cli-start-query"></a>

下列範例 AWS CLI **start-query**命令會在 查詢陳述式中指定為 ID 的事件資料存放區上執行查詢，並將查詢結果傳送到指定的 S3 儲存貯體。`--query-statement` 參數提供用單引號括住的 SQL 查詢。選用參數包括 `--delivery-s3-uri`，用於將查詢結果傳送到指定的 S3 儲存貯體。如需可在 CloudTrail Lake 中使用之查詢語言的詳細資訊，請參閱 [CloudTrail Lake SQL 限制條件](query-limitations.md)。

```
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"
}
```

**注意**  
執行時間超過一小時的查詢可能會逾時。您仍然可以取得在查詢逾時之前處理的部分結果。  
如果您使用選用的 `--delivery-s3-uri` 參數將查詢結果傳送到 S3 儲存貯體，則儲存貯體政策必須授予 CloudTrail 許可，才能將查詢結果傳送到儲存貯體。如需手動編輯儲存貯體政策的資訊，請參閱「[適用於 CloudTrail Lake 查詢結果的 Amazon S3 儲存貯體政策](s3-bucket-policy-lake-query-results.md)」。

## 使用 取得查詢的中繼資料 AWS CLI
<a name="lake-cli-describe-query"></a>

下列範例 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
<a name="lake-cli-get-query-results"></a>

下列範例 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
<a name="lake-cli-list-queries"></a>

下列範例 AWS CLI **list-queries** 命令會傳回過去七天內指定事件資料存放區上的查詢和查詢狀態清單。您必須對於 `--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
<a name="lake-cli-cancel-query"></a>

下列範例 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)
```