# 将 Lambda 运行时 API 用于自定义运行时
<a name="runtimes-api"></a>

AWS Lambda 提供了用于[自定义运行时](runtimes-custom.md)的 HTTP API，接收来自 Lambda 的调用事件并在 Lambda [执行环境](lambda-runtimes.md)中发送回响应数据。本节包含 Lambda 运行时 API 的 API 参考。

**Lambda 托管实例支持并发请求**  
Lambda 托管实例使用与 Lambda（默认）函数相同的运行时 API。关键区别在于，托管实例可以接受不超过 `AWS_LAMBDA_MAX_CONCURRENCY` 配置限制的并发 `/next` 和 `/response` 请求。这样一来，就可以在单个执行环境中同时处理多个调用。有关托管实例的更多信息，请参阅 [了解 Lambda 托管实例执行环境](lambda-managed-instances-execution-environment.md)。

![\[执行环境的体系结构图。\]](http://docs.aws.amazon.com/zh_cn/lambda/latest/dg/images/telemetry-api-concept-diagram.png)


运行时 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)

## 下一个调用
<a name="runtimes-api-next"></a>

**路径** – `/runtime/invocation/next`

**方法** – **GET**

运行时将此消息发送到 Lambda 以请求调用事件。响应主体包含来自调用的有效负载，该负载是包含来自函数触发器的事件数据的 JSON 文档。响应标头包含有关调用的额外数据。

**响应标头**
+ `Lambda-Runtime-Aws-Request-Id` – 请求 ID，用于标识触发了函数调用的请求。

  例如：`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 身份提供商的数据。

不要对 `GET` 请求设置超时，因为响应可能会延迟。在 Lambda 引导运行时和运行时返回事件之间，运行时进程可能会冻结几秒钟。

请求 ID 用于跟踪 Lambda 中的调用。使用它可在您发送响应时指定调用。

跟踪标头包含跟踪 ID、父 ID 和采样决策。如果对请求进行采样，则由 Lambda 或某个上游服务对请求进行采样。运行时应设置具有标头的值的 `_X_AMZN_TRACE_ID`。X-Ray 开发工具包会读取此项以获取 ID 并确定是否要跟踪请求。

## 调用响应
<a name="runtimes-api-response"></a>

**路径** – `/runtime/invocation/AwsRequestId/response`

**方法** – **POST**

在函数运行完成后，运行时会将调用响应发送到 Lambda。对于同步调用，Lambda 会将响应发送到客户端。

**Example 成功请求**  

```
REQUEST_ID=156cb537-e2d4-11e8-9b34-d36013741fb9
curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/response"  -d "SUCCESS"
```

## 初始化错误
<a name="runtimes-api-initerror"></a>

如果函数返回错误或运行时在初始化期间遇到错误，则运行时将使用此方法向 Lambda 报告错误。

**路径** – `/runtime/init/error`

**方法** – **POST**

**标头**

`Lambda-Runtime-Function-Error-Type` – 运行时遇到的错误类型。必需：否 

此标头由字符串值组成。Lambda 接受任何字符串，但建议您使用 <category.reason> 格式。例如：
+ Runtime.NoSuchHandler
+ Runtime.APIKeyNotFound
+ Runtime.ConfigInvalid
+ Runtime.UnknownReason

**主体参数**

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

## 调用错误
<a name="runtimes-api-invokeerror"></a>

如果函数返回错误或运行时遇到错误，则运行时将使用此方法向 Lambda 报告错误。

**路径** – `/runtime/invocation/AwsRequestId/error`

**方法** – **POST**

**标头**

`Lambda-Runtime-Function-Error-Type` – 运行时遇到的错误类型。必需：否 

此标头由字符串值组成。Lambda 接受任何字符串，但建议您使用 <category.reason> 格式。例如：
+ Runtime.NoSuchHandler
+ Runtime.APIKeyNotFound
+ Runtime.ConfigInvalid
+ Runtime.UnknownReason

**主体参数**

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