将触发器事件发送到 AWS EventBridge
MongoDB提供AWS Eventbridge 合作事件源,允许您将Atlastrigger 事件发送到事件总线,而不是调用Atlas Function 。您可以配置任何trigger类型以将事件发送到 EventBridge。 数据库触发器还支持自定义错误处理,以减少由于非严重错误而导致的trigger暂停。
将trigger事件发送到 EventBridge 只需要一个Amazon Web Services帐户ID即可。 本指南引导您查找帐户ID 、配置trigger 、将trigger事件源与事件总线关联以及设置自定义错误处理。
步骤
注意
EventBridge trigger事件的单个条目必须小于 256 KB。
在性能优化部分了解如何减小
PutEvents
条目的大小。
设置 MongoDB 合作伙伴事件源
如需向 AWS EventBridge 发送触发事件,您需要应接收事件的帐号的 AWS account ID。
打开 Amazon EventBridge 控制台 Partner event sources然后单击导航菜单中的 。
搜索MongoDB合作事件源,然后单击Set up 。
在 MongoDB合作事件源页面中,单击 Copy 将您的Amazon Web Services帐户ID复制到剪贴板。
配置触发器
获得 AWS account ID 后,您可以配置数据库trigger或定时trigger以将事件发送到 EventBridge。
您可以在trigger Atlas用户界面中或使用 配置App Services CLI 。
在Atlas用户界面中,使用以下设置创建并配置新的数据库trigger或定时trigger :
选择EventBridge作为事件类型。
粘贴从 EventBridge 复制的AWS Account ID 。
选择要向其发送trigger事件的 AWS Region。
(可选,仅适用于数据库触发器)配置函数以处理trigger错误。
有关详细信息,请参阅本页的“自定义错误处理”部分。
点击放大要启用扩展JSON,请切换Advanced (Optional)部分中的Enable Extended JSON设置。
默认情况下,触发器将事件对象中的 BSON 类型转换为标准 JSON 类型。
启用扩展JSON会通过将事件对象序列化为扩展JSON格式来保留BSON类型信息。 这保留了类型信息,但牺牲了可读性和互操作性。
对 MongoDB Atlas 用户进行身份验证
使用MongoDB Atlas Administration API密钥登录App Services CLI:
appservices login --api-key="<API KEY>" --private-api-key="<PRIVATE KEY>" 提取应用程序的最新配置文件
运行以下命令以获取配置文件的本地副本:
appservices pull --remote=<App ID> 默认,该命令会将文件提取到当前工作目录中。 您可以使用可选的
--local
标志指定目录路径。在本地
/triggers
目录中创建trigger配置文件。 省略function_name
字段并定义AWS_EVENTBRIDGE
事件处理器。将
account_id
字段设置为您从 EventBridge 复制的AWS Account ID 。将
region
字段设置为Amazon Web Services区域。要启用扩展 JSON,请将
extended_json_enabled
字段设置为true
。默认情况下,触发器将事件对象中的 BSON 类型转换为标准 JSON 类型。
启用扩展JSON会通过将事件对象序列化为扩展JSON格式来保留BSON类型信息。 这保留了类型信息,但牺牲了可读性和互操作性。
(可选,仅适用于数据库触发器)配置函数以处理trigger错误。
有关详细信息,请参阅本页的“自定义错误处理”部分。
trigger配置文件应类似于以下内容:
{ "name": "...", "type": "...", "event_processors": { "AWS_EVENTBRIDGE": { "config": { "account_id": "<AWS Account ID>", "region": "<AWS Region>", "extended_json_enabled": <boolean> } } } }
将触发器事件源与事件总线关联
返回 EventBridge 控制台。
在导航窗格中选择合作伙伴事件源。
在 Partner event sources 表中,找到并选择 Pending trigger源,然后单击 Associate with event bus。
在Associate with event bus屏幕上,定义其他帐户和组织所需的访问权限权限,然后单击Associate 。
确认关联后, trigger事件源的状态从 Pending 更改为 Active,事件总线的名称也会更新以匹配事件源名称。 现在,您可以创建规则,以trigger来自该合作事件源的事件。
有关更多信息,请参阅创建在 SaaS 合作伙伴事件中触发的规则。
自定义错误处理
注意
只有数据库触发器支持自定义错误处理程序
目前,只有数据库触发器支持自定义错误处理。 身份验证触发器和定时触发器目前不支持自定义错误处理。
您可以创建一个错误处理程序,以便在重试不成功时、 trigger失败时执行。 自定义错误处理允许您确定来自AWS Eventbridge的错误是否严重到需要暂停trigger ,或者是否可以忽略错误并继续处理其他事件。
有关暂停的数据库触发器的更多信息,请参阅暂停的触发器。
创建新的自定义错误处理程序
您可以使用App Services CLI或通过App Services Admin API在Atlas用户界面中创建新的错误处理程序。
此过程将引导您了解如何直接在Create a Trigger页面中创建新函数。
您也可以从Functions页面创建函数。 有关如何在Atlas中定义函数的更多信息,请参阅定义函数。
您可以使用trigger 更新带有错误处理程序的App Services CLI 配置。有关更多信息,请参阅更新应用程序。
对 MongoDB Atlas 用户进行身份验证
使用MongoDB Atlas Administration API密钥登录App Services CLI:
appservices login --api-key="<API KEY>" --private-api-key="<PRIVATE KEY>"
编写错误处理程序
按照定义函数中的步骤写入错误处理程序源代码和配置文件。
请参阅以下模板错误处理程序示例:
exports = async function(error, changeEvent) { // This sample function will log additional details if the error is not // a DOCUMENT_TOO_LARGE error if (error.code === 'DOCUMENT_TOO_LARGE') { console.log('Document too large error'); // Comment out the line below in order to skip this event and not suspend the Trigger throw new Error('Encountered error: ${error.code}'); } console.log('Error sending event to EventBridge'); console.log('DB: ${changeEvent.ns.db}'); console.log('Collection: ${changeEvent.ns.coll}'); console.log('Operation type: ${changeEvent.operationType}'); // Throw an error in your Function to suspend the Trigger // and stop processing additional events throw new Error('Encountered error: ${error.message}'); };
有关创建函数的更多信息,请参阅函数。
将错误处理程序添加到trigger配置中
将 error_handler
属性添加到 Triggers
文件夹中的trigger配置文件中。
trigger配置文件应类似于以下内容:
{ "name": "...", "type": "DATABASE", "event_processors": { "AWS_EVENTBRIDGE": { "config": { "account_id": "<AWS Account ID>", "region": "<AWS Region>", "extended_json_enabled": <boolean> } } }, "error_handler": { "config": { "enabled": <boolean>, "function_name": "<Error Handler Function Name>" } } }
有关详细信息,请参阅trigger配置文件。
部署更改
运行以下命令以部署更改:
appservices push
注意
此过程适用于App Services Admin API端点。 它不使用Atlas Administration API端点。
对 MongoDB Atlas 用户进行身份验证
使用 MongoDB Atlas Administration API密钥对 调用 登录 端点:
curl -X POST \ https://services.cloud.mongodb.com/api/admin/v3.0/auth/providers/mongodb-cloud/login \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -d '{ "username": "<Public API Key>", "apiKey": "<Private API Key>" }'
如果身份验证成功,响应正文将包含一个具有access_token
值的JSON对象:
{ "access_token": "<access_token>", "refresh_token": "<refresh_token>", "user_id": "<user_id>", "device_id": "<device_id>" }
access_token
授予对App Services Admin API的访问权限。 您必须将其作为持有者令牌包含在所有App Services Admin API请求的Authorization
标头中。
创建部署草稿(可选)
草稿表示一群组应用程序更改,您可以将其作为一个单元进行部署或丢弃。 如果不创建草稿,则会自动单独部署更新。
要创建草稿,请将不带正文的 POST
请求发送到创建部署草稿端点:
curl -X POST 'https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/drafts' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer <access_token>'
创建错误处理程序函数
通过向“AWS Eventbridgetrigger POST
创建新函数”端点发出 请求,创建函数以处理失败的 的错误。
curl -X POST \ https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/functions \ -H 'Authorization: Bearer <access_token>' \ -d '{ "name": "string", "private": true, "source": "string", "run_as_system": true }'
创建 AWS EventBridge 触发器
通过向“创建触发器”端点发出
POST
请求,创建已启用错误处理功能的 AWS EventBridge 触发器。
curl -X POST \ https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/triggers \ -H 'Authorization: Bearer <access_token>' \ -d '{ "name": "string", "type": "DATABASE", "config": { "service_id": "string", "database": "string", "collection": "string", "operation_types": { "string" }, "match": , "full_document": false, "full_document_before_change": false, "unordered": true }, "event_processors": { "AWS_EVENTBRIDGE": { "account_id": "string", "region": "string", "extended_json_enabled": false }, }, "error_handler": { "enabled": true, "function_id": "string" } }'
部署更改
如果您创建了草稿,则可以通过向部署草稿端点发送不带正文的
POST
请求来部署草稿中的所有更改。
如果第一步没有创建草稿,则会自动部署单个函数和trigger请求。
curl -X POST \ 'https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/drafts/{draftId}/deployment' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <access_token>' \
错误处理程序参数
默认错误处理程序有两个参数:error
和 changeEvent
。
error
具有以下两个属性:
code
:出错的 EventBridge put请求的代码。 有关错误处理程序使用的错误代码列表,请参阅本页上的“错误代码”部分。message
: 来自错误的 EventBridge put 请求的未过滤错误消息。
changeEvent
EventBridge 对您的数据所做的请求更改。 有关变更事件类型及其配置的更多信息,请参阅变更事件类型。
错误代码
如果从 EventBridge 收到错误,事件处理器会将错误解析为DOCUMENT_TOO_LARGE
或OTHER
。 已解析的错误通过error
参数传递给错误处理函数。
DOCUMENT_TOO_LARGE
如果 EventBridge trigger事件的条目大于 256 KB,则 EventBridge 将引发错误。 该错误将包含以下任一内容:
有关减小条目大小的更多信息,请参阅性能优化。
OTHER
所有其他错误的默认存储桶。
提示
优化其他代码错误的错误处理
您可以为最常见的错误消息制定特殊的错误处理案例,以优化使用OTHER
代码的错误处理。 为了确定哪些错误需要特殊情况,我们建议追踪您在error.message
中收到的最常见错误消息。
错误处理程序日志
您可以在应用程序日志中查看 EventBridge 触发器错误处理程序的触发器错误处理程序日志。
从Atlas 用户界面的Triggers
页面中,选择Logs标签页。
默认显示所有日志。 要仅查看错误处理程序日志,请单击Show errors only切换开关。
将trigger_error_handler
值传递给--type
标志以查看所有错误处理程序日志。
appservices logs list --type=trigger_error_handler
注意
此过程适用于App Services Admin API端点。 它不使用Atlas Administration API端点。
通过向检索App Services日志端点发出
GET
请求来检索TRIGGER_ERROR_HANDLER
类型日志:
curl -X GET 'https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/logs' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer <access_token>' -d '{ "type": "TRIGGER_ERROR_HANDLER" }'
要学习;了解有关查看应用程序日志的更多信息,请参阅查看应用程序日志。
示例事件
以下对象配置trigger以将事件发送到AWS Eventbridge并处理错误:
"event_processors": { "AWS_EVENTBRIDGE": { "config": { "account_id": "012345678901", "region": "us-east-1" } } }, "error_handler": { "config": { "enabled": true, "function_name": "myErrorHandler.js" } }
性能优化
EventBridge trigger事件的单个条目必须小于 256 KB。
有关Amazon Web Services 计算Amazon PutEvents事件条目大小的更多信息,请参阅 文档 。使用数据库触发器时,项目表达式可以仅包含指定字段,从而在将消息发送到 EventBridge 之前减小文档大小。 有关项目表达式的更多详细信息,请参阅数据库trigger项目表达式文档。