搭配使用 Lambda 與 Amazon DocumentDB - AWS Lambda

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

搭配使用 Lambda 與 Amazon DocumentDB

您可以透過將 Amazon DocumentDB 叢集設定為事件來源,使用 Lambda 函數處理 Amazon DocumentDB (with MongoDB compatibility) 變更串流中的事件。接著,您可以在每次使用 Amazon DocumentDB 叢集變更資料時,調用 Lambda 函數來自動執行事件驅動的工作負載。

注意

Lambda 僅支援 Amazon DocumentDB 4.0 和 5.0 版。Lambda 不支援 3.6 版。

此外,針對事件來源映射,Lambda 僅支援執行個體型叢集和區域叢集。Lambda 不支援 彈性叢集全域叢集。使用 Lambda 做為用戶端連線至 Amazon DocumentDB 時不適用此限制。Lambda 可以連線至所有叢集類型來執行 CRUD 操作。

Lambda 會依照抵達的順序處理來自 Amazon DocumentDB 變更串流的事件。因此,函數一次只能處理來自 DocumentDB 的一個並行調用。若要監控函數,您可以追蹤其並行指標

警告

Lambda 事件來源對應至少處理每個事件一次,而且可能會重複處理批次。為了避免與重複事件相關的潛在問題,我們強烈建議您將函數代碼設為冪等。若要深入了解,請參閱 AWS 知識中心如何讓 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 函數的事件來源使用前,請留意以下先決條件。您必須:

注意

雖然 Lambda 函數的逾時上限通常為 15 分鐘,但 Amazon MSK、自我管理的 Apache Kafka、Amazon DocumentDB 以及 Amazon MQ for ActiveMQ 和 Amazon MQ for RabbitMQ 的事件來源映射只支援 14 分鐘逾時限制上限的函數。此限制條件可確保事件來源映射能夠正確處理函數錯誤和重試。

網路組態

Lambda 必須能存取與您 Amazon DocumentDB 叢集相關聯的 Amazon VPC 資源。根據預設,Amazon DocumentDB 叢集連接埠為 27017,但您可以變更此設定。如果您變更連接埠,請相應地修改安全性群組設定。如果您是在 Secrets Manager 中設定秘密以透過叢集驗證 Lambda,請一併為 Secrets Manager 部署 VPC 端點

或者,確保與您 Amazon DocumentDB 叢集相關聯的 VPC 的每個公有子網路都含有一個 NAT 閘道。如需詳細資訊,請參閱 VPC 連線函數的網際網路和服務存取

使用下列規則 (最低限度) 設定 Amazon VPC 安全群組:

  • 傳入規則

    • 對於您為事件來源指定的安全群組,允許 Amazon DocumentDB 叢集連接埠上的所有流量 (預設為 27017)。

    • (僅限 VPC 端點) 針對與 VPC 端點相關聯的安全群組,允許連接埠 443 上所有來自您為事件來源指定的安全群組之流量。

  • 傳出規則

    • 針對所有目的地,允許連接埠 443 上的所有流量。

    • 對於您為事件來源指定的安全群組,允許 Amazon DocumentDB 叢集連接埠上的所有流量 (預設為 27017)。

建立 Amazon DocumentDB 事件來源映射 (主控台)

若要讓 Lambda 函數從 Amazon DocumentDB 叢集的變更串流中讀取,請建立 DocumentDB 事件來源映射。本節會說明如何透過 Lambda 主控台執行這項操作。如需 AWS SDK 和 AWS CLI 指示,請參閱建立 Amazon DocumentDB 事件來源映射 (SDK 或 CLI)

建立 Amazon DocumentDB 事件來源映射 (主控台)
  1. 開啟 Lambda 主控台中的 函數頁面

  2. 選擇函數的名稱。

  3. 函式概觀 下,選擇 新增觸發條件

  4. 觸發條件組態底下的下拉式清單中,選擇 DocumentDB

  5. 設定需要的選項,然後選擇 新增

