擷取 Lambda 非同步調用的記錄 - AWS Lambda
目的地無效字母佇列

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

擷取 Lambda 非同步調用的記錄

Lambda 可以將非同步調用的記錄傳送到下列其中一項 AWS 服務。

  • Amazon SQS：標準 SQS 佇列

  • Amazon SNS：標準 SNS 主題

  • Amazon S3：Amazon S3 儲存貯體 (僅限失敗時)

  • AWS Lambda：Lambda 函數

  • Amazon EventBridge：EventBridge 事件匯流排

呼叫記錄包含請求和回應 (JSON 格式) 的詳細資訊。您可以為成功處理的事件及所有處理嘗試皆失敗的事件設定個別目標。或者，您可以將標準 Amazon SQS 佇列或標準 Amazon SNS 主題設為捨棄事件的無效字母佇列。針對無效字母佇列，Lambda 只會傳送事件的內容，而不包含回應的詳細資訊。

如果 Lambda 無法將記錄傳送到您設定的目的地，便會將 DestinationDeliveryFailures 指標傳送至 Amazon CloudWatch。如果您的組態中包含不受支援的目的地類型 (例如 Amazon SQS FIFO 佇列或 Amazon SNS FIFO 主題)，就可能發生這種情形。傳遞錯誤也可能因許可錯誤和大小限制而發生。如需 Lambda 調用指標的詳細資訊，請參閱：呼叫指標

注意

為了防止函數觸發，您可以將函數的預留並行設為零。當您將非同步調用函數的預留並行設定為零時，Lambda 會開始將新事件傳送至設定的無效字母佇列或失敗時的事件目的地，不會進行任何重試。若要處理在預留並行設定為零時傳送的事件，您必須使用來自無效字母佇列或失敗時的事件目的地之事件。

新增目的地

若要保留非同步調用的記錄，請將目的地新增至您的函數。您可以選擇將成功或失敗的調用傳送至目的地。每個函數都可以有多個目的地，因此您可以為成功和失敗的事件配置單獨的目的地。傳送至目的地的每筆記錄都是包含調用之詳細資訊的 JSON 文件。與錯誤處理設定相似，您可以設定函數、函數版本或是別名的目標。

提示

您也可以保留以下事件來源映射類型的調用失敗記錄：Amazon Kinesis、Amazon DynamoDB、自我管理 Apache Kafka 和 Amazon MSK。

以下資料表列出針對非同步調用記錄支援的目的地。若要讓 Lambda 成功將記錄傳送至您選擇的目的地，請確定函數的執行角色也包含相關許可。此資料表也說明每個目的地類型如何接收 JSON 調用記錄。

目的地類型 所需的許可 目的地特定 JSON 格式

Amazon SQS 佇列

sqs:SendMessage

Lambda 會將調用記錄做為 Message 傳遞至目的地。

Amazon SNS 主題

sns:Publish

Lambda 會將調用記錄做為 Message 傳遞至目的地。

Amazon S3 儲存貯體 (僅限失敗時)

s3:PutObject

s3:ListBucket

  • Lambda 會以 JSON 物件的形式在目的地儲存貯體中儲存調用記錄。

  • S3 物件使用以下命名慣例：

    aws/lambda/async/<function-name>/YYYY/MM/DD/YYYY-MM-DDTHH.MM.SS-<Random UUID>

Lambda 函數

lambda:InvokeFunction

Lambda 傳遞調用記錄會以承載形式傳遞給函數。

EventBridge

events:PutEvents

  • Lambda 會在 PutEvents 呼叫中以 detail 形式來傳遞調用記錄。

  • source 事件欄位的值是 lambda。

  • detail-type 事件欄位的值是 Lambda Function Invocation Result - Success (Lambda 函數調用結果 - 成功) 或 Lambda Function Invocation Result - Failure (Lambda 函數調用結果 - 失敗)。

  • resource 事件欄位包含函數和目的地 Amazon Resource Names (ARN)。

  • 如需其他事件欄位，請參閱 Amazon EventBridge 事件。
注意

對於 Amazon S3 目的地，如果您已使用 KMS 金鑰在相應儲存貯體上啟用加密，則函數也需要 kms:GenerateDataKey 許可。

下列步驟說明如何使用 Lambda 主控台和 來設定函數的目的地 AWS CLI。

Console

  1. 開啟 Lambda 主控台中的 函數頁面。

  2. 選擇一個函數。

  3. 在函數概觀下，選擇新增目的地。

  4. 針對來源，選擇非同步調用。

  5. 如為條件，請從下列選項中選擇：

    • On failure (失敗時) - 當事件的所有處理嘗試都失敗，或超過存留期上限時，傳送記錄。

    • 成功時 - 當函數成功處理非同步調用時傳送記錄。

  6. 對於目的地類型，請選擇接收調用記錄的資源類型。

  7. 對於目的地，請選擇一個資源。

  8. 選擇 Save (儲存)。

