本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 針對自訂執行時期使用 Lambda 執行時期 API
AWS Lambda 為[自訂執行時間](runtimes-custom.md)提供 HTTP API，以從 Lambda 接收呼叫事件，並在 Lambda [執行環境中](lambda-runtimes.md)傳送回應資料。本節包含 Lambda 執行時期 API 的 API 參考。
**Lambda 受管執行個體支援並行請求**
Lambda 受管執行個體使用與 Lambda （預設） 函數相同的執行時間 API。關鍵差異在於受管執行個體可以接受並行請求`/next`，並且`/response`請求達到設定的`AWS_LAMBDA_MAX_CONCURRENCY`限制。這可在單一執行環境中同時處理多個調用。如需受管執行個體的詳細資訊，請參閱 [了解 Lambda 受管執行個體執行環境](lambda-managed-instances-execution-environment.md)。
執行時間 API 版本 **2018-06-01** 的 OpenAPI 規格可從 [runtime-api.zip](samples/runtime-api.zip) 中獲得
若要建立 API 請求 URL，執行時間會從 `AWS_LAMBDA_RUNTIME_API` 環境變數中取得 API 端點，新增 API 版本，以及新增所需的資源路徑。
**Example 請求**
```
curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next"
```
**Topics**
+ [下次調用](#runtimes-api-next)
+ [調用回應](#runtimes-api-response)
+ [初始化錯誤](#runtimes-api-initerror)
+ [調用錯誤](#runtimes-api-invokeerror)
+ [還原後 （僅適用於 SnapStart)](#runtimes-api-after-restore)
+ [還原錯誤 （僅適用於 SnapStart)](#runtimes-api-restore-error)
## 下次調用
**路徑** – `/runtime/invocation/next`
**方法** – **GET**
執行時間會傳送此訊息至 Lambda 來請求調用事件。回應內文包含該次調用的承載，此 JSON 文件含有取自函式觸發條件的事件資料。回應標頭包含有關該次調用的額外資料。
**回應標頭**
+ `Lambda-Runtime-Aws-Request-Id` – 觸發函數調用的事件。事件來源提供請求 IDs，或 Lambda 會在擷取時自動產生請求 ID。單一請求 ID 可能會導致多次調用嘗試。傳送回應或錯誤時，請在 URL 路徑中使用它。
例如 `8476a536-e9f4-11e8-9739-2dfe598c3fcd`。
+ `Lambda-Runtime-Deadline-Ms` - 函數逾時的日期，以 Unix 時間毫秒為單位。
例如 `1542409706888`。
+ `Lambda-Runtime-Invoked-Function-Arn` - 在調用中指定的 Lambda 函數、版本或別名的 ARN。
例如 `arn:aws:lambda:us-east-2:123456789012:function:custom-runtime`。
+ `Lambda-Runtime-Trace-Id` - [AWS X-Ray 追蹤標頭](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-tracingheader)。
例如 `Root=1-5bef4de7-ad49b0e87f6ef6c87fc2e700;Parent=9a9197af755a6419;Sampled=1`。
+ `Lambda-Runtime-Client-Context` – 對於來自 AWS Mobile SDK 的調用，則為用戶端應用程式和裝置的資料。
+ `Lambda-Runtime-Cognito-Identity` – 對於來自 AWS Mobile SDK 的調用，是有關 Amazon Cognito 身分提供者的資料。
+ `Lambda-Runtime-Invocation-Id` – 此調用嘗試的唯一識別符。
請勿在 `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 會使用 拒絕請求。
**Example 成功請求**
```
REQUEST_ID=156cb537-e2d4-11e8-9b34-d36013741fb9
INVOCATION_ID=
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 為 `Runtime`或 `Function`且 Reason 以大寫字母開頭。例如：
+ `Runtime.NoSuchHandler`
+ `Runtime.APIKeyNotFound`
+ `Runtime.ConfigInvalid`
+ `Runtime.BeforeSnapshotError` （適用於 SnapStart)
+ `Runtime.UnknownReason`
不符合此模式的值會標準化為 `Runtime.Unknown`或 `Function.Unknown`。
**主體參數**
`ErrorRequest` - 關於錯誤的資訊。必要：否。
此欄位是具有下列結構的 JSON 物件：
```
{
errorMessage: string (text description of the error),
errorType: string,
stackTrace: array of strings
}
```
請注意，Lambda 接受 `errorType` 的任何值。
下列範例顯示 Lambda 函數錯誤訊息，其中函數無法剖析調用中提供的事件資料。
**Example 函數錯誤**
```
{
"errorMessage" : "Error parsing event data.",
"errorType" : "InvalidEventDataException",
"stackTrace": [ ]
}
```
**回應內文參數**
+ `StatusResponse` – 字串. 狀態信息，隨 202 回應代碼一起傳送。
+ `ErrorResponse` - 其他錯誤資訊，與錯誤回應代碼一起傳送。ErrorResponse 包含錯誤類型和錯誤訊息。
**回應代碼**
+ 202 - 已接受
+ 403 - 禁止
+ 500 - 容器錯誤。不可復原的狀態。執行時間應立即退出。
**Example 初始化錯誤請求**
```
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 可接受任何字串，但我們建議使用格式 。例如：
+ Runtime.NoSuchHandler
+ Runtime.APIKeyNotFound
+ Runtime.ConfigInvalid
+ Runtime.UnknownReason
`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 函數錯誤訊息，其中函數無法剖析調用中提供的事件資料。
**Example 函數錯誤**
```
{
"errorMessage" : "Error parsing event data.",
"errorType" : "InvalidEventDataException",
"stackTrace": [ ]
}
```
**回應內文參數**
+ `StatusResponse` – 字串. 狀態信息，隨 202 回應代碼一起傳送。
+ `ErrorResponse` - 其他錯誤資訊，與錯誤回應代碼一起傳送。ErrorResponse 包含錯誤類型和錯誤訊息。
**回應代碼**
+ 202 - 已接受
+ 400 - 錯誤請求
+ 403 - 禁止
+ 500 - 容器錯誤。不可復原的狀態。執行時間應立即退出。
**Example 錯誤請求**
```
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 回應。
**標頭**
不需要標頭。
**回應代碼**
+ 200 – Lambda 還原了執行環境。執行還原後掛鉤。回應內文是空的。
+ 403 – 禁止。執行時間未處於允許的狀態 `/restore/next`（例如，執行時間已呼叫 `/invocation/next`或 `/restore/next`)。
+ 404 – 此函數未啟用 SnapStart。
+ 500 - 容器錯誤。執行環境處於無法復原的狀態。結束執行時間程序。
```
GET /2018-06-01/runtime/restore/next HTTP/1.1
Host: ${AWS_LAMBDA_RUNTIME_API}
```
```
HTTP/1.1 200 OK
Content-Length: 0
```
**注意**
請勿在此 （或任何其他） 執行時間 API 請求上設定用戶端通訊端或讀取逾時。這是迭代器樣式的封鎖呼叫；Lambda 會在請求開啟時凍結執行環境。請求可以在快照的整個生命週期 （可能為幾天、幾週或更久） 內保持開啟，而不會將連線視為從 Lambda 服務閒置。
## 還原錯誤 （僅適用於 SnapStart)
如果還原後掛鉤失敗或執行時間在還原期間遇到錯誤，執行時間會使用此方法向 Lambda 報告錯誤。Lambda 使傳輸中的調用失敗，並破壞執行環境。
**路徑** – `/runtime/restore/error`
**方法** – **POST**
**標頭**
`Lambda-Runtime-Function-Error-Type` - 執行期遇到的錯誤類型。此標頭是選用的。Lambda 接受任何字串值；我們建議使用格式 ``，其中 Category 為 `Runtime`或 `Function`且 Reason 以大寫字母 （例如 ) 開頭`Runtime.AfterRestoreError`。不符合此模式的值會標準化為 `Runtime.Unknown`或 `Function.Unknown`。
**回應代碼**
+ 202 – 已接受。回應內文為 `{"status":"OK"}`。執行時間應結束 程序。
+ 403 – 禁止。執行時間未處於允許的狀態 `/restore/error`（例如，`/restore/next`尚未呼叫 )。
+ 404 – 此函數未啟用 SnapStart。
+ 500 - 容器錯誤。執行環境處於無法復原的狀態。結束執行時間程序。
**Example 範例請求**
```
POST /2018-06-01/runtime/restore/error HTTP/1.1
Host: ${AWS_LAMBDA_RUNTIME_API}
Lambda-Runtime-Function-Error-Type: Runtime.AfterRestoreError
```
**Example 回應範例**
```
HTTP/1.1 202 Accepted
Content-Type: application/json
{"status":"OK"}
```