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

# 使用 EventBridge 監控 Athena 查詢事件
<a name="athena-events"></a>

您可以搭配使用 Amazon EventBridge 與 Amazon Athena，以接收有關查詢狀態的即時通知。當您提交的查詢轉換狀態時，Athena 會將事件發布至 EventBridge，當中包含該查詢狀態轉換的相關資訊。您可以針對感興趣的事件撰寫簡單的規則，並在事件符合規則時採取自動化動作。例如，您可以建立規則，在查詢達到終端狀態時叫用 AWS Lambda 函數。盡可能發出事件。

在您為 Athena 建立事件規則之前，請執行下列動作：
+ 熟悉 Eventbridge 中的事件、規則和目標。如需詳細資訊，請參閱[什麼是 Amazon EventBridge？](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html) 如需有關如何設定規則的詳細資訊，請參閱 [Amazon EventBridge 入門](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-get-started.html)。
+ 建立要在事件規則中使用的一或多個目標。

**注意**  
Athena 目前提供一種事件類型 (Athena 查詢狀態變更)，但可能會新增其他事件類型和詳細資訊。如果您是透過程式設計方式將事件 JSON 資料還原序列化，請確定您的應用程式在新增這些額外屬性時已準備好處理不明屬性。

## Athena 事件格式
<a name="athena-events-pattern"></a>

以下是 Amazon Athena 事件的基本模式。

```
{
    "source":[
        "aws.athena"
    ],
    "detail-type":[
        "Athena Query State Change"
    ],
    "detail":{
        "currentState":[
            "SUCCEEDED"
        ]
    }
}
```

## Athena 查詢狀態變更事件
<a name="athena-events-athena-query-state-change"></a>

下列範例會顯示 `currentState` 值為 `SUCCEEDED` 的 Athena 狀態變更事件。

```
{
    "version":"0",
    "id":"abcdef00-1234-5678-9abc-def012345678",
    "detail-type":"Athena Query State Change",
    "source":"aws.athena",
    "account":"123456789012",
    "time":"2019-10-06T09:30:10Z",
    "region":"us-east-1",
    "resources":[

    ],
    "detail":{
        "versionId":"0",
        "currentState":"SUCCEEDED",
        "previousState":"RUNNING",
        "statementType":"DDL",
        "queryExecutionId":"01234567-0123-0123-0123-012345678901",
        "workgroupName":"primary",
        "sequenceNumber":"3"
    }
}
```

下列範例會顯示 `currentState` 值為 `FAILED` 的 Athena 狀態變更事件。只有在 `currentState` 為 `FAILED` 時，才會顯示 `athenaError` 區塊。如需有關 `errorCategory` 和 `errorType` 值的詳細資訊，請參閱 [Athena 錯誤目錄](error-reference.md)。

```
{
    "version":"0",
    "id":"abcdef00-1234-5678-9abc-def012345678",
    "detail-type":"Athena Query State Change",
    "source":"aws.athena",
    "account":"123456789012",
    "time":"2019-10-06T09:30:10Z",
    "region":"us-east-1",
    "resources":[ 
    ],
    "detail":{
        "athenaError": {
            "errorCategory": 2.0, //Value depends on nature of exception
            "errorType": 1306.0, //Type depends on nature of exception
            "errorMessage": "Amazon S3 bucket not found", //Message depends on nature of exception
            "retryable":false //Retryable value depends on nature of exception
        },
        "versionId":"0",
        "currentState": "FAILED",
        "previousState": "RUNNING",
        "statementType":"DML",
        "queryExecutionId":"01234567-0123-0123-0123-012345678901",
        "workgroupName":"primary",
        "sequenceNumber":"3"
    }
}
```

### 輸出屬性
<a name="athena-events-query-state-change-output-properties"></a>

JSON 輸出包含以下屬性。


****  

| 屬性 | Description | 
| --- | --- | 
| athenaError | 只有在 currentState 為 FAILED 時才會顯示。包含發生之錯誤的相關資訊，包括錯誤類別、錯誤類型、錯誤訊息，以及是否可以重試導致錯誤的動作。每個欄位的值視錯誤性質而定。如需有關 errorCategory 和 errorType 值的詳細資訊，請參閱 [Athena 錯誤目錄](error-reference.md)。 | 
| versionId | 詳細資訊物件之結構描述的版本號碼。 | 
| currentState | 在事件發生時查詢所轉換成的狀態。 | 
| previousState | 在事件發生時查詢從其轉換的狀態。 | 
| statementType | 執行的查詢陳述式類型。 | 
| queryExecutionId | 查詢執行的唯一識別碼。 | 
| workgroupName | 執行查詢的工作群組名稱。 | 
| sequenceNumber | 單調遞增的數字，允許刪除重複和排序涉及所執行單一查詢的傳入事件。當針對相同的狀態轉換發布重複事件時，sequenceNumber 值是相同的。當查詢經歷一次以上的狀態轉換時 (例如遇到鮮少列入佇列的查詢)，您可以使用 sequenceNumber 來排序 currentState 和 previousState 值相同的事件。 | 

## 範例
<a name="athena-events-examples"></a>

下列範例會將事件發布至您已訂閱的 Amazon SNS 主題。查詢 Athena 時，您會收到一封電子郵件。該範例假設 Amazon SNS 主題存在且您已訂閱該主題。

**若要將 Athena 事件發布至 Amazon SNS 主題**

1. 建立 Amazon SNS 主題的目標。授予 EventBridge 事件服務主體發布至 Amazon SNS 主題的 `events.amazonaws.com` 許可，如下列範例所示。

   ```
   {
       "Effect":"Allow",
       "Principal":{
           "Service":"events.amazonaws.com"
       },
       "Action":"sns:Publish",
       "Resource":"arn:aws:sns:us-east-1:111111111111:your-sns-topic"
   }
   ```

1. 使用 AWS CLI `events put-rule`命令來建立 Athena 事件的規則，如下列範例所示。

   ```
   aws events put-rule --name {ruleName} --event-pattern '{"source": ["aws.athena"]}'
   ```

1. 使用 AWS CLI `events put-targets`命令將 Amazon SNS 主題目標連接至規則，如下列範例所示。

   ```
   aws events put-targets --rule {ruleName} --targets Id=1,Arn=arn:aws:sns:us-east-1:111111111111:your-sns-topic
   ```

1. 查詢 Athena 並觀察被叫用的目標。您應該會收到來自該 Amazon SNS 主題的相應電子郵件。

## AWS 使用者通知 搭配 Amazon Athena 使用
<a name="monitoring-user-notifications"></a>

您可使用 [AWS 使用者通知](https://docs.aws.amazon.com/notifications/latest/userguide/what-is.html) 來設定交付管道，以取得有關 Amazon Athena 事件的通知。當事件符合您指定的規則時，便會收到通知。您可以透過多個管道接收事件通知，包括電子郵件、[聊天應用程式中的 Amazon Q Developer](https://docs.aws.amazon.com/chatbot/latest/adminguide/what-is.html) 聊天通知或 [AWS Console Mobile Application](https://docs.aws.amazon.com/consolemobileapp/latest/userguide/what-is-consolemobileapp.html) 推送通知。您也可以在[主控台通知中心](https://console.aws.amazon.com/notifications/)查看通知。 使用者通知 支援彙總，這可以減少您在特定事件期間收到的通知數量。

如需詳細資訊，請參閱[「*AWS 使用者通知 使用者指南」*](https://docs.aws.amazon.com/notifications/latest/userguide/what-is.html)。