使用 Lambda 擴充功能建API立擴充功能 - AWS Lambda

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

使用 Lambda 擴充功能建API立擴充功能

Lambda 函數作者使用延伸項目將 Lambda 與其偏好的監控、可觀度、安全性和治理工具整合在一起。函數作者可以使用合作AWS 夥伴和開放原始碼專案的擴充功能。 AWS如需使用擴充功能的詳細資訊,請參閱 AWS Compute 部落格上的AWS Lambda 擴充功能簡介 本節說明如何使用 Lambda 擴充功能API、Lambda 執行環境生命週期和 Lambda 擴充功能API參考資料。

擴充功能API和遙測功能會API連接 Lambda 和外部擴充功能。

身為擴充功能作者,您可以使用 Lambda 擴充功能深入整合API至 Lambda 執行環境。您的延伸項目可以註冊函數和執行環境生命週期事件。為了回應這些事件,您可以啟動新程序、執行邏輯,以及控制並參與 Lambda 生命週期的所有階段:初始化、調用和關閉。此外,您可以使用執行階段記錄API來接收記錄串流。

延伸項目會在執行環境中作為獨立的處理序執行,並在完全處理函數調用之後繼續執行。由於延伸項目會以程序執行,因此您可以使用與函數不同的語言來撰寫。我們建議您使用編譯語言實作延伸項目。在這種情況下,延伸項目是獨立的二進位檔案,會與支援的執行時間相容。所有 Lambda 執行期 支援延伸。如果您使用非編譯語言,請確定您在延伸項目中包含相容的執行階段。

Lambda 也支援內部延伸項目。內部延伸項目會作為獨立執行緒在執行時間程序中執行。執行時間會啟動並停止內部延伸項目。與 Lambda 環境整合的另一種方法是使用特定語言的環境變數和包裝函數指令碼。您可使用這些來設定執行時間環境,並修改執行時間程序的啟動行為。

您可以使用兩種方法將延伸項目新增至函數。對於部署為 .zip 封存檔案的函數,您可以將延伸項目部署為 layer。對於定義為容器映像的函數,可以將延伸項目新增至容器映像。

注意

如需擴充功能和包裝函式指令碼範例,請參閱 AWS 範例 GitHub 儲存庫上的AWS Lambda 擴充

Lambda 執行環境生命週期

執行環境的生命週期包含下列階段:

  • Init:在此階段中,Lambda 會使用設定的資源建立或解除凍結執行環境,下載函數程式碼和所有層,初始化所有擴展功能,初始化執行時間,然後執行函數的初始化程式碼 (主處理常式之外的程式碼)。此 Init 階段發生在第一次調用期間,或者在函數調用之前發生 (如果您已啟用佈建並行)。

    Init 階段分為三個子階段:Extension initRuntime init 以及 Function init。這些子階段可確保所有擴展功能和執行時間在函數程式碼執行之前完成其設定任務。

  • Invoke:在此階段中,Lambda 會調用函數處理常式。函數執行完成之後,Lambda 會準備處理另一個函數調用。

  • Shutdown:如果 Lambda 函數在一段時間內未收到任何調用,就會觸發此階段。在 Shutdown 階段中,Lambda 會關閉執行時間、警示擴展功能以便它們完全停止,然後移除環境。Lambda 會傳送 Shutdown 事件到每個擴展功能,這會告訴擴展功能環境即將關閉。

每個階段都會從 Lambda 到執行時間和所有已註冊延伸項目的事件開始。運行時和每個擴展通過發送NextAPI請求信號完成。當每個處理已完成且沒有擱置的事件時,Lambda 凍結執行環境。

擴充功能使用 Lambda 執行環境

初始化階段

Extension init 階段中,每個延伸項目都需要向 Lambda 註冊才能接收事件。Lambda 會使用延伸項目的完整檔案名稱來驗證延伸項目是否已完成啟動程序。因此,每個RegisterAPI呼叫都必須包含帶有副檔名完整檔案名稱的Lambda-Extension-Name標頭。

您可以為函式最多註冊 10 個延伸項目。此限制是透過RegisterAPI呼叫強制執行。

在每個延伸項目註冊後,Lambda 會啟動 Runtime init 階段。執行時間程序會呼叫 functionInit 以啟動 Function init 階段。

階段在執行Init階段之後完成,每個已註冊的擴充功能都會透過傳送NextAPI要求來指示完成

注意

延伸項目可以在 Init 階段的任何時候完成初始化。

Lambda 初始化階段中的事件順序

調用階段

當呼叫 Lambda 函數以回應NextAPI請求時,Lambda 會將Invoke事件傳送至執行階段,以及為該Invoke事件註冊的每個擴充功能。

