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

您可以将 Amazon Athena 与 Amazon EventBridge 结合使用来接收有关查询状态的实时通知。当您提交的查询转换了状态时，Athena 将事件发布到 EventBridge，其中包含有关该查询状态转换的信息。您可以针对感兴趣的事件编写简单规则，并在事件匹配规则时执行自动化操作。例如，您可以创建在查询到达终端状态时调用 AWS Lambda 函数的规则。尽最大努力发出事件。

在为 Athena 创建事件规则之前，您应该先执行以下操作：
+ 熟悉 EventBridge 中的事件、规则和目标。有关更多信息，请参阅[什么是 Amazon EventBridge？](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html) 有关如何设置规则的更多信息，请参阅 [Getting started with 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 查询状态更改事件。`athenaError` 数据块仅当 `currentState` 为 `FAILED` 时才会出现。有关 `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 输出包括以下属性。


****  

| 属性 | 说明 | 
| --- | --- | 
| 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 事件的服务主体授予 `events.amazonaws.com` 权限以发布到您的 Amazon SNS 主题，如下例所示。

   ```
   {
       "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 开发者版](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)。**