Lambda 支援以下 Amazon DocumentDB 事件來源的選項:

  • DocumentDB 叢集:選取 Amazon DocumentDB 叢集。

  • 啟用觸發條件:選擇您是否要立即啟用觸發條件。若勾選此核取方塊,您的函數會在建立事件來源映射時立即開始接收來自指定 Amazon DocumentDB 變更串流的流量。建議您取消勾選此核取方塊,以便在停用狀態下建立事件來源映射來進行測試。完成建立後,您隨時可以啟動事件來源映射。

  • 資料庫名稱: 輸入叢集內要使用的資料庫名稱。

  • (選用) 集合名稱:輸入資料庫內要使用的集合名稱。如果您未指定集合,Lambda 會偵聽資料庫中每個集合中的所有事件。

  • 批次大小: 設定單一批次中要擷取的訊息數目上限 (最高 10,000)。預設批次大小為 100。

  • 開始位置: 選擇串流中要從中開始讀取記錄的位置。

    • 最新: 僅處理已新增到串流的新記錄。Lambda 建立完事件來源後,您的函數才會開始處理記錄。這表示系統可能會捨棄部分記錄,直到您的事件來源成功建立為止。

    • 水平修剪 - 處理所有在串流中的記錄。Lambda 會透過叢集的日誌保留持續時間來決定開始讀取事件的時間點。具體來說,Lambda 會從 current_time - log_retention_duration 開始進行讀取。變更串流必須在此時間戳記前處於作用中狀態,Lambda 才能正確讀取所有事件。

    • At timestamp (在時間戳記為) - 從特定時間開始處理記錄。變更串流必須在指定時間戳記前處於作用中狀態,Lambda 才能正確讀取所有事件。

  • 身分驗證: 選擇在叢集中存取中介裝置的身分驗證方式。

    • BASIC_AUTH: 使用基本身分驗證下,您必須提供含有憑證的 Secrets Manager 金鑰,才能存取叢集。

  • Secrets Manager 金鑰:選擇含有存取 Amazon DocumentDB 叢集所需身分驗證詳細資料 (使用者名稱和密碼) 的 Secrets Manager 金鑰。

  • (選用) 批次間隔:在調用函數前收集記錄的最長時間 (秒),上限為 300 秒。

  • (選用) 完整文件組態:文件更新作業方面,請選擇要傳送至串流的內容。預設值為 Default,這表示 Amazon DocumentDB 針對每個變更串流事件僅會傳送說明所做變更的差異。如需有關此欄位的詳細資訊,請參閱FullDocument在 MongoDB API 文件中。

    • 預設: Lambda 僅會傳送說明所做變更的部分文件。

    • UpdateLookup-Lambda 發送描述更改的增量值以及整個文檔的副本。

建立 Amazon DocumentDB 事件來源映射 (SDK 或 CLI)

若要使用 AWS SDK 來建立或管理 Amazon DocumentDB 事件來源映射,您可以使用下列 API 操作:

若要使用建立事件來源對映 AWS CLI,請使用create-event-source-mapping指令。以下範例使用此命令,將名為 my-function 的函數映射至 Amazon DocumentDB 變更串流。事件來源是由 Amazon Resource Name (ARN) 指定,批次大小為 500,且開始時間為 Unix 時間的時間戳記。此命令也會指定 Lambda 用來連線至 Amazon 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 命令來更新 Amazon DocumentDB 事件來源的設定。以下命令將批次大小更新為 1,000,並將批次間格更新為 10 秒。對於此命令,您必須擁有事件來源映射的 UUID (可使用 list-event-source-mapping 命令或 Lambda 主控台擷取)。

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" }

若要刪除 Amazon DocumentDB 事件來源映射,請使用 delete-event-source-mapping 命令。

aws lambda delete-event-source-mapping \ --uuid 2b733gdc-8ac3-cdf5-af3a-1827b3b11284

輪詢和串流開始位置

請注意,建立和更新事件來源映射期間的串流輪詢最終會一致。

  • 在建立事件來源映射期間,從串流開始輪詢事件可能需要幾分鐘時間。

  • 在更新事件來源映射期間,從串流停止並重新開始輪詢事件可能需要幾分鐘時間。

這種行為表示如果您指定 LATEST 當作串流的開始位置,事件來源映射可能會在建立或更新期間遺漏事件。若要確保沒有遺漏任何事件,請將串流開始位置指定為 TRIM_HORIZONAT_TIMESTAMP

監控 Amazon DocumentDB 事件來源

為協助您監控 Amazon DocumentDB 事件來源,Lambda 會在您的函數處理完一批記錄後發出 IteratorAge 指標。迭代器存留期是最近事件和目前時間戳記之間的差距。基本上,IteratorAge 指標會指出批次中最後處理的記錄經過了多久的時間。如果函數目前正在處理新的事件,可使用迭代器存留期來預估記錄新增與函數實際處理之間的延遲。

IteratorAge 的增加趨勢可看出您函數的問題。如需詳細資訊,請參閱 使用 Lambda 函數指標

Lambda 支援的承載上限為 6MB。不過,Amazon DocumentDB 變更串流事件的大小可達 16MB。如果變更串流嘗試向 Lambda 傳送大於 6MB 的變更串流事件,Lambda 會捨棄訊息並發出 OversizedRecordCount 指標。Lambda 會盡力發送所有指標。