在調用期間,外部延伸項目會與函式平行執行。函式完成後,它們也會繼續執行。這可讓您擷取診斷資訊,或將日誌、指標和追蹤傳送至您選擇的位置。

從執行時間中收到函數回應之後,即使延伸項目仍在執行中,Lambda 也會將回應傳回給用戶端。

Invoke階段在運行時結束後結束,所有擴展都通過發送NextAPI請求來表示它們完成。

Lambda 叫用階段中的事件順序

每個承載︰傳送到執行時間 (和 Lambda 函數) 的事件載有整個請求、標頭 (例如 RequestId) 和承載。傳送至每個延伸項目的事件會包含描述事件內容的中繼資料。此生命週期事件包括事件的類型、函數逾時的時間 (deadlineMs)、叫用函數的 Amazon 資源名稱 (ARN) 和追蹤標頭。requestId

想要存取函數事件主體的擴充功能可以使用與擴充功能進行通訊SDK的執行階段。函數開發人員會在叫用函數時,使用執行階段SDK將裝載傳送至擴充功能。

以下是承載範例:

{ "eventType": "INVOKE", "deadlineMs": 676051, "requestId": "3da1f2dc-3222-475e-9205-e2e6c6318895", "invokedFunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:ExtensionTest", "tracing": { "type": "X-Amzn-Trace-Id", "value": "Root=1-5f35ae12-0c0fec141ab77a00bc047aa2;Parent=2be948a625588e32;Sampled=1" } }

持續時間限制:該函數的逾時設置限制了整個 Invoke 階段的持續時間。例如,如果您將函式逾時設定為 360 秒,則函式和所有延伸項目都需要在 360 秒內完成。請注意,沒有獨立的調用後階段。持續時間是執行階段和所有擴充功能呼叫完成所需的總時間,直到函數和所有擴充功能完成執行之後才會計算。

效能影響和延伸項目負擔:延伸項目可能會影響函式效能。身為延伸項目的作者,您可以控制延伸項目的效能影響。例如,如果您的擴充功能執行運算密集型作業,則函式的持續時間會增加,因為擴充功能和函數程式碼共用相同CPU的資源。此外,如果您的延伸項目在函式調用完成後執行大量作業,函式的持續時間就會增加,因為 Invoke 階段會持續進行,直到所有延伸項目表示它們已完成為止。

注意

Lambda 按照函數的記憶體設定成比例分配功CPU率。您可能會在較低的記憶體設定下看到執行和初始化持續時間增加,因為函數和擴充程序正在競爭相同的CPU資源。若要減少執行和初始化持續時間,請嘗試增加記憶體設定。

為了協助識別延伸在 Invoke 階段上造成的效能衝擊,Lambda 會輸出 PostRuntimeExtensionsDuration 指標。此測量結果會測量執行階段NextAPI要求與上次延伸NextAPI要求之間花費的累計時間。若要測量使用的記憶體增加的情況,請使用 MaxMemoryUsed 指標。如需函式指標的詳細資訊,請參閱檢視 Lambda 函數的指標

函式開發人員可以並排執行不同版本的函式,以了解特定延伸項目的影響。我們建議延伸項目作者發佈預期的資源消耗,以便函式開發人員更容易選擇合適的延伸項目。

關閉階段

當 Lambda 即將關閉執行時間,它會將 Shutdown 事件傳送至每個已註冊外部延伸。延伸項目可以使用此時間進行最終清理工作。該Shutdown事件是為了響應請NextAPI求而發送。

持續時間限制Shutdown 階段的最長持續時間視已註冊延伸項目的組態而定:

  • 0 毫秒 - 沒有註冊延伸的函數

  • 500 毫秒 - 具有已註冊內部延伸項目的函數

  • 2,000 毫秒 - 具有一個或多個已註冊外部延伸項目的函數

對於具有外部延伸項目的函數,Lambda 會保留最多 300 毫秒 (具有內部延伸項目的執行時間 500 毫秒),以便執行時間程序執行正常關閉。Lambda 會分配 2000 毫秒限制的其餘部分,以關閉外部延伸項目。

如果執行時間或延伸項目未在限制內回應 Shutdown 事件,Lambda 會使用 SIGKILL 訊號結束程序。

Lambda 關閉階段中的事件順序

事件承載Shutdown 事件會包含關閉的原因和剩餘時間 (以毫秒為單位)。

shutdownReason 包含以下值:

  • SPINDOWN— 正常關機

  • TIMEOUT— 持續時間限制超時

  • FAILURE— 錯誤狀況,例如out-of-memory事件

{ "eventType": "SHUTDOWN", "shutdownReason": "reason for shutdown", "deadlineMs": "the time and date that the function times out in Unix time milliseconds" }

許可與組態

