将触发器事件发送到 AWS EventBridge
概述
MongoDB 提供 AWS Eventbridge 合作伙伴事件源,允许您将 Atlas Trigger 事件发送到事件总线,而不是调用 Atlas Function。您可以配置任何触发器类型以将事件发送到 EventBridge。数据库触发器还支持自定义错误处理,以减少由于非严重错误而导致的触发器暂停。
将trigger事件发送到 EventBridge 只需要一个 Amazon Web Services 帐户 ID。本指南将逐步介绍如何查找帐户 ID、配置触发器、将触发器事件源与事件总线关联以及设置自定义错误处理。
步骤
注意
EventBridge 触发事件的 AWS put 条目必须小于 256 KB。
在性能优化部分了解如何减小 PutEvents 条目的大小。
设置 MongoDB 合作伙伴事件源
要将trigger事件发送到AWS Eventbridge ,您需要应接收事件的帐户的 AWS account ID。 打开 Amazon EventBridge 控制台 Partner event sources然后单击导航菜单中的 。Atlas Search MongoDB 合作伙伴事件源,然后单击 Set up。
在 MongoDB 合作伙伴事件源页面上,单击 Copy(复制)以将您的 AWS 帐户 ID 复制到剪贴板。
配置触发器
在获得 AWS account ID 后,您可以配置一个触发器以将事件发送到 EventBridge。
在 App Services 用户界面中,创建并配置新的数据库触发器、身份验证触发器或定时触发器,并选择 EventBridge 事件类型。
粘贴您从 EventBridge 复制的 AWS Account ID,然后选择要将触发器事件发送到的 AWS Region。
还可以选择配置用于处理触发器错误的函数。 自定义错误处理仅对数据库触发器有效。 有关详细信息,请参阅本页的“自定义错误处理”部分。
默认情况下,触发器将事件对象中的 BSON 类型转换为标准 JSON 类型。要保留 BSON 类型信息,您可以将事件对象序列化为扩展 JSON 格式。扩展 JSON 保留了类型信息,但牺牲了可读性和互操作性。
要启用扩展 JSON,请单击 Advanced (Optional) 部分中的 Enable Extended JSON 开关。
在 /triggers
目录中创建触发器配置文件。省略function_name
字段并定义AWS_EVENTBRIDGE
事件处理器。
将account_id
字段设置为您从 EventBridge 复制的AWS Account ID ,并将region
字段设置为 AWS 区域。
默认情况下,触发器将事件对象中的 BSON 类型转换为标准 JSON 类型。要保留 BSON 类型信息,您可以将事件对象序列化为扩展 JSON 格式。扩展 JSON 保留了类型信息,但牺牲了可读性和互操作性。
要启用扩展 JSON,请将extended_json_enabled
字段设置为true
。
还可以选择配置用于处理触发器错误的函数。 自定义错误处理仅对数据库触发器有效。 有关详细信息,请参阅本页的“自定义错误处理”部分。
触发器配置文件应类似于以下内容:
{ "name": "...", "type": "...", "event_processors": { "AWS_EVENTBRIDGE": { "config": { "account_id": "<AWS Account ID>", "region": "<AWS Region>", "extended_json_enabled": <boolean> } } } }
将触发器事件源与事件总线关联
返回 EventBridge 控制台,在导航窗格选择合作伙伴事件源。在 Partner event sources 表格中,查找并选择 Pending 触发器源,然后单击 Associate with event bus。
在 Associate with event bus(与事件总线关联)屏幕上,定义其他帐户和组织所需的访问权限,然后单击 Associate(关联)。
确认后,触发器事件源的状态将从 Pending(待处理)变更为 Active(活动),事件总线的名称也会更新以匹配事件源名称。您现在可以开始创建一些规则,用于触发来自该合作伙伴事件源的事件。有关更多信息,请参阅创建在 SaaS 合作伙伴事件中触发的规则。
自定义错误处理
注意
只有数据库触发器支持自定义错误处理程序
目前,只有数据库触发器支持自定义错误处理。 身份验证触发器和定时触发器目前不支持自定义错误处理。
您可以创建一个错误处理程序,在trigger失败或重试不成功时执行。自定义错误处理允许您确定来自 Amazon Web Services Eventbridge 的错误是否严重到需要暂停trigger,或者是否可以忽略错误并继续处理其他事件。有关暂停的Atlas Triggers的更多信息,请参阅暂停的Atlas Triggers。
创建新的自定义错误处理程序
您可以直接在“Create a Trigger”(创建触发器)页面中创建新函数,如下所示,或从“Functions”(函数)标签页创建。有关如何在 App Services 中定义函数的更多信息,请参阅定义函数。
要使用错误处理程序更新触发器的配置,请按照以下步骤更新应用。在步骤3中更新配置文件时,请执行以下操作:
编写错误处理程序
按照定义函数中的步骤编写错误处理程序源代码和配置文件。
有关错误处理程序源代码,请参阅以下模板错误处理程序:
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}`); };
将错误处理程序添加到触发器配置中
将error_handler
属性添加到Triggers
文件夹中的触发器配置文件中。触发器配置文件应类似于以下内容:
{ "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>" } } }
有关触发器配置文件的更多信息,请参阅触发器配置文件。
对 MongoDB Atlas 用户进行身份验证
使用您的 MongoDB Atlas 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
授予对 Atlas App Services Admin API 的访问权限。您必须将其作为持有者令牌包含在所有 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>'
创建错误处理函数
通过向“创建新函数”端点发出POST
请求,创建函数以处理失败的 AWS EventBridge 触发器的错误。
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
请求来部署草稿中的所有更改。如果第一步没有创建草稿,则会自动部署单个函数和触发器请求。
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 事件的 put 条目大于 256 KB,则 EventBridge 将引发错误。该错误将包含以下任一内容:
有关减少看跌期权条目大小的更多信息,请参阅下面的“性能优化”部分。
OTHER
所有其他错误的默认存储桶。
提示
优化其他代码错误的错误处理
您可以为最常见的错误消息制定特殊的错误处理案例,以优化使用OTHER
代码的错误处理。 为了确定哪些错误需要特殊情况,我们建议追踪您在error.message
中收到的最常见错误消息。
错误处理程序日志
您可以在应用程序日志中查看 EventBridge 触发器错误处理程序的触发器错误处理程序日志。
单击 App Services 用户界面左侧导航栏中的
Logs
。单击 Filter by Type 下拉列表并选择 Triggers Error Handlers,查看应用的所有错误处理程序日志。
将trigger_error_handler
值传递给--type
标志,以查看该应用的所有错误处理程序日志。
appservices logs list --type=trigger_error_handler
通过向检索 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" }'
要了解有关查看应用程序日志的更多信息,请参阅查看应用程序日志。
示例事件
以下对象配置触发器以将事件发送到 AWS Eventbridge 并处理错误:
"event_processors": { "AWS_EVENTBRIDGE": { "config": { "account_id": "012345678901", "region": "us-east-1" } } }, "error_handler": { "config": { "enabled": true, "function_name": "myErrorHandler.js" } }
性能优化
EventBridge 触发事件的 AWS put 条目必须小于 256 KB。
有关 计算 Amazon PutEvents 事件条目大小的更多信息,请参阅 AWS 文档。
在使用数据库触发器时,可以在将消息发送到 EventBridge 之前使用项目表达式减小文档大小。该表达式允许您仅包含指定的字段,从而减小文档大小。