将 Amazon Lambda 与 Amazon DocumentDB 结合使用
您可以通过将 Amazon DocumentDB 集群配置为事件源,从而使用 Amazon Lambda 函数来处理 Amazon DocumentDB(与 MongoDB 兼容)更改流 中的事件。然后,您可以在 Amazon DocumentDB 集群每次发生数据更改时调用 Lambda 函数,从而实现事件驱动型工作负载的自动化。
Amazon DocumentDB 事件示例
{ "eventSourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:canaryclusterb2a659a2-qo5tcmqkcl03", "events": [ { "event": { "_id": { "_data": "0163eeb6e7000000090100000009000041e1" }, "clusterTime": { "$timestamp": { "t": 1676588775, "i": 9 } }, "documentKey": { "_id": { "$oid": "63eeb6e7d418cd98afb1c1d7" } }, "fullDocument": { "_id": { "$oid": "63eeb6e7d418cd98afb1c1d7" }, "anyField": "sampleValue" }, "ns": { "db": "test_database", "coll": "test_collection" }, "operationType": "insert" } } ], "eventSource": "aws:docdb" }
有关事件类型及其形状的更多信息,请参阅 MongoDB 文档
先决条件和权限
将 Amazon DocumentDB 用作 Lambda 函数的事件源之前,请注意以下先决条件:
-
您必须有一个现有的 DocumentDB 集群并且该集群必须与您的函数位于同一 Amazon Web Services 账户和 Amazon Web Services 区域中。如果您没有现有的集群,可以按照 Amazon DocumentDB 入门 中的步骤创建一个。
-
Lambda 必须具有访问与您的 DocumentDB 集群关联的 Amazon Virtual Private Cloud(Amazon VPC)资源的权限。有关更多信息,请参阅网络配置。
-
您必须在您的 DocumentDB 集群上启用 TLS(这是默认设置)。如果您禁用了 TLS,Lambda 将无法与您的集群通信。请重新启用 TLS 以恢复与 Lambda 的连接。
-
您必须在您的 DocumentDB 集群上激活更改流。有关更多信息,请参阅 将更改流与 Amazon DocumentDB 结合使用。
-
在设置过程中,您必须提供凭证以便 Lambda 能够访问您的的 DocumentDB 集群。为此,您可以提供包含访问集群所需详细身份验证信息(用户名和密码)的 Amazon Secrets Manager 密钥。
-
如果您使用控制台来设置事件源,请在 Secrets Manager 密钥字段中提供此密钥。
-
如果您使用 Amazon Command Line Interface(Amazon CLI)来设置事件源,请在 CreateEventSourceMapping 或 UpdateEventSourceMapping API 的 SourceAccessConfigurations 字段中提供此密钥。例如:
aws lambda create-event-source-mapping \ ... --source-access-configurations '[{"Type":"BASIC_AUTH","URI":"arn:aws:secretsmanager:us-west-2:123456789012:secret:DocDBSecret-AbC4E6"}]' \ ...
-
-
您必须向 Lambda 授予管理与您的 DocumentDB 流相关的资源的权限。将以下角色权限手动添加到您的函数的 执行角色:
-
您发送到 Lambda 的每个 DocumentDB 更改流事件的大小不能超过 6MB。Lambda 仅支持最大 6MB 的负载。如果您的更改流尝试向 Lambda 发送大于 6MB 的事件,Lambda 会丢弃该消息并发送
OversizedRecordCount
指标。Lambda 将尽力发送所有指标。
网络配置
Lambda 必须具有访问与您的 DocumentDB 集群关联的 Amazon VPC 资源的权限。如果您在 Secrets Manager 中配置了密钥,以便 Lambda 进行集群身份验证,则还应部署一个 用于 Secrets Manager 的 VPC 端点。
或者,请确保与您的 DocumentDB 集群关联的 VPC 在每个公有子网中都包含一个 NAT 网关。有关更多信息,请参阅VPC 连接函数的 Internet 和服务访问。
使用以下规则配置您的 Amazon VPC 安全组(至少):
-
入站规则 – 允许为您的事件源指定的安全组的所有流量通过 DocumentDB 集群端口(27017)。
-
出站规则 – 允许所有目标的端口 443 上的所有流量传输。允许为您的事件源指定的安全组的所有流量通过 DocumentDB 集群端口(27017)。
-
如果您使用的是 VPC 端点而不是 NAT 网关,则与 VPC 端点关联的安全组必须允许来自事件源安全组的端口 443 上的所有入站流量。
将 DocumentDB 更改流配置为事件源
要配置函数以从 DocumentDB 集群更改流中读取数据,请创建一个 DocumentDB 事件源映射。这一部分介绍了如何从控制台执行此操作。有关使用 Amazon CLI 配置 DocumentDB 更改流的信息,请参阅事件源映射 API。
创建 DocumentDB 事件源映射(控制台)
-
打开 Lamba 控制台的函数页面
。 -
选择一个函数的名称。
-
在 Function overview(函数概览)下,选择 Add trigger(添加触发器)。
-
在下拉菜单中,选择 DocumentDB。
-
配置必填选项,然后选择 Add(添加)。
Lambda 支持 DocumentDB 事件源的以下选项:
-
立即激活触发器 – 选择是否要立即激活触发器。如果选中此复选框,则在创建事件源映射后,您的函数会立即开始接收来自指定 DocumentDB 更改流的流量。我们建议取消选中此复选框,以便在禁用状态下创建事件源映射以进行测试。创建事件源映射后,您可以随时将其激活。
-
DocumentDB 集群 – 选择一个 DocumentDB 集群。
-
数据库名称 – 输入集群中要使用的数据库的名称。
-
集合名称 – 输入数据库中要使用的集合的名称。如果您未指定集合,Lambda 将侦听来自数据库中每个集合的所有事件。
-
身份验证 – 选择访问集群中的代理时将使用的身份验证方法。
-
BASIC_AUTH – 使用基本身份验证时,您必须提供包含访问集群凭据所需凭证的 Secrets Manager 密钥。
-
-
Secrets Manager 密钥 – 选择包含访问 DocumentDB 集群所需身份验证详细信息(用户名和密码)的 Secrets Manager 密钥。
-
批处理大小 – 设置要在单个批处理中检索的最大消息数,最高为 10000。默认批处理大小为 100。
-
开始位置 – 选择将从流中开始读取记录的位置。
-
最新 – 仅处理添加到流中的新记录。您的函数仅在 Lambda 完成创建事件源后才会开始处理记录。这意味着在成功创建事件源之前,某些记录可能会被丢弃。
-
Trim horizon(时间范围)– 处理流中的所有记录。Lambda 使用集群的日志保留期来确定从哪里开始读取事件。具体而言,Lambda 将从
current_time - log_retention_duration
开始读取事件。您的更改流必须在此时间戳之前已经处于活动状态,才能确保 Lambda 正确读取所有事件。 -
At timestamp(时间戳)– 处理从特定时间开始的记录。您的更改流必须在指定的时间戳之前已经处于活动状态,才能确保 Lambda 正确读取所有事件。
-
-
完整文档配置 – 对于文档更新操作,请选择要发送到流中的内容。默认值为
Default
,这意味着对于每个更改流事件,DocumentDB 仅发送一个描述所发生更改的增量。有关此字段的更多信息,请参阅 MongoDB Javadocs 中的 FullDocument。 -
默认 – Lambda 将仅发送描述所发生更改的部分文档。
-
UpdateLookup – Lambda 将发送一个描述所发生更改的增量以及完整文档的副本。
-
事件源映射 API
要使用 Amazon CLI 或 Amazon SDK
注意
在更新、禁用或删除 Amazon DocumentDB 事件源映射后,更改最长可能需要 15 分钟才会生效。在此期间结束之前,您的事件源映射可能会继续处理事件并使用您之前的设置来调用您的函数。即使控制台中显示的事件源映射状态表明更改已经生效,也可能发生这种情况。
要使用 Amazon CLI 创建事件源映射,请使用 create-event-source-mapping
命令。以下示例使用 Amazon CLI 将名为 my-function
的函数映射到一个 DocumentDB 更改流。事件源由 Amazon 资源名称(ARN)指定,批处理大小为 500,从以 Unix 时间表示的时间戳开始。该命令还指定了 Lambda 用于连接到 DocumentDB 的 Secrets Manager 密钥,以及用于指定要从中读取的数据库和集合的 document-db-event-source-config
参数:
aws lambda create-event-source-mapping --function-name my-function \ --event-source-arn arn:aws:rds:us-west-2:123456789012:cluster:privatecluster7de2-epzcyvu4pjoy --batch-size 500 \ --starting-position AT_TIMESTAMP \ --starting-position-timestamp 1541139109 \ --source-access-configurations '[{"Type":"BASIC_AUTH","URI":"arn:aws:secretsmanager:us-east-1:123456789012:secret:DocDBSecret-BAtjxi"}]' \ --document-db-event-source-config '{"DatabaseName":"test_database", "CollectionName": "test_collection"}' \
应看到类似如下内容的输出:
{ "UUID": "2b733gdc-8ac3-cdf5-af3a-1827b3b11284", "BatchSize": 500, "DocumentDBEventSourceConfig": { "CollectionName": "test_collection", "DatabaseName": "test_database", "FullDocument": "Default" }, "MaximumBatchingWindowInSeconds": 0, "EventSourceArn": "arn:aws:rds:us-west-2:123456789012:cluster:privatecluster7de2-epzcyvu4pjoy", "FunctionArn": "arn:aws:lambda:us-west-2:123456789012:function:my-function", "LastModified": 1541348195.412, "LastProcessingResult": "No records processed", "State": "Creating", "StateTransitionReason": "User action" }
创建后,您可以使用 update-event-source-mapping
命令更改与您的 DocumentDB 事件源相关的更新设置。例如,以下命令会将批处理大小更新为 1000,并将批处理时间窗口更新为 10 秒。对于此命令,您需要有事件源映射的 UUID,并且您可以通过 list-event-source-mapping
调用或控制台检索该值:
aws lambda update-event-source-mapping --function-name my-function \ --uuid f89f8514-cdd9-4602-9e1f-01a5b77d449b \ --batch-size 1000 \ --batch-window 10
您应该看到此输出内容:
{ "UUID": "2b733gdc-8ac3-cdf5-af3a-1827b3b11284", "BatchSize": 500, "DocumentDBEventSourceConfig": { "CollectionName": "test_collection", "DatabaseName": "test_database", "FullDocument": "Default" }, "MaximumBatchingWindowInSeconds": 0, "EventSourceArn": "arn:aws:rds:us-west-2:123456789012:cluster:privatecluster7de2-epzcyvu4pjoy", "FunctionArn": "arn:aws:lambda:us-west-2:123456789012:function:my-function", "LastModified": 1541359182.919, "LastProcessingResult": "OK", "State": "Updating", "StateTransitionReason": "User action" }
Lambda 会异步更新设置,并且在更新完成之前,您可能无法在输出中看到这些更改。使用 get-event-source-mapping
命令查看当前状态。
aws lambda get-event-source-mapping --uuid f89f8514-cdd9-4602-9e1f-01a5b77d449b
您应该看到此输出内容:
{ "UUID": "2b733gdc-8ac3-cdf5-af3a-1827b3b11284", "DocumentDBEventSourceConfig": { "CollectionName": "test_collection", "DatabaseName": "test_database", "FullDocument": "Default" }, "BatchSize": 1000, "MaximumBatchingWindowInSeconds": 10, "EventSourceArn": "arn:aws:rds:us-west-2:123456789012:cluster:privatecluster7de2-epzcyvu4pjoy", "FunctionArn": "arn:aws:lambda:us-west-2:123456789012:function:my-function", "LastModified": 1541359182.919, "LastProcessingResult": "OK", "State": "Enabled", "StateTransitionReason": "User action" }
要删除 DocumentDB 事件源映射,请使用 delete-event-source-mapping
命令:
aws lambda delete-event-source-mapping \ --uuid 2b733gdc-8ac3-cdf5-af3a-1827b3b11284
监控 DocumentDB 事件源
为便于您监控 DocumentDB 事件源,在您的函数处理完一批记录后,Lambda 将发出 IteratorAge
指标。IteratorAge
是最近一个事件的时间戳和当前时间戳之间的差。基本上,该指标会说明处理该批处理中最后一条记录后经过的时间。如果您的函数当前正在处理新事件,则可使用迭代器龄期来估算新记录的添加时间与函数处理新记录的时间之间的延迟。
如果 IteratorAge
呈上升趋势,则可能说明您的函数存在问题。有关更多信息,请参阅使用 Lambda 函数指标。
Lambda 仅支持最大 6MB 的负载。但是,DocumentDB 更改流事件的大小可达 16MB。如果您的更改流尝试向 Lambda 发送大于 6MB 的更改流事件,Lambda 会丢弃该消息并发送 OversizedRecordCount
指标。Lambda 将尽力发送所有指标。