# Lambda 遥测 API 参考
<a name="telemetry-api-reference"></a>

使用 Lambda 遥测 API 端点订阅遥测流的扩展。您可以从 `AWS_LAMBDA_RUNTIME_API` 环境变量中检索遥测 API 端点。若要发送 API 请求，请附加 API 版本（`2022-07-01/`）和 `telemetry/`。例如：

```
http://${AWS_LAMBDA_RUNTIME_API}/2022-07-01/telemetry/
```

有关订阅响应版本 `2025-01-29` 的 OpenAPI 规范（OAS）定义，请参阅以下内容：
+ **HTTP** – [telemetry-api-http-schema.zip](samples/events_http_schema_v2025_01_29.zip)
+ **TCP** – [telemetry-api-tcp-schema.zip](samples/events_tcp_schema_v2025_01_29.zip)

**Topics**
+ [订阅](#telemetry-subscribe-api)

## 订阅
<a name="telemetry-subscribe-api"></a>

若要订阅遥测流，Lambda 扩展可以发送订阅 API 请求。
+ **路径** – `/telemetry`
+ **方法** – `PUT`
+ **标头**：
  + `Content-Type`: `application/json`
+ **请求正文参数**
  + **schemaVersion**
    + 是否必需：是
    + 类型：字符串
    + 有效值：`"2025-01-29"`、`"2022-12-13"` 或 `"2022-07-01"`
    + **注意：**Lambda 托管实例需要 `"2025-01-29"`。此版本向后兼容 Lambda（默认）函数。
  + **目标** – 定义遥测事件目标和事件传输协议的配置设置。
    + 是否必需：是
    + 类型：对象

      ```
      {
          "protocol": "HTTP",
          "URI": "http://sandbox.localdomain:8080"
      }
      ```
    + **协议** – Lambda 用于发送遥测数据的协议。
      + 是否必需：是
      + 类型：字符串
      + 有效值：`"HTTP"`\$1`"TCP"`
    + **URI** – 要向其发送遥测数据的 URI。
      + 是否必需：是
      + 类型：字符串
    + 有关更多信息，请参阅 [指定目标协议](telemetry-api.md#telemetry-api-destination)。
  + **类型** – 您希望扩展订阅的遥测类型。
    + 是否必需：是
    + 类型：字符串数组
    + 有效值：`"platform"`\$1`"function"`\$1`"extension"`
  + **缓冲** – 事件缓冲的配置设置。
    + 必需：否
    + 类型：对象

      ```
      {
         "buffering": {
              "maxItems": 1000,
              "maxBytes": 256*1024,
              "timeoutMs": 100
         }
      }
      ```
    + **maxItems** – 在内存中缓冲的最大事件数。
      + 必需：否
      + 类型：整数
      + 默认值：1000
      + 最小值：1000
      + 最大值：10000
    + **maxBytes** – 在内存中缓冲的最大遥测量（以字节为单位）。
      + 必需：否
      + 类型：整数
      + 默认值：262144
      + 最小值：262144
      + 最大值：1048576。
    + **timeoutMs** – 缓冲批的最长时间（以毫秒为单位）。
      + 必需：否
      + 类型：整数
      + 默认值：1000
      + 最小值：25
      + 最大值：30000
    + 有关更多信息，请参阅 [配置内存使用量和缓冲](telemetry-api.md#telemetry-api-buffering)。

### 订阅 API 请求示例
<a name="telemetry-subscribe-api-example"></a>

```
PUT http://${AWS_LAMBDA_RUNTIME_API}/2022-07-01/telemetry HTTP/1.1
{
   "schemaVersion": "2025-01-29",
   "types": [
        "platform",
        "function",
        "extension"
   ],
   "buffering": {
        "maxItems": 1000,
        "maxBytes": 256*1024,
        "timeoutMs": 100
   },
   "destination": {
        "protocol": "HTTP",
        "URI": "http://sandbox.localdomain:8080"
   }
}
```

如果订阅请求成功，扩展将收到 HTTP 200 成功响应：

```
HTTP/1.1 200 OK
"OK"
```

如果订阅请求失败，扩展将收到错误响应。例如：

```
HTTP/1.1 400 OK
{
    "errorType": "ValidationError",
    "errorMessage": "URI port is not provided; types should not be empty"
}
```

以下是扩展可以收到的一些其他响应代码：
+ 200 – 已成功完成请求
+ 202 – 已接受请求。本地测试环境中的订阅请求响应
+ 400 – 错误请求
+ 500 – 服务错误