針對自訂執行時期使用 Lambda 執行時期 API

AWS Lambda 為自訂執行時間提供 HTTP API，以從 Lambda 接收呼叫事件，並在 Lambda 執行環境中傳送回應資料。本節包含 Lambda 執行時期 API 的 API 參考。

執行時間 API 版本 2018-06-01 的 OpenAPI 規格可從 runtime-api.zip 中獲得

若要建立 API 請求 URL，執行時間會從 AWS_LAMBDA_RUNTIME_API 環境變數中取得 API 端點，新增 API 版本，以及新增所需的資源路徑。

curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next"

下次調用

路徑 – /runtime/invocation/next

方法 – GET

執行時間會傳送此訊息至 Lambda 來請求調用事件。回應內文包含該次調用的承載，此 JSON 文件含有取自函式觸發條件的事件資料。回應標頭包含有關該次調用的額外資料。

請勿在 GET 請求上設定逾時，因為回應可能會延遲。在 Lambda 引導執行時間到執行時間有事件要傳回之間，執行時間程序可能會凍結幾秒鐘。

請求 ID (Lambda-Runtime-Aws-Request-Id) 可識別唯一事件。請求 IDs由事件來源提供，或由 Lambda 在擷取時自動產生。傳送回應或錯誤時，請在 URL 路徑中使用請求 ID。

呼叫 ID (Lambda-Runtime-Invocation-Id) 代表事件的單一呼叫嘗試。單一請求 ID 可能會導致多次調用嘗試，每個嘗試都有自己的唯一調用 ID。Lambda 只會使用每個叫用 ID 一次，而且永遠不會重複使用。將此值回呼至 /response和 /error呼叫。對於與現有執行時間的回溯相容性， 標頭是選用的，省略它不會觸發拒絕。Lambda 只會在標頭存在400 InvalidInvocationId時拒絕 ，但其值不符合作用中的調用。

追蹤標頭包含追蹤 ID、父系 ID 和抽樣決策。如果對請求進行抽樣，請求將由 Lambda 或上游服務進行抽樣。執行時間應設定 _X_AMZN_TRACE_ID 為標頭的值。X-Ray 開發套件將讀取此項以取得 ID 並決定是否要追蹤請求。

調用回應

路徑 – /runtime/invocation/AwsRequestId/response

方法 – POST

在函數執行到完成之後，執行時間會傳送調用回應至 Lambda。若為同步調用，Lambda 會將回應傳送給用戶端。

請求標頭

Lambda-Runtime-Invocation-Id – 回呼從 收到的值/next。400 InvalidInvocationId 如果值不符合作用中的調用，Lambda 會使用 拒絕請求。

REQUEST_ID=156cb537-e2d4-11e8-9b34-d36013741fb9
INVOCATION_ID=<value from Lambda-Runtime-Invocation-Id response header>
curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/response"  -d "SUCCESS" --header "Lambda-Runtime-Invocation-Id: $INVOCATION_ID"

初始化錯誤

如果函數傳回錯誤或執行時間在初始化期間遇到錯誤，執行時間會使用此方法將錯誤報告給 Lambda。

路徑 – /runtime/init/error

方法 – POST

標頭

Lambda-Runtime-Function-Error-Type - 執行期遇到的錯誤類型。此標頭是選用的。Lambda 接受任何字串值；我們建議使用格式 <Category.Reason>，其中 Category 為 Runtime或 Function且 Reason 以大寫字母開頭。例如：

不符合此模式的值會標準化為 Runtime.Unknown或 Function.Unknown。

主體參數

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": [ ]
}      

ERROR="{\"errorMessage\" : \"Failed to load function.\", \"errorType\" : \"InvalidFunctionException\"}"
curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/init/error" -d "$ERROR" --header "Lambda-Runtime-Function-Error-Type: Unhandled"

調用錯誤

如果函數傳回錯誤或執行時間遇到錯誤，執行時間會使用此方法將錯誤報告給 Lambda。

路徑 – /runtime/invocation/AwsRequestId/error

方法 – POST

標頭

Lambda-Runtime-Function-Error-Type - 執行時間遇到的錯誤類型。必要：否。

此標頭包含一個字串值。Lambda 可接受任何字串，但我們建議使用格式 <category.reason>。例如：

Lambda-Runtime-Invocation-Id – 回呼從 收到的值/next。400 InvalidInvocationId 如果值不符合作用中的調用，Lambda 會使用 拒絕請求。

主體參數

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": [ ]
}      

REQUEST_ID=156cb537-e2d4-11e8-9b34-d36013741fb9
ERROR="{\"errorMessage\" : \"Error parsing event data.\", \"errorType\" : \"InvalidEventDataException\"}"
curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/error" -d "$ERROR" --header "Lambda-Runtime-Function-Error-Type: Unhandled"

還原後 （僅適用於 SnapStart)

路徑 – /runtime/restore/next

方法 – GET

快照前掛鉤完成後，執行時間會呼叫 GET /runtime/restore/next。這是一個迭代器樣式的封鎖呼叫，類似於 /runtime/invocation/next，它向 Lambda 發出訊號，表示執行時間已準備好快照執行環境。請求會封鎖，直到 Lambda 從快照還原執行環境，然後傳回具有空白內文的 HTTP 200 回應。

標頭

不需要標頭。

請求語法

GET /2018-06-01/runtime/restore/next HTTP/1.1
Host: ${AWS_LAMBDA_RUNTIME_API}

回應語法

HTTP/1.1 200 OK
Content-Length: 0

還原錯誤 （僅適用於 SnapStart)

如果還原後掛鉤失敗或執行時間在還原期間遇到錯誤，執行時間會使用此方法向 Lambda 報告錯誤。Lambda 使傳輸中的調用失敗，並破壞執行環境。

路徑 – /runtime/restore/error

方法 – POST

標頭

Lambda-Runtime-Function-Error-Type - 執行期遇到的錯誤類型。此標頭是選用的。Lambda 接受任何字串值；我們建議使用格式 <Category.Reason>，其中 Category 為 Runtime或 Function且 Reason 以大寫字母 （例如 ) 開頭Runtime.AfterRestoreError。不符合此模式的值會標準化為 Runtime.Unknown或 Function.Unknown。

POST /2018-06-01/runtime/restore/error HTTP/1.1
Host: ${AWS_LAMBDA_RUNTIME_API}
Lambda-Runtime-Function-Error-Type: Runtime.AfterRestoreError

HTTP/1.1 202 Accepted
Content-Type: application/json

{"status":"OK"}