当前位置：首页 > news >正文

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

news 2025/11/15 6:58:57

基于官方文档与 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. 端到端交互时序

4. 请求/响应详解

4.1 GetIceServerConfig

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

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

Response:

{"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:

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

Response:

{"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
关键头：

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）

#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 最小权限模板

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

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

# 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 时区同步