【ZeroRange WebRTC】Amazon Kinesis Video Streams WebRTC Data Plane REST API 深度解析

基于官方文档与 amazon-kinesis-video-streams-webrtc-sdk-c-main 源码（v1.7.0+）

1. 职责定位

维度	说明
所属平面	Data Plane REST（信令数据面 REST）
主要用途	1. 获取短期 STUN/TURN 列表与临时凭证（GetIceServerConfig） 2. 存储会话管理（JoinStorageSession / UpdateStorageSession） 3. 支持录制与回放场景
协议	HTTPS（TLS 1.2+）+ SigV4 签名
终端节点	由 `GetSignalingChannelEndpoint` 返回的 `ResourceEndpointList.Protocol=HTTPS`
幂等性	全部幂等
默认配额	5--20 TPS/Region/Channel（见下表）

2. 接口速览

API	典型调用者	幂等	默认配额	SDK 封装函数
GetIceServerConfig	所有客户端	✅	20 TPS	`getIceConfigLws()`
JoinStorageSession	存储场景 Master	✅	5 TPS	`joinStorageSessionLws()`
UpdateStorageSession	运维/存储场景	✅	5 TPS	`updateStorageSessionLws()`

配额提升路径：AWS Support → Service Quotas → Kinesis Video Streams

3. 端到端交互时序

Client (SDK) Data-Plane Endpoint (HTTPS) KVS Signaling Service 1. 获取终端（控制面已完成） POST /getIceServerConfig {ChannelARN, ClientId} 200 {IceServerList:[{Username,Password,Ttl,Uris:[...]}]} 2. 存储场景（可选） POST /joinStorageSession {ChannelARN} 200 {StorageStatus:ENABLED} alt [enableMediaStorage] Client (SDK) Data-Plane Endpoint (HTTPS) KVS Signaling Service

4. 请求/响应详解

4.1 GetIceServerConfig

Method : POST
URI : /{AccountId}/channel/{ChannelARN}/getIceServerConfig
Body:

json 复制代码

{
  "ChannelARN": "arn:aws:kinesisvideo:us-east-1:123456789012:channel/myChannel/12345678901234567",
  "ClientId": "web-123",          // 可选，用于审计
  "Service": "TURN"               // 固定值
}

Response:

json 复制代码

{
  "IceServerList": [
    {
      "Username": "1600000000:abc123",
      "Password": "def456...",
      "Ttl": 86400,
      "Uris": [
        "turns:turn-12345678.kinesisvideo.us-east-1.amazonaws.com:443?transport=tcp",
        "turn:turn-12345678.kinesisvideo.us-east-1.amazonaws.com:3478?transport=udp"
      ]
    }
  ]
}

4.2 JoinStorageSession（可选）

URI : /joinStorageSession
Body:

json 复制代码

{
  "ChannelARN": "arn:aws:kinesisvideo:us-east-1:123456789012:channel/myChannel/12345678901234567"
}

Response:

json 复制代码

{
  "StorageStatus": "ENABLED",
  "StorageSessionARN": "arn:aws:kinesisvideo:us-east-1:123456789012:storage-session/..."
}

5. SigV4 签名与终端拼装

终端来源：GetSignalingChannelEndpoint 返回的 ResourceEndpointList.Protocol=HTTPS
签名入口：createRequestInfo() → generateSignature() @ <src/source/Common/Auth.c>
关键头：

http 复制代码

Authorization: AWS4-HMAC-SHA256 Credential=AKIA.../20251114/us-east-1/kinesisvideo/aws4_request, SignedHeaders=host;x-amz-date, Signature=...
X-Amz-Date: 20251114T123456Z
X-Amz-Security-Token: <session-token>

6. 源码级映射（amazon-kinesis-video-streams-webrtc-sdk-c-main）