延伸項目會在與 Lambda 函數相同的執行環境中執行。擴充功能也會與該功能共用資源,例如CPU記憶體和/tmp磁碟儲存空間。此外,擴充功能會使用與函數相同的 AWS Identity and Access Management (IAM) 角色和安全性內容。

檔案系統和網路存取許可:延伸項目在與函式執行階段相同的檔案系統和網路名稱命名空間中執行。這表示延伸項目必須與相關的作業系統相容。如果延伸項目需要任何其他傳出網路流量規則,您必須將這些規則套用至函數組態。

注意

由於函式程式碼目錄是唯讀的目錄,因此延伸項目無法修改函式程式碼。

環境變數:延伸項目可以存取函式的環境變數,但下列特定於執行階段程序的變數除外:

  • AWS_EXECUTION_ENV

  • AWS_LAMBDA_LOG_GROUP_NAME

  • AWS_LAMBDA_LOG_STREAM_NAME

  • AWS_XRAY_CONTEXT_MISSING

  • AWS_XRAY_DAEMON_ADDRESS

  • LAMBDA_RUNTIME_DIR

  • LAMBDA_TASK_ROOT

  • _AWS_XRAY_DAEMON_ADDRESS

  • _AWS_XRAY_DAEMON_PORT

  • _HANDLER

失敗處理

初始化失敗:如果延伸失敗,Lambda 會重新啟動執行環境以強制執行一致的行為,並促進延伸項目快速失敗。此外,對於某些客戶,延伸項目必須符合任務關鍵需求,例如日誌、安全性、治理和遙測收集。

調用失敗 (例如記憶體不足、函式逾時):因為延伸項目程序與執行時間共享資源,所以記憶體耗盡會對其產生影響。當執行階段失敗時,所有延伸項目和執行階段本身都會參與此 Shutdown 階段。此外,執行時間會自動重新啟動,這可能是為了要做為目前調用的一部分,或是透過延遲的重新初始化機制重新啟動。

如果在 Invoke 期間發生失敗 (例如函數逾時或執行時間錯誤),則 Lambda 服務會執行重設。重設的行為會與 Shutdown 事件一樣。首先,Lambda 關閉執行時間,然後將 Shutdown 事件傳送給每個已註冊外部延伸項目。事件會包括關閉的原因。如果將此環境用於新的調用,延伸項目和執行階段會重新初始化為下次調用的一部分。

執行環境範例:初始化、呼叫、以錯誤呼叫、呼叫、關閉

如需上圖更為詳細的說明,請參閱 調用階段期間出現的故障

擴充功能記錄:Lambda 會將擴充功能的記錄輸出傳送至 CloudWatch 記錄。Lambda 也會在 Init 期間為每個延伸項目產生額外的日誌事件。日誌事件會記錄成功時的名稱和註冊偏好設定 (事件、設定),或失敗時的失敗原因。

故障排除延伸項目

  • 如果Register要求失敗,請確定RegisterAPI呼叫中的Lambda-Extension-Name標頭包含副檔名的完整檔案名稱。

  • 如果內部延伸項目的 Register 請求失敗,請確定請求不會註冊 Shutdown 事件。

擴展API參考

您可以在此處找到擴充功能的開放API規格 2020-01-01 API 版本:extensions-api.zip

您可以從AWS_LAMBDA_RUNTIME_API環境變數擷取API端點的值。要發送Register請求,請2020-01-01/在每個API路徑之前使用前綴。例如:

http://${AWS_LAMBDA_RUNTIME_API}/2020-01-01/extension/register

登錄

Extension init 階段中,所有延伸項目都需要向 Lambda 註冊才能接收事件。Lambda 會使用延伸項目的完整檔案名稱來驗證延伸項目是否已完成啟動程序。因此,每個RegisterAPI呼叫都必須包含帶有副檔名完整檔案名稱的Lambda-Extension-Name標頭。

執行階段程序會啟動和停止內部延伸項目,因此不允許它們註冊 Shutdown 事件。

路徑/extension/register

方法POST

請求標頭

  • Lambda-Extension-Name - 延伸項目的完整檔案名稱。必要:是。類型:字串

  • Lambda-Extension-Accept-Feature - 用來在註冊期間指定選用的延伸項目特色。必要:否。類型:逗號分隔的字串。可使用此設定來指定的特色:

    • accountId - 如果指定此項,延伸項目註冊回應將包含與待註冊延伸項目之 Lambda 函數相關聯的帳戶 ID。

請求內文參數
  • events - 要註冊的事件陣列。必要:否。類型:字串陣列。有效字串:INVOKESHUTDOWN

回應標頭
  • Lambda-Extension-Identifier— 產生所有後續要求所需的唯一代理程式識別碼 (UUID字串)。

