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

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

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

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

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

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

Lambda 執行環境生命週期

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

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

初始化階段

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

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

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

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

調用階段

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

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

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

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

每個承載︰傳送到執行時間 (和 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 階段會持續進行，直到所有延伸項目表示它們已完成為止。

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

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

關閉階段

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

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

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

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

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

shutdownReason 包含以下值：

{ 
  "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) 角色和安全性內容。

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

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

失敗處理

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

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

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

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

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

故障排除延伸項目

擴展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

請求標頭

{
    'events': [ 'INVOKE', 'SHUTDOWN']
}             

{
    "functionName": "helloWorld",
    "functionVersion": "$LATEST",
    "handler": "lambda_function.lambda_handler"
}               

{
    "functionName": "helloWorld",
    "functionVersion": "$LATEST",
    "handler": "lambda_function.lambda_handler",
    "accountId": "123456789012"
}

下一頁

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

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

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

路徑 – /extension/event/next

方法 — GET

初次化錯誤

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

路徑 – /extension/init/error

方法 — POST

此欄位是具有下列結構的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": [ ]
}      

結束錯誤

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

路徑 – /extension/exit/error

方法 — POST

此欄位是具有下列結構的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": [ ]
}