Lambda Extensions API

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

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

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

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

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

注意

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

Lambda 執行環境生命週期

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

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

Init 階段分為三個子階段：Extension init、Runtime init 以及 Function init。這些子階段可確保所有擴展功能和執行時間在函數程式碼執行之前完成其設定任務。
Invoke：在此階段中，Lambda 會調用函數處理常式。函數執行完成之後，Lambda 會準備處理另一個函數調用。
Shutdown：如果 Lambda 函數在一段時間內未收到任何調用，就會觸發此階段。在 Shutdown 階段中，Lambda 會關閉執行時間、警示擴展功能以便它們完全停止，然後移除環境。Lambda 會傳送 Shutdown 事件到每個擴展功能，這會告訴擴展功能環境即將關閉。

每個階段都會從 Lambda 到執行時間和所有已註冊延伸項目的事件開始。執行時間和每個已註冊延伸項目都會透過傳送 Next API 請求來表示已完成。當每個處理已完成且沒有擱置的事件時，Lambda 凍結執行環境。

主題

初始化階段
調用階段
關閉階段
許可與組態
失敗處理
故障排除延伸項目

初始化階段

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

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

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

Init 階段會在執行階段之後完成，每個已註冊延伸項目都會透過傳送 Next API 請求來表示已完成。

注意

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

調用階段

當調用 Lambda 函數來回應 Next API 請求時，Lambda 會將 Invoke 事件傳送至執行時間，並傳送至針對該 Invoke 事件已註冊的每個延伸項目。

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

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

Invoke 階段會在執行階段後結束，所有延伸項目訊號都透過傳送 Next API 請求完成。

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

想要存取函式事件主體的延伸項目，您可以使用與延伸項目通訊的執行階段 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 指標。此指標會測量執行階段 Next API 請求與上次延伸 Next API 請求之間所花費的累計時間。若要測量使用的記憶體增加的情況，請使用 MaxMemoryUsed 指標。如需函式指標的詳細資訊，請參閱使用 Lambda 函數指標。

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

關閉階段

當 Lambda 即將關閉執行時間，它會將 Shutdown 事件傳送至每個已註冊外部延伸。延伸項目可以使用此時間進行最終清理工作。系統會傳送 Shutdown 事件以回應 Next API 請求。

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

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

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

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

事件承載：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 請求失敗，請確定 Register API 呼叫中的 Lambda-Extension-Name 標頭包含延伸項目的完整檔案名稱。
如果內部延伸項目的 Register 請求失敗，請確定請求不會註冊 Shutdown 事件。

Extensions API 參考

對於 Extensions API 版本 2020-01-01 的 OpenAPI 規範可以在這裡找到：extensions-api.zip

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


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

API 方法

登錄
下一頁
初次化錯誤
結束錯誤

登錄

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

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

路徑 – /extension/register

方法 – POST

請求標頭

Lambda-Extension-Name - 延伸項目的完整檔案名稱。必要：是。類型：字串。
Lambda-Extension-Accept-Feature - 用來在註冊期間指定選用的延伸項目特色。必要：否。類型：逗號分隔的字串。可使用此設定來指定的特色：
- accountId - 如果指定此項，延伸項目註冊回應將包含與待註冊延伸項目之 Lambda 函數相關聯的帳戶 ID。

請求內文參數

events - 要註冊的事件陣列。必要：否。類型：字串陣列。有效字串：INVOKE、SHUTDOWN。

回應標頭

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

延伸項目會傳送 Next API 請求以接收下一個事件，可以是 Invoke 事件或 Shutdown 事件。回應主體包含承載，這是包含事件資料的 JSON 文件。

延伸項目會傳送 Next API 請求，以表示它已準備好接收新事件。這是一個封鎖調用。

請勿在 GET 調用上設定逾時，因為延伸項目可以暫停一段時間，直到有事件傳回為止。

路徑 – /extension/event/next

方法 – GET

請求標頭

Lambda-Extension-Identifier - 延伸項目的唯一識別符 (UUID 字串)。必要：是。類型：UUID 字串。

回應標頭

Lambda-Extension-Event-Identifier - 延伸項目的唯一識別符 (UUID 字串)。

回應代碼

200 - 回應包含下個事件 (EventInvoke 或 EventShutdown) 的相關資訊。
403 - 禁止
500 - 容器錯誤。不可復原的狀態。延伸項目應會立即結束。

初次化錯誤

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

路徑 – /extension/init/error

方法 – POST

請求標頭

Lambda-Extension-Identifier - 延伸項目的唯一識別符。必要：是。類型：UUID 字串。
Lambda-Extension-Function-Error-Type - 擴展遇到的錯誤類型。必要：是。此標頭包含一個字串值。Lambda 可接受任何字串，但我們建議使用格式 <category.reason>。例如：
- 擴充功能。 NoSuchHandler
- 擴展名 .API KeyNotFound
- 擴充功能。 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
- 擴展名 .API KeyNotFound
- 擴充功能。 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 - 容器錯誤。不可復原的狀態。延伸項目應會立即結束。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

延伸合作夥伴

遙測 API

Lambda Extensions API

注意

主題

Lambda 執行環境生命週期

主題

初始化階段

注意

調用階段

注意

關閉階段

許可與組態

注意

失敗處理

故障排除延伸項目

Extensions API 參考

API 方法

登錄

請求內文參數

回應標頭

回應代碼

範例請求主體

範例回應主題

範例 具有選用 accountId 特色的回應內文範例

下一頁

請求標頭

回應標頭

回應代碼

初次化錯誤

請求標頭

請求內文參數

範例 函數錯誤

回應代碼

結束錯誤

請求標頭

請求內文參數

範例 函數錯誤

回應代碼

範例具有選用 accountId 特色的回應內文範例

範例函數錯誤

範例函數錯誤