本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 搭配使用 Lambda 與 Amazon MQ **注意** 如要將資料傳送到 Lambda 函數以外的目標，或在傳送資料之前讓資料更豐富，請參閱 [Amazon EventBridge Pipes](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-pipes.html)。 Amazon MQ 是一項受管訊息代理程式服務，適用於 [Apache ActiveMQ](https://activemq.apache.org/) 和 [RabbitMQ](https://www.rabbitmq.com)。*訊息代理程式*透過主題或佇列事件目的地，允許軟體應用程式和元件使用各種程式設計語言、作業系統和正式簡訊協定來進行通訊。 Amazon MQ 還可以透過安裝 ActiveMQ 或 RabbitMQ 代理程式，並提供不同的網路拓撲和其他基礎架構需求，來代表您管理 Amazon Elastic Compute Cloud (Amazon EC2) 執行個體。 您可以使用 Lambda 函數來處理您的 Amazon MQ 訊息代理程式中的記錄。Lambda 透過[事件來源映射](invocation-eventsourcemapping.md)叫用函數，這是從您的代理程式讀取訊息並[同步](invocation-sync.md)叫用函數的 Lambda 資源。 **警告** Lambda 事件來源映射至少會處理每個事件一次，而且可能會重複處理記錄。為避免與重複事件相關的潛在問題，強烈建議您讓函數程式碼具有等冪性。若要進一步了解，請參閱 AWS 知識中心中的[如何使 Lambda 函數具有等冪性](https://repost.aws/knowledge-center/lambda-function-idempotent)。 Amazon MQ 事件來源映射具有下列組態限制： + 並行：使用 Amazon MQ 事件來源映射的 Lambda 函數具有預設[並行](lambda-concurrency.md)上限設定。若使用 ActiveMQ，Lambda 服務會將並行執行環境的數量上限設為每個 Amazon MQ 事件來源映射 5 個。若使用 RabbitMQ，並行執行環境的數量上限為每個 Amazon MQ 事件來源映射 1 個。即使您變更函數的保留或佈建並行設定，Lambda 服務還是無法提供更多可用的執行環境。若要請求增加單一 Amazon MQ 事件來源映射的預設並行上限， 支援 請聯絡事件來源映射 UUID 以及 區域。由於增加會套用在特定事件來源映射層級，而不是帳戶或區域層級，因此您需要為每個事件來源映射手動請求擴展增加。 + 跨帳戶 - Lambda 不支援跨帳戶處理。您無法用 Lambda 處理來自不同 AWS 帳戶中 Amazon MQ 訊息代理程式的記錄。 + 身分驗證支援 - 對於 ActiveMQ，僅支援 ActiveMQ [SimpleAuthenticationPlugin](https://activemq.apache.org/security#simple-authentication-plugin)。對於 RabbitMQ，僅支援 [PLAIN](https://www.rabbitmq.com/access-control.html#mechanisms) 身分驗證機制。使用者必須使用 AWS Secrets Manager 來管理其登入資料。如需 ActiveMQ 身分驗證的詳細資訊，請參閱 *Amazon MQ 開發人員指南*中的[將 ActiveMQ 代理程式與 LDAP 整合](https://docs.aws.amazon.com/amazon-mq/latest/developer-guide/security-authentication-authorization.html)。 + 連線配額 - 代理程式每個線路層級協定允許的連線數量上限。此配額以代理程式執行個體類型為基礎。如需詳細資訊，請參閱 *Amazon MQ 開發人員指南*中的 **Amazon MQ 中的配額**的[代理程式](https://docs.aws.amazon.com/amazon-mq/latest/developer-guide/amazon-mq-limits.html#broker-limits)。 + 連線 - 您可以在公有或私有 Virtual Private Cloud (VPC) 中建立代理程式。若是私有 VPC，您的 Lambda 函數需要存取 VPC 才能接收訊息。如需詳細資訊，請參閱本節稍後的[設定網路安全](process-mq-messages-with-lambda.md#process-mq-messages-with-lambda-networkconfiguration)。 + 事件目的地 - 僅支援佇列目的地。然而，您可以使用虛擬主題，當作為佇列與 Lambda 互動時，其行為在內部可作為主題。如需詳細資訊，請參閱 Apache ActiveMQ 網站上的[虛擬目的地](https://activemq.apache.org/virtual-destinations)，以及 RabbitMQ 網站上的[虛擬主機](https://www.rabbitmq.com/vhosts.html)。 + 網路拓撲 - 對於 ActiveMQ，每個事件來源映射僅支援單一執行個體或待命代理程式。對於 RabbitMQ，每個事件來源映射僅支援單一執行個體代理程式或叢集部署。單一執行個體代理程式需要容錯移轉端點。如需這些代理程式部署模式的詳細資訊，請參閱 *Amazon MQ 開發人員指南*中的 [ActiveMQ 代理程式架構](https://docs.aws.amazon.com/amazon-mq/latest/developer-guide/amazon-mq-broker-architecture.html)和 [Rabbit MQ 代理程式架構](https://docs.aws.amazon.com/amazon-mq/latest/developer-guide/rabbitmq-broker-architecture.html)。 + 協定 - 支援的協定取決於 Amazon MQ 整合的類型。 + 對於 ActiveMQ 整合，Lambda 會使用 OpenWire/Java Message Service (JMS) 協定來取用訊息。不支援透過其他協定來取用訊息。在 JMS 協定中，僅支援 [https://activemq.apache.org/components/cms/api_docs/activemqcpp-3.6.0/html/classactivemq_1_1commands_1_1_active_m_q_text_message.html](https://activemq.apache.org/components/cms/api_docs/activemqcpp-3.6.0/html/classactivemq_1_1commands_1_1_active_m_q_text_message.html) 和 [https://activemq.apache.org/components/cms/api_docs/activemqcpp-3.9.0/html/classactivemq_1_1commands_1_1_active_m_q_bytes_message.html](https://activemq.apache.org/components/cms/api_docs/activemqcpp-3.9.0/html/classactivemq_1_1commands_1_1_active_m_q_bytes_message.html)。Lambda 也支援 JMS 自訂屬性。如需有關 OpenWire 協定的詳細資訊，請參閱 Apache ActiveMQ 網站上的 [OpenWire](https://activemq.apache.org/openwire.html)。 + 對於 RabbitMQ 整合，Lambda 透過 AMQP 0-9-1 協定來取用訊息。不支援透過其他協定來取用訊息。如需 RabbitMQ 實作 AMQP 0-9-1 協定的詳細資訊，請參閱 RabbitMQ 網站上的 [AMQP 0-9-1 完整參考指南](https://www.rabbitmq.com/amqp-0-9-1-reference.html)。 Lambda 會自動支援 Amazon MQ 支援的最新版 ActiveMQ 和 RabbitMQ。如需支援的最新版，請參閱 *Amazon MQ 開發人員指南*中的 [Amazon MQ 版本備註](https://docs.aws.amazon.com/amazon-mq/latest/developer-guide/amazon-mq-release-notes.html)。 **注意** 根據預設，Amazon MQ 具有每週代理程式維護時段。代理程式在該時段不可用。若是無待命狀態的代理程式，則 Lambda 無法在該時段處理任何訊息。 **Topics** + [了解 Amazon MQ 的 Lambda 取用者群組](#services-mq-configure) + [設定 Lambda 的 Amazon MQ 事件來源](process-mq-messages-with-lambda.md) + [事件來源映射參數](services-mq-params.md) + [從 Amazon MQ 事件來源篩選事件](with-mq-filtering.md) + [對 Amazon MQ 事件來源映射錯誤進行疑難排解](services-mq-errors.md) ## 了解 Amazon MQ 的 Lambda 取用者群組 若要與 Amazon MQ 互動，Lambda 會建立可以從您的 Amazon MQ 代理程式讀取的取用者群體。建立取用者群組時，會使用與事件來源映射 UUID 相同的 ID。 對於 Amazon MQ 事件來源，Lambda 會批次處理記錄，並在單個承載中將它們傳送到您的函數。要控制行為，您可以設定批次間隔和批次大小。Lambda 會提取訊息，直到它處理最大為 6 MB 的承載大小、批次間隔過期或記錄數達到完整批次大小。如需詳細資訊，請參閱[批次處理行為](invocation-eventsourcemapping.md#invocation-eventsourcemapping-batching)。 取用者群組會將訊息擷取為位元組 BLOB，並透過 base64 將其編碼成單一 JSON 承載，然後調用您的函數。如果函數針對批次中的任何訊息傳回錯誤，Lambda 會重試整個批次的訊息，直至處理成功或訊息過期。 **注意** 雖然 Lambda 函數的逾時上限通常為 15 分鐘，但 Amazon MSK、自我管理的 Apache Kafka、Amazon DocumentDB 以及 Amazon MQ for ActiveMQ 和 Amazon MQ for RabbitMQ 的事件來源映射只支援 14 分鐘逾時限制上限的函數。此限制條件可確保事件來源映射能夠正確處理函數錯誤和重試。 您可以使用 Amazon CloudWatch 中的 `ConcurrentExecutions` 指標，監控指定函數的並行用量。如需並行的詳細資訊，請參閱[設定函數的預留並行](configuration-concurrency.md)。 **Example Amazon MQ 記錄事件** ``` { "eventSource": "aws:mq", "eventSourceArn": "arn:aws:mq:us-east-2:111122223333:broker:test:b-9bcfa592-423a-4942-879d-eb284b418fc8", "messages": [ { "messageID": "ID:b-9bcfa592-423a-4942-879d-eb284b418fc8-1---mq---us-east-2.amazonaws.com.rproxy.goskope.com-37557-1234520418293-4:1:1:1:1", "messageType": "jms/text-message", "deliveryMode": 1, "replyTo": null, "type": null, "expiration": "60000", "priority": 1, "correlationId": "myJMSCoID", "redelivered": false, "destination": { "physicalName": "testQueue" }, "data":"QUJDOkFBQUE=", "timestamp": 1598827811958, "brokerInTime": 1598827811958, "brokerOutTime": 1598827811959, "properties": { "index": "1", "doAlarm": "false", "myCustomProperty": "value" } }, { "messageID": "ID:b-9bcfa592-423a-4942-879d-eb284b418fc8-1---mq---us-east-2.amazonaws.com.rproxy.goskope.com-37557-1234520418293-4:1:1:1:1", "messageType": "jms/bytes-message", "deliveryMode": 1, "replyTo": null, "type": null, "expiration": "60000", "priority": 2, "correlationId": "myJMSCoID1", "redelivered": false, "destination": { "physicalName": "testQueue" }, "data":"LQaGQ82S48k=", "timestamp": 1598827811958, "brokerInTime": 1598827811958, "brokerOutTime": 1598827811959, "properties": { "index": "1", "doAlarm": "false", "myCustomProperty": "value" } } ] } ``` ``` { "eventSource": "aws:rmq", "eventSourceArn": "arn:aws:mq:us-east-2:111122223333:broker:pizzaBroker:b-9bcfa592-423a-4942-879d-eb284b418fc8", "rmqMessagesByQueue": { "pizzaQueue::/": [ { "basicProperties": { "contentType": "text/plain", "contentEncoding": null, "headers": { "header1": { "bytes": [ 118, 97, 108, 117, 101, 49 ] }, "header2": { "bytes": [ 118, 97, 108, 117, 101, 50 ] }, "numberInHeader": 10 }, "deliveryMode": 1, "priority": 34, "correlationId": null, "replyTo": null, "expiration": "60000", "messageId": null, "timestamp": "Jan 1, 1970, 12:33:41 AM", "type": null, "userId": "AIDACKCEVSQ6C2EXAMPLE", "appId": null, "clusterId": null, "bodySize": 80 }, "redelivered": false, "data": "eyJ0aW1lb3V0IjowLCJkYXRhIjoiQ1pybWYwR3c4T3Y0YnFMUXhENEUifQ==" } ] } } ``` 在 RabbitMQ 範例中，`pizzaQueue` 是 RabbitMQ 佇列的名稱，`/` 是虛擬主機的名稱。接收訊息時，事件來源會在 `pizzaQueue::/` 列出訊息。 # 設定 Lambda 的 Amazon MQ 事件來源 **Topics** + [設定網路安全](#process-mq-messages-with-lambda-networkconfiguration) + [建立事件來源映射](#services-mq-eventsourcemapping) ## 設定網路安全 若要透過事件來源映射授予 Lambda 對 Amazon MQ 的完整存取權，您的代理程式必須使用公有端點 (公有 IP 位址)，或者您必須提供建立代理程式之 Amazon VPC 的存取權。 當您將 Amazon MQ 與 Lambda 搭配使用時，請建立 [AWS PrivateLink VPC 端點](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html)，為您的函數提供 Amazon VPC 中資源的存取權。 **注意** AWS PrivateLink 具有使用事件輪詢器預設 （隨需） 模式之事件來源映射的函數需要 VPC 端點。如果您的事件來源映射使用[佈建模式](invocation-eventsourcemapping.md#invocation-eventsourcemapping-provisioned-mode)，則不需要設定 AWS PrivateLink VPC 端點。 建立端點以提供對下列資源的存取權： + Lambda：為 Lambda 服務主體建立端點。 + AWS STS — 為 建立端點， AWS STS 以便服務主體代表您擔任角色。 + Secrets Manager：如果您的代理程式使用 Secrets Manager 來儲存憑證，則請為 Secrets Manager 建立端點。 或者，在 Amazon VPC 中的每個公有子網路上設定一個 NAT 閘道。如需詳細資訊，請參閱[啟用 VPC 連線的 Lambda 函數的網際網路存取](configuration-vpc-internet.md)。 當您為 Amazon MQ 建立事件來源映射時，Lambda 會檢查是否已存在彈性網絡介面 (ENI)，適用於為您的 Amazon VPC 設定的子網路和安全群組。如果 Lambda 找到現有的 ENI，則它會嘗試重複使用它們。否則，Lambda 會建立新的 ENI 以連線至事件來源並調用您的函數。 **注意** Lambda 函數一律會在 Lambda 服務所擁有的 VPC 內執行。函數的 VPC 組態不會影響事件來源映射。只有事件來源的聯網組態會決定 Lambda 如何連線至您的事件來源。 為包含代理程式的 Amazon VPC 設定安全群組。根據預設，Amazon MQ 會使用下列連接埠：`61617` (Amazon MQ for ActiveMQ) 和 `5671` (Amazon MQ for RabbitMQ)。 + 傳入規則：允許與事件來源相關聯之安全群組的預設代理程式連接埠上的所有流量。或者，您可使用自我參照安全群組規則，允許來自同一安全群組內其他執行個體的存取。 + 傳出規則 – 如果您的函數需要與服務通訊`443`，允許外部目的地連接埠上的所有流量 AWS 。或者，如果您不需要與其他 AWS 服務通訊，您也可以使用自我參考安全群組規則來限制對代理程式的存取。 + Amazon VPC 端點傳入規則：如果您使用的是 Amazon VPC 端點，與您的 Amazon VPC 端點相關聯的安全群組必須允許來自代理程式安全群組的連接埠 `443` 上的傳入流量。 如果代理程式使用身分驗證，也可以限制 Secrets Manager 端點的端點政策。若要呼叫 Secrets Manager API，Lambda 會使用您的函數角色，而不是 Lambda 服務主體。 **Example VPC 端點政策 — Secrets Manager 端點** ``` { "Statement": [ { "Action": "secretsmanager:GetSecretValue", "Effect": "Allow", "Principal": { "AWS": [ "arn:aws::iam::123456789012:role/my-role" ] }, "Resource": "arn:aws::secretsmanager:us-west-2:123456789012:secret:my-secret" } ] } ``` 當您使用 Amazon VPC 端點時， 會使用端點的彈性網路界面 (ENI) AWS 路由您的 API 呼叫來叫用函數。Lambda 服務主體需要在使用這些 ENI 的任何角色和函數上呼叫 `lambda:InvokeFunction`。 根據預設，Amazon VPC 端點具有開放的 IAM 政策，允許廣泛存取資源。最佳實務是限制這些政策，以使用該端點執行所需的動作。為了確保事件來源映射能夠調用 Lambda 函數，VPC 端點政策必須允許 Lambda 服務主體呼叫 `sts:AssumeRole` 和 `lambda:InvokeFunction`。限制您的 VPC 端點政策以僅允許源自您組織內部的 API 呼叫，可阻止事件來源映射正常運作，因此在這些政策中需要 `"Resource": "*"`。 下列範例 VPC 端點政策展示了如何授予 Lambda 服務主體對 AWS STS 和 Lambda 端點的必要存取權。 **Example VPC 端點政策 — AWS STS 端點** ``` { "Statement": [ { "Action": "sts:AssumeRole", "Effect": "Allow", "Principal": { "Service": [ "lambda.amazonaws.com" ] }, "Resource": "*" } ] } ``` **Example VPC 端點政策 – Lambda 端點** ``` { "Statement": [ { "Action": "lambda:InvokeFunction", "Effect": "Allow", "Principal": { "Service": [ "lambda.amazonaws.com" ] }, "Resource": "*" } ] } ``` ## 建立事件來源映射 建立[事件來源映射](invocation-eventsourcemapping.md)，指示 Lambda 將記錄從 Amazon MQ 代理程式傳送至 Lambda 函數。您可以建立多個事件來源映射，來使用多個函數處理相同資料，或使用單一函數處理來自多個來源的項目。 若要設定您的函數以從 Amazon MQ 讀取，請新增必要的許可，並在 Lambda 主控台中建立 **MQ** 觸發條件。 若要從 Amazon MQ 代理程式讀取記錄，您的 Lambda 函數需要將下列許可。您可以透過將許可陳述式新增至您的函數[執行角色](lambda-intro-execution-role.md)，授予 Lambda 許可，以與您的 Amazon MQ 代理程式及其基礎資源互動： + [mq:DescribeBroker](https://docs.aws.amazon.com/amazon-mq/latest/api-reference/brokers-broker-id.html#brokers-broker-id-http-methods) + [secretsmanager:GetSecretValue](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_GetSecretValue.html) + [ec2:CreateNetworkInterface](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CreateNetworkInterface.html) + [ec2:DeleteNetworkInterface](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DeleteNetworkInterface.html) + [ec2:DescribeNetworkInterfaces](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeNetworkInterfaces.html) + [ec2:DescribeSecurityGroups](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeSecurityGroups.html) + [ec2:DescribeSubnets](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeSubnets.html) + [ec2:DescribeVpcs](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeVpcs.html) + [logs:CreateLogGroup](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_CreateLogGroup.html) + [logs:CreateLogStream](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_CreateLogStream.html) + [日誌：PutLogEvents](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutLogEvents.html) **注意** 使用加密的客戶管理金鑰時，也請新增 `[kms:Decrypt](https://docs.aws.amazon.com/msk/1.0/apireference/clusters-clusterarn-bootstrap-brokers.html#clusters-clusterarn-bootstrap-brokersget)` 許可。 **若要新增許可並建立觸發條件** 1. 開啟 Lambda 主控台中的 [函數頁面](https://console.aws.amazon.com/lambda/home#/functions)。 1. 選擇函數的名稱。 1. 依序選擇 **Configuration** (組態) 索引標籤和 **Permissions** (許可)。 1. 在**角色名稱**下面，選擇執行角色連結。此連結會在 IAM 主控台中開啟該角色。 ![\[\]](http://docs.aws.amazon.com/zh_tw/lambda/latest/dg/images/execution-role.png) 1. 選擇**新增許可**，然後選擇**建立內嵌政策**。 ![\[\]](http://docs.aws.amazon.com/zh_tw/lambda/latest/dg/images/inline-policy.png) 1. 在**政策編輯器**中，選擇 **JSON**。輸入下列政策。您的函數需要這些許可才能從 Amazon MQ 代理程式讀取。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "mq:DescribeBroker", "secretsmanager:GetSecretValue", "ec2:CreateNetworkInterface", "ec2:DeleteNetworkInterface", "ec2:DescribeNetworkInterfaces", "ec2:DescribeSecurityGroups", "ec2:DescribeSubnets", "ec2:DescribeVpcs", "logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents" ], "Resource": "*" } ] } ``` ------ **注意** 使用加密的客戶管理金鑰時，還必須新增 `kms:Decrypt` 許可。 1. 選擇**下一步**。輸入政策名稱，然後選擇**建立政策**。 1. 在 Lambda 主控台中返回您的 Lambda 函數。在**函數概觀**下，選擇**新增觸發條件**。 ![\[\]](http://docs.aws.amazon.com/zh_tw/lambda/latest/dg/images/add-trigger.png) 1. 選擇 **MQ** 觸發條件類型。 1. 設定需要的選項，然後選擇**新增**。 Lambda 支援 Amazon MQ 事件來源的下列選項： + **MQ broker (MQ 代理程式)** – 選取 Amazon MQ 代理程式。 + **Batch size (批次大小)** - 設定單一批次中要擷取的訊息數目上限。 + **Queue name (佇列名稱)** - 輸入要取用的 Amazon MQ 佇列。 + **Source access configuration (來源存取組態)** - 輸入儲存您代理程式憑證的虛擬主機資訊和 Secrets Manager 機密。 + **Enable trigger (啟用觸發條件)** - 停用觸發條件以停止處理記錄。 若要啟用或停用觸發條件 (或將其刪除)，請在設計工具中選擇 **MQ** 觸發條件。若要重新設定觸發條件，請使用事件來源映射 API 操作。 # 事件來源映射參數 所有 Lambda 事件來源類型都會共用相同的 [CreateEventSourceMapping](https://docs.aws.amazon.com/lambda/latest/api/API_CreateEventSourceMapping.html) 和 [UpdateEventSourceMapping](https://docs.aws.amazon.com/lambda/latest/api/API_UpdateEventSourceMapping.html) API 操作。但是，只有一些參數適用於 Amazon MQ 和 RabbitMQ。 | 參數 | 必要 | 預設 | 備註 | | --- | --- | --- | --- | | BatchSize | 否 | 100 | 上限：10,000 | | 已啟用 | N | true | 無 | | FunctionName | 是 | N/A | 無 | | FilterCriteria | N | N/A | [控制 Lambda 將哪些事件傳送至您的函數](invocation-eventfiltering.md) | | MaximumBatchingWindowInSeconds | N | 500 毫秒 | [批次處理行為](invocation-eventsourcemapping.md#invocation-eventsourcemapping-batching) | | 佇列 | N | N/A | 要使用的 Amazon MQ 代理程式目的地佇列的名稱。 | | SourceAccessConfigurations | N | N/A | 若為 ActiveMQ，可使用 BASIC\$1AUTH 憑證。若為 RabbitMQ，可同時包含 BASIC\$1AUTH 憑證和 VIRTUAL\$1HOST 資訊。 | # 從 Amazon MQ 事件來源篩選事件 您可以使用事件篩選來控制 Lambda 將哪些記錄從串流或佇列中傳送至函數。如需事件篩選運作方式的一般資訊，請參閱[控制 Lambda 將哪些事件傳送至您的函數](invocation-eventfiltering.md)。 本節重點介紹 Amazon MQ 事件來源的事件篩選。 **注意** Amazon MQ 事件來源映射僅支援依據 `data` 鍵進行篩選。 **Topics** + [Amazon MQ 事件篩選基本概念](#filtering-AMQ) ## Amazon MQ 事件篩選基本概念 假設您的 Amazon MQ 訊息佇列包含有效 JSON 格式或純字串的訊息。範例記錄如下所示，資料在 `data` 欄位中會轉換為 Base64 編碼字串。 ------ #### [ ActiveMQ ] ``` { "messageID": "ID:b-9bcfa592-423a-4942-879d-eb284b418fc8-1---mq---us-east-2.amazonaws.com.rproxy.goskope.com-37557-1234520418293-4:1:1:1:1", "messageType": "jms/text-message", "deliveryMode": 1, "replyTo": null, "type": null, "expiration": "60000", "priority": 1, "correlationId": "myJMSCoID", "redelivered": false, "destination": { "physicalName": "testQueue" }, "data":"QUJDOkFBQUE=", "timestamp": 1598827811958, "brokerInTime": 1598827811958, "brokerOutTime": 1598827811959, "properties": { "index": "1", "doAlarm": "false", "myCustomProperty": "value" } } ``` ------ #### [ RabbitMQ ] ``` { "basicProperties": { "contentType": "text/plain", "contentEncoding": null, "headers": { "header1": { "bytes": [ 118, 97, 108, 117, 101, 49 ] }, "header2": { "bytes": [ 118, 97, 108, 117, 101, 50 ] }, "numberInHeader": 10 }, "deliveryMode": 1, "priority": 34, "correlationId": null, "replyTo": null, "expiration": "60000", "messageId": null, "timestamp": "Jan 1, 1970, 12:33:41 AM", "type": null, "userId": "AIDACKCEVSQ6C2EXAMPLE", "appId": null, "clusterId": null, "bodySize": 80 }, "redelivered": false, "data": "eyJ0aW1lb3V0IjowLCJkYXRhIjoiQ1pybWYwR3c4T3Y0YnFMUXhENEUifQ==" } ``` ------ 對於 Active MQ 和 Rabbit MQ 代理程式，您可以使用事件篩選透過 `data` 索引鍵來篩選記錄。假設您的 Amazon MQ 佇列包含以下 JSON 格式的訊息。 ``` { "timeout": 0, "IPAddress": "203.0.113.254" } ``` 若要僅篩選 `timeout` 欄位大於 0 的記錄，`FilterCriteria` 物件將如下所示。 ``` { "Filters": [ { "Pattern": "{ \"data\" : { \"timeout\" : [ { \"numeric\": [ \">\", 0] } } ] } }" } ] } ``` 補充說明，此處是篩選條件的 `Pattern` 在純文字 JSON 中擴展的值。 ``` { "data": { "timeout": [ { "numeric": [ ">", 0 ] } ] } } ``` 您可以使用主控台、AWS CLI 或 AWS SAM 範本新增篩選條件。 ------ #### [ Console ] 若要使用主控台新增此篩選條件，請遵循 [將篩選條件標準連接至事件來源映射 (主控台)](invocation-eventfiltering.md#filtering-console) 中的指示，並針對**篩選條件標準**輸入下列字串。 ``` { "data" : { "timeout" : [ { "numeric": [ ">", 0 ] } ] } } ``` ------ #### [ AWS CLI ] 若要使用 AWS Command Line Interface (AWS CLI) 來建立具有這些篩選條件標準的新事件來源映射，請執行下列命令。 ``` aws lambda create-event-source-mapping \ --function-name my-function \ --event-source-arn arn:aws:mq:us-east-2:123456789012:broker:my-broker:b-8ac7cc01-5898-482d-be2f-a6b596050ea8 \ --filter-criteria '{"Filters": [{"Pattern": "{ \"data\" : { \"timeout\" : [ { \"numeric\": [ \">\", 0 ] } ] } }"}]}' ``` 若要將這些篩選條件標準新增到現有事件來源映射，請執行下列命令。 ``` aws lambda update-event-source-mapping \ --uuid "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE" \ --filter-criteria '{"Filters": [{"Pattern": "{ \"data\" : { \"timeout\" : [ { \"numeric\": [ \">\", 0 ] } ] } }"}]}' ``` 若要將這些篩選條件標準新增到現有事件來源映射，請執行下列命令。 ``` aws lambda update-event-source-mapping \ --uuid "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE" \ --filter-criteria '{"Filters": [{"Pattern": "{ \"data\" : { \"timeout\" : [ { \"numeric\": [ \">\", 0 ] } ] } }"}]}' ``` ------ #### [ AWS SAM ] 若要使用 AWS SAM 新增此篩選條件，請將下列程式碼片段新增到事件來源的 YAML 範本。 ``` FilterCriteria: Filters: - Pattern: '{ "data" : { "timeout" : [ { "numeric": [ ">", 0 ] } ] } }' ``` ------ 使用 Amazon MQ，您也可以篩選訊息為純字串的記錄。假設您只想處理訊息以「結果：」開頭的記錄。`FilterCriteria` 物件如下所示。 ``` { "Filters": [ { "Pattern": "{ \"data\" : [ { \"prefix\": \"Result: \" } ] }" } ] } ``` 補充說明，此處是篩選條件的 `Pattern` 在純文字 JSON 中擴展的值。 ``` { "data": [ { "prefix": "Result: " } ] } ``` 您可以使用主控台、AWS CLI 或 AWS SAM 範本新增篩選條件。 ------ #### [ Console ] 若要使用主控台新增此篩選條件，請遵循 [將篩選條件標準連接至事件來源映射 (主控台)](invocation-eventfiltering.md#filtering-console) 中的指示，並針對**篩選條件標準**輸入下列字串。 ``` { "data" : [ { "prefix": "Result: " } ] } ``` ------ #### [ AWS CLI ] 若要使用 AWS Command Line Interface (AWS CLI) 來建立具有這些篩選條件標準的新事件來源映射，請執行下列命令。 ``` aws lambda create-event-source-mapping \ --function-name my-function \ --event-source-arn arn:aws:mq:us-east-2:123456789012:broker:my-broker:b-8ac7cc01-5898-482d-be2f-a6b596050ea8 \ --filter-criteria '{"Filters": [{"Pattern": "{ \"data\" : [ { \"prefix\": \"Result: \" } ] }"}]}' ``` 若要將這些篩選條件標準新增到現有事件來源映射，請執行下列命令。 ``` aws lambda update-event-source-mapping \ --uuid "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE" \ --filter-criteria '{"Filters": [{"Pattern": "{ \"data\" : [ { \"prefix\": \"Result: \" } ] }"}]}' ``` ------ #### [ AWS SAM ] 若要使用 AWS SAM 新增此篩選條件，請將下列程式碼片段新增到事件來源的 YAML 範本。 ``` FilterCriteria: Filters: - Pattern: '{ "data" : [ { "prefix": "Result " } ] }' ``` ------ Amazon MQ 訊息必須是 UTF-8 編碼的字串，可以是純字串或 JSON 格式。這是因為 Lambda 會在套用篩選條件之前，將 Amazon MQ 位元組陣列解碼成 UTF-8。如果您的訊息使用其他編碼方式 (例如 UTF-16 或 ASCII)，或者訊息格式與 `FilterCriteria` 格式不相符，則 Lambda 只會處理中繼資料篩選條件。下表摘要說明特定行為： | 傳入訊息 格式 | 訊息屬性的篩選條件模式格式 | 產生的動作 | | --- | --- | --- | | 純文字的字串 | 純文字的字串 | 根據您的篩選條件標準之 Lambda 篩選條件。 | | 純文字的字串 | 資料屬性沒有篩選條件模式 | Lambda 篩選條件 (僅限其他中繼資料屬性) 會根據您的篩選條件標準而定。 | | 純文字的字串 | 有效的 JSON | Lambda 篩選條件 (僅限其他中繼資料屬性) 會根據您的篩選條件標準而定。 | | 有效的 JSON | 純文字的字串 | Lambda 篩選條件 (僅限其他中繼資料屬性) 會根據您的篩選條件標準而定。 | | 有效的 JSON | 資料屬性沒有篩選條件模式 | Lambda 篩選條件 (僅限其他中繼資料屬性) 會根據您的篩選條件標準而定。 | | 有效的 JSON | 有效的 JSON | 根據您的篩選條件標準之 Lambda 篩選條件。 | | 非 UTF-8 編碼字串 | JSON、純字串或沒有模式 | Lambda 篩選條件 (僅限其他中繼資料屬性) 會根據您的篩選條件標準而定。 | # 對 Amazon MQ 事件來源映射錯誤進行疑難排解 當 Lambda 函數遇到無法復原的錯誤時，您的 Amazon MQ 取用者將停止處理記錄。任何其他取用者可能會繼續處理，只要他們沒有遇到相同的錯誤。若要判斷停止 `StateTransitionReason` 取用者的潛在原因，請檢查傳回詳細資料中的 `EventSourceMapping` 欄位，以取得下列其中一個程式碼： **`ESM_CONFIG_NOT_VALID`** 事件來源對應組態無效。 **`EVENT_SOURCE_AUTHN_ERROR`** Lambda 驗證事件來源失敗。 **`EVENT_SOURCE_AUTHZ_ERROR`** Lambda 沒有存取事件來源所需的許可。 **`FUNCTION_CONFIG_NOT_VALID`** 該函數的配置無效。 如果記錄因大小而遭 Lambda 棄置，則也將不會得到處理。Lambda 記錄的大小限制為 6MB。若要在函數錯誤時重新傳遞訊息，您可以使用無效字母佇列 (DLQ)。如需詳細資訊，請參閱 Apache ActiveMQ 網站上的[訊息重新傳遞和 DLQ 處理](https://activemq.apache.org/message-redelivery-and-dlq-handling)，以及 RabbitMQ 網站上的[可靠性指南](https://www.rabbitmq.com/reliability.html)。 **注意** Lambda 不支援自訂重新傳遞政策，相反，Lambda 會使用具有來自 Apache ActiveMQ 網站[重新傳遞政策](https://activemq.apache.org/redelivery-policy)頁面中之預設值的政策，並將 `maximumRedeliveries` 設定為 6。