API	SDK 封装函数	HTTPS 实现	状态机推进	关键日志
GetIceServerConfig	`getIceConfig()`	`getIceConfigLws()` @ LwsApiCalls.c:1188	`SIGNALING_STATE_GET_ICE_CONFIG` → `CONNECT`	`IceServerList`/`Ttl`
JoinStorageSession	`joinStorageSession()`	`joinStorageSessionLws()` @ LwsApiCalls.c:1570	存储场景下调用	`StorageStatus:ENABLED`
UpdateStorageSession	`updateStorageSession()`	`updateStorageSessionLws()` @ LwsApiCalls.c:1600	运行时更新存储配置	`StorageStatus:UPDATED`

所有请求统一走 lwsCompleteSync() → lwsHttpCallbackRoutine()，JSON 拼装模板见 LwsApiCalls.h:131-144

7. JSON 模板与字段说明

7.1 IceServerConfig 模板（src/source/Signaling/LwsApiCalls.h）

c 复制代码

#define SIGNALING_ICE_SERVER_LIST_TEMPLATE_START ",\n\t\"IceServerList\": ["
#define SIGNALING_ICE_SERVER_TEMPLATE \
    "\n\t\t{\n" \
    "\t\t\t\"Password\": \"%s\",\n" \
    "\t\t\t\"Ttl\": %" PRIu64 ",\n" \
    "\t\t\t\"Uris\": [%s],\n" \
    "\t\t\t\"Username\": \"%s\"\n" \
    "\t\t},"

7.2 字段含义

字段	类型	说明
Username	string	临时用户名，格式 `{unixTime}:{random}`
Password	string	基于 AWS 签名密钥派生，有效期 = Ttl
Ttl	long	凭证有效期（秒），默认 24 h
Uris	array	支持 `turn:` 与 `turns:`，端口 3478/443

8. 重试与退避

指数退避：初始 100 ms → 最大 30 s，因子 1.5
幂等：相同 ChannelARN+ClientId 多次调用返回相同结果
时钟偏差：> 5 min 返回 RequestTimeTooSkewed，SDK 自动校正

9. IAM 最小权限模板

json 复制代码

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kinesisvideo:GetIceServerConfig",
        "kinesisvideo:JoinStorageSession",
        "kinesisvideo:UpdateStorageSession"
      ],
      "Resource": "arn:aws:kinesisvideo:*:*:channel/myAppPrefix*"
    }
  ]
}

10. 日志关键词与快速检索

bash 复制代码

# IceServerConfig
grep -E "getIceConfigLws|IceServerList|Ttl" master.log

# 存储会话
grep -E "joinStorageSessionLws|StorageStatus" master.log

# SigV4 头
grep -E "Authorization:|X-Amz-Date:" master.log

# 时钟偏差
grep "Clock skew" master.log

11. 常见错误与处置

HTTP	错误名	根因	排查
403	AccessDenied	IAM/签名/时钟	核对 IAM、Region、NTP
404	ResourceNotFound	ChannelARN 错误	ARN 与终端 Region 一致
400	ThrottlingException	超配额	控制台提升 TPS；退避已内置
400	RequestTimeTooSkewed	时钟 > 5 min	容器/VM 时区同步

12. 小结

职责：Data-Plane REST 仅负责"网络配置获取"与"存储会话管理"，不承载媒体与信令消息
安全：TLS + SigV4 + 短期凭证，独立配额与审计
可靠：幂等 + 指数退避 + 自动时钟校正
易用：JSON 模板透明，SDK 封装拼装/重试/错误处理

附录：引用源码（行号随版本略有浮动）

getIceConfigLws() → src/source/Signaling/LwsApiCalls.c:1188
joinStorageSessionLws() → src/source/Signaling/LwsApiCalls.c:1570
JSON 模板 → src/source/Signaling/LwsApiCalls.h:131-144
SigV4 生成 → <src/source/Common/Auth.c>

如需 PlantUML 高清时序图、CloudWatch Insights 查询模板或一键 IAM 策略生成脚本，请告诉我！