本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 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`
+ **Method** – `PUT`
+ **標頭**
  + `Content-Type`: `application/json`
+ **請求內文參數**
  + **schemaVersion**
    + 必要：是
    + 類型：字串
    + 有效值：`"2025-01-29"`、`"2022-12-13"` 或 `"2022-07-01"`
    + **注意：**Lambda 受管執行個體需要 `"2025-01-29"`。此版本與 Lambda （預設） 函數回溯相容。
  + **destination** – 定義遙測事件目的地和事件傳遞通訊協定的組態設定。
    + 必要：是
    + 類型：物件

      ```
      {
          "protocol": "HTTP",
          "URI": "http://sandbox.localdomain:8080"
      }
      ```
    + **protocol** – Lambda 用來傳送遙測資料的通訊協定。
      + 必要：是
      + 類型：字串
      + 有效值：`"HTTP"`\$1`"TCP"`
    + **URI** – 要傳送遙測資料的目的地 URI。
      + 必要：是
      + 類型：字串
    + 如需詳細資訊，請參閱[指定目的地通訊協定](telemetry-api.md#telemetry-api-destination)。
  + **types** – 您希望延伸項目訂閱的遙測類型。
    + 必要：是
    + 類型：字串陣列
    + 有效值：`"platform"`\$1`"function"`\$1`"extension"`
  + **buffering** – 事件緩衝的組態設定。
    + 必要：否
    + 類型：物件

      ```
      {
         "buffering": {
              "maxItems": 1000,
              "maxBytes": 256*1024,
              "timeoutMs": 100
         }
      }
      ```
    + **maxItems** – 記憶體中要緩衝的事件數目上限。
      + 必要：否
      + 類型：整數
      + 預設：1,000
      + 下限：1,000
      + 上限：10,000
    + **maxBytes** – 記憶體中要緩衝的遙測資料量上限 (位元組)。
      + 必要：否
      + 類型：整數
      + 預設：262,144
      + 下限：262,144
      + 上限：1,048,576
    + **timeoutMs** - 緩衝批次處理的時間上限 (毫秒)。
      + 必要：否
      + 類型：整數
      + 預設：1,000
      + 下限：25
      + 上限：30,000
    + 如需詳細資訊，請參閱[設定記憶體使用量和緩衝](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 - 服務錯誤