回應代碼
  • 200 - 回應主體包含的函數名稱、函數版本和處理常式名稱。

  • 400 - 錯誤請求

  • 403 - 禁止

  • 500 - 容器錯誤。不可復原的狀態。延伸項目應會立即結束。

範例請求主體
{ 'events': [ 'INVOKE', 'SHUTDOWN'] }
範例回應主題
{ "functionName": "helloWorld", "functionVersion": "$LATEST", "handler": "lambda_function.lambda_handler" }
範例 具有可選 accountId 特徵的示例響應主體
{ "functionName": "helloWorld", "functionVersion": "$LATEST", "handler": "lambda_function.lambda_handler", "accountId": "123456789012" }

下一頁

擴充功能會傳送NextAPI要求以接收下一個事件 (可以是Invoke事件或Shutdown事件)。回應主體包含有效負載,這是包含事JSON件資料的文件。

擴展程序發送一個NextAPI請求,表示它已準備好接收新事件。這是一個封鎖調用。

請勿在GET呼叫上設定逾時,因為擴充功能可暫停一段時間,直到有要傳回的事件為止。

路徑/extension/event/next

方法GET

請求標頭
  • Lambda-Extension-Identifier— 副檔名的唯一識別碼 (UUID字串)。必要:是。類型:UUID字符串。

回應標頭
  • Lambda-Extension-Event-Identifier— 事件的唯一識別元 (UUID字串)。

回應代碼
  • 200 - 回應包含下個事件 (EventInvokeEventShutdown) 的相關資訊。

  • 403 - 禁止

  • 500 - 容器錯誤。不可復原的狀態。延伸項目應會立即結束。

初次化錯誤

延伸項目會使用此方法向 Lambda 報告初始化錯誤。當延伸項目註冊後無法初始化時會調用它。Lambda 收到錯誤後,沒有進一步的API呼叫成功。延伸項目應該在收到 Lambda 的回應之後退出。

路徑/extension/init/error

方法POST

請求標頭
  • Lambda-Extension-Identifier - 延伸項目的唯一識別符。必要:是。類型:UUID字符串。

  • Lambda-Extension-Function-Error-Type - 擴展遇到的錯誤類型。必要:是。此標頭包含一個字串值。Lambda 可接受任何字串,但我們建議使用格式 <category.reason>。例如:

    • 擴充功能。 NoSuchHandler

    • 擴充功能。 APIKeyNotFound

    • 擴充功能。 ConfigInvalid

    • 擴充功能。 UnknownReason

請求內文參數
  • ErrorRequest - 關於錯誤的資訊。必要:否。

此欄位是具有下列結構的JSON物件:

{ errorMessage: string (text description of the error), errorType: string, stackTrace: array of strings }

請注意,Lambda 接受 errorType 的任何值。

下列範例顯示 Lambda 函數錯誤訊息,其中函數無法剖析調用中提供的事件資料。

範例 函數錯誤
{ "errorMessage" : "Error parsing event data.", "errorType" : "InvalidEventDataException", "stackTrace": [ ] }
回應代碼
  • 202 - 已接受

  • 400 - 錯誤請求

  • 403 - 禁止

  • 500 - 容器錯誤。不可復原的狀態。延伸項目應會立即結束。

結束錯誤

延伸項目會使用此方法,在結束前向 Lambda 報告錯誤。當您遇到意外失敗時呼叫它。Lambda 收到錯誤後,沒有進一步的API呼叫成功。延伸項目應該在收到 Lambda 的回應之後退出。

路徑/extension/exit/error

方法POST

請求標頭
  • Lambda-Extension-Identifier - 延伸項目的唯一識別符。必要:是。類型:UUID字符串。

  • Lambda-Extension-Function-Error-Type - 擴展遇到的錯誤類型。必要:是。此標頭包含一個字串值。Lambda 可接受任何字串,但我們建議使用格式 <category.reason>。例如:

    • 擴充功能。 NoSuchHandler

    • 擴充功能。 APIKeyNotFound

    • 擴充功能。 ConfigInvalid

    • 擴充功能。 UnknownReason

請求內文參數
  • ErrorRequest - 關於錯誤的資訊。必要:否。

此欄位是具有下列結構的JSON物件:

{ errorMessage: string (text description of the error), errorType: string, stackTrace: array of strings }

請注意,Lambda 接受 errorType 的任何值。

下列範例顯示 Lambda 函數錯誤訊息,其中函數無法剖析調用中提供的事件資料。

範例 函數錯誤
{ "errorMessage" : "Error parsing event data.", "errorType" : "InvalidEventDataException", "stackTrace": [ ] }
回應代碼
  • 202 - 已接受

  • 400 - 錯誤請求

  • 403 - 禁止

  • 500 - 容器錯誤。不可復原的狀態。延伸項目應會立即結束。