AWS CLI

若要使用 設定目的地 AWS CLI，請執行 update-function-event-invoke-config 命令。下列範例會將 Lambda 設定為在無法處理事件時，將記錄傳送至名為 destination 的標準 SQS 佇列。

aws lambda update-function-event-invoke-config \
  --function-name my-function \
  --destination-config '{"OnFailure":{"Destination": "arn:aws:sqs:us-east-1:123456789012:destination"}}'

Amazon S3 目的地的安全最佳實務

刪除已設定為目的地的 S3 儲存貯體而不從函數的組態中移除目的地，可能會產生安全風險。如果其他使用者知道目的地儲存貯體的名稱，他們可以在其 AWS 帳戶中重新建立儲存貯體。失敗調用的記錄會被傳送到其儲存貯體，可能公開來自您函數的資料。

警告

為了確保無法將來自函數的調用記錄傳送到另一個 儲存貯體中的 S3 儲存貯體 AWS 帳戶，請將條件新增至函數的執行角色，以限制您帳戶中儲存貯體的s3:PutObject許可。

下列範例顯示的 IAM 政策，將函數的 s3:PutObject 許可限制為帳戶中的儲存貯體。此政策也為 Lambda 提供了使用 S3 儲存貯體做為目的地所需的 s3:ListBucket 許可。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "S3BucketResourceAccountWrite",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:ListBucket"
            ],
            "Resource": "arn:aws:s3:::*/*",
            "Condition": {
                "StringEquals": {
                    "s3:ResourceAccount": "111122223333"
                }
            }
        }
    ]
}

若要使用 AWS Management Console 或 將許可政策新增至您 funcion 的執行角色 AWS CLI，請參閱下列程序的說明：

Console
若要將許可政策新增至函數的執行角色 (主控台)

  1. 開啟 Lambda 主控台中的函數頁面。

  2. 選取您要修改其執行角色的 Lambda 函數。

  3. 在組態索引標籤中，選擇許可。

  4. 在執行角色索引標籤中，選取函數的角色名稱，以開啟角色的 IAM 主控台頁面。

  5. 透過下列步驟將許可政策新增至角色：

    1. 在許可政策窗格中，選擇新增許可 ，然後選取建立內嵌政策。

    2. 在政策編輯器中，選取 JSON。

    3. 將您要新增的政策貼入編輯器 (取代現有的 JSON)，然後選擇下一步。

    4. 在政策詳細資訊下，輸入政策名稱。

    5. 選擇 建立政策。

AWS CLI
若要將許可政策新增至函數的執行角色 (CLI)

  1. 建立具有所需許可的 JSON 政策文件，並將其儲存在本機目錄中。

  2. 使用 IAM put-role-policy CLI 命令，將許可新增至函數的執行角色。從您儲存 JSON 政策文件的目錄執行下列命令，並將角色名稱、政策名稱和政策文件取代為您自己的值。

    aws iam put-role-policy \
--role-name my_lambda_role \
--policy-name LambdaS3DestinationPolicy \
--policy-document file://my_policy.json

調用記錄範例

當調用與條件相符時，Lambda 會將包含調用之詳細資訊的 JSON 文件傳送到目的地。下列範例顯示因函式錯誤而導致處理失敗三次事件的呼叫記錄。

{
    "version": "1.0",
    "timestamp": "2019-11-14T18:16:05.568Z",
    "requestContext": {
        "requestId": "e4b46cbf-b738-xmpl-8880-a18cdf61200e",
        "functionArn": "arn:aws:lambda:us-east-1:123456789012:function:my-function:$LATEST",
        "condition": "RetriesExhausted",
        "approximateInvokeCount": 3
    },
    "requestPayload": {
        "ORDER_IDS": [
            "9e07af03-ce31-4ff3-xmpl-36dce652cb4f",
            "637de236-e7b2-464e-xmpl-baf57f86bb53",
            "a81ddca6-2c35-45c7-xmpl-c3a03a31ed15"
        ]
    },
    "responseContext": {
        "statusCode": 200,
        "executedVersion": "$LATEST",
        "functionError": "Unhandled"
    },
    "responsePayload": {
        "errorMessage": "RequestId: e4b46cbf-b738-xmpl-8880-a18cdf61200e Process exited before completing request"
    }
}

呼叫記錄包含事件、回應以及記錄傳送原因的詳細資訊。

追蹤傳至目的地的請求

您可以使用 AWS X-Ray 查看每個請求排入佇列、由 Lambda 函數處理並傳遞至目的地服務的連接檢視。為調用函數的函數或服務啟用 X-Ray 追蹤時，Lambda 會將 X-Ray 標頭新增至請求，並將標頭傳送至目的地服務。來自上游服務的追蹤會自動連結至來自下游 Lambda 函數和目的地服務的追蹤，進而建立整個應用程式的端對端檢視。如需追蹤的詳細資訊，請參閱：使用 視覺化 Lambda 函數叫用 AWS X-Ray。

新增無效字母佇列

做為失敗目標的替代項目，您可以設定您的函數，使其具備一個無效字母佇列來儲存捨棄的事件，以供後續處理。無效字母佇列的運作方式與失敗目標相同，會在事件的所有處理嘗試失敗，或是在沒有處理的情況下過期時使用。不過，您只能在函數層級新增或移除無效字母佇列。函數版本使用與未發布版本 ($LATEST) 相同的無效字母佇列設定。失敗目標也支援其他目標，並會在呼叫記錄中包含函數回應的詳細資訊。

若要重新處理無效字母佇列中的事件，請將它設定為 Lambda 函數的事件來源。或者，您可以手動擷取事件。

您可以為無效字母佇列選擇 Amazon SQS 標準佇列或 Amazon SNS 標準主題。不支援 SQS FIFO 佇列和 Amazon SNS FIFO 主題。

  • Amazon SQS 佇列 - 佇列會保留失敗的事件，直到其遭到擷取為止。如果您希望單一實體 (例如 Lambda 函數或 CloudWatch 警示) 處理失敗的事件，請選擇 Amazon SQS 標準佇列。如需詳細資訊，請參閱搭配 Amazon SQS 使用 Lambda。

  • Amazon SNS 主題 - 主題會將失敗的事件轉送到一個或多個目的地。如果您希望多個實體對失敗的事件採取動作，請選擇 Amazon SNS 標準主題。例如，您可以設定一個主題，以將事件傳送到電子郵件地址、Lambda 函數及/或 HTTP 端點。如需詳細資訊，請參閱使用 Amazon SNS 通知調用 Lambda 函數。

若要將事件傳送到佇列或主題，您的函式需要額外許可。將具有所需許可的政策新增到您函數的執行角色。如果使用客戶受管 AWS KMS 金鑰加密目標佇列或主題，請確定您函數的執行角色和金鑰的資源型政策都包含相關的許可。

在建立目標及更新函式的執行角色之後，將無效字母佇列新增到您的函式。您可以設定多個函式來將事件傳送到相同的目標。

Console

  1. 開啟 Lambda 主控台中的 函數頁面。

  2. 選擇一個函數。

  3. 選擇組態，然後選擇非同步調用。

  4. 在非同步調用下方，選擇編輯。

  5. 將無效字母佇列服務設定為 Amazon SQS 或 Amazon SNS。

  6. 選擇目標佇列或主題。

  7. 選擇 Save (儲存)。

AWS CLI

若要使用 設定無效字母佇列 AWS CLI，請使用 update-function-configuration 命令。

aws lambda update-function-configuration \
  --function-name my-function \
  --dead-letter-config TargetArn=arn:aws:sns:us-east-1:123456789012:my-topic

Lambda 會依現狀將事件傳送到無效字母佇列，其屬性中有額外資訊。您可以使用此資訊來識別該函式所傳回的錯誤，或建立事件與日誌或 AWS X-Ray 追蹤的關聯性。

無效字母佇列訊息屬性

  • RequestID (字串) - 調用請求的 ID。請求 ID 會出現於函式日誌中。您也可以使用 X-Ray SDK 在追蹤的屬性中記錄請求 ID。然後，您可以在 X-Ray 主控台中依請求 ID 搜尋追蹤。

  • ErrorCode (數字) - HTTP 狀態碼。

  • ErrorMessage (字串) - 第 1 KB 的錯誤訊息。

如果 Lambda 無法將訊息傳送到無效字母佇列，則會刪除事件並發出 DeadLetterErrors 指標。這可能由於缺乏許可，或訊息總大小超過目標佇列或主題的限制，而發生此狀況。例如，假設本文大小接近 256 KB 的 Amazon SNS 通知會觸發導致錯誤的函數。在這種情況下，Amazon SNS 新增的事件資料與 Lambda 新增的屬性結合後，可能導致訊息超過無效字母佇列中允許的大小上限。

如果您使用 Amazon SQS 作為事件來源，請對 Amazon SQS 佇列本身 (而非 Lambda 函數) 設定無效字母佇列。如需詳細資訊，請參閱搭配 Amazon SQS 使用 Lambda。