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

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

news 2025/11/15 9:58:58

Amazon Kinesis Video Streams WebRTC Control Plane API 深度解析

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

1. 职责定位

维度	说明
所属平面	Control Plane（控制面）
主要用途	1. 信令通道生命周期（创建/描述/删除） 2. 端点发现（获取 Data-Plane HTTPS/WSS/WEBRTC 终端） 3. 权限与配额管理
协议	HTTPS（TLS 1.2+）+ SigV4 签名
终端节点	`https://kinesisvideo.{region}.amazonaws.com`
幂等性	除 List 外均为幂等
默认配额	5–20 TPS/Region/Account（见下表）

2. 接口速览

API	典型调用者	幂等	默认配额	SDK 封装函数
CreateSignalingChannel	启动脚本	✅	10 TPS	`createChannelLws()`
DescribeSignalingChannel	所有客户端	✅	20 TPS	`describeChannelLws()`
GetSignalingChannelEndpoint	所有客户端	✅	20 TPS	`getChannelEndpointLws()`
UpdateSignalingChannel	运维/存储场景	✅	5 TPS	—（直接 REST）
DeleteSignalingChannel	清理脚本	✅	5 TPS	—（直接 REST）
ListSignalingChannels	控制台/运维	❌	5 TPS	—（直接 REST）

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

3. 端到端交互时序

4. 请求/响应详解

4.1 DescribeSignalingChannel

Method: POST
URI: /describeSignalingChannel
Body:

{"ChannelName": "myChannel"
}

Response:

{"ChannelInfo": {"ChannelName": "myChannel","ChannelARN": "arn:aws:kinesisvideo:us-east-1:123456789012:channel/myChannel/12345678901234567","CreationTime": 1.23456789E9,"Version": "1.0"}
}

4.2 GetSignalingChannelEndpoint

Method: POST
URI: /getSignalingChannelEndpoint
Body:

{"ChannelARN": "arn:aws:kinesisvideo:us-east-1:123456789012:channel/myChannel/12345678901234567","SingleMasterChannelEndpointConfiguration": {"Protocols": ["HTTPS", "WSS"],"Role": "MASTER"      // 或 VIEWER}
}

Response:

{"ResourceEndpointList": [{"Protocol": "HTTPS","ResourceEndpoint": "https://b-12345678.kinesisvideo.us-east-1.amazonaws.com"},{"Protocol": "WSS","ResourceEndpoint": "wss://v-12345678.kinesisvideo.us-east-1.amazonaws.com"}]
}

4.3 CreateSignalingChannel

URI: /createSignalingChannel
Body:

{"ChannelName": "myChannel","ChannelType": "SINGLE_MASTER",   // 目前唯一合法值"Tags": [{"Key": "Project", "Value": "WebRTC"}]
}

Response 同 Describe，含新生成 ARN。

5. SigV4 签名与代码实现

签名入口：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=...
nX-Amz-Date: 20251114T123456Z
X-Amz-Security-Token: <session-token>   # 临时凭证时

时钟偏差 > 5 min 将返回 RequestTimeTooSkewed；SDK 自动校正（clockSkew 逻辑 @ LwsApiCalls.c:92）

6. SDK 源码映射

| API | 封装函数 | HTTPS 实现 | 状态机推进 | 关键日志 |
n| ---- | ---- | ---- | ---- | ---- |
| DescribeSignalingChannel | describeChannel() | describeChannelLws() @ LwsApiCalls.c:798 | SIGNALING_STATE_DESCRIBE → GET_ENDPOINT | Perform secure synchronous call for URL: .../describeSignalingChannel |
| GetSignalingChannelEndpoint | getChannelEndpoint() | getChannelEndpointLws() @ LwsApiCalls.c:1039 | GET_ENDPOINT → GET_ICE_CONFIG | ResourceEndpointList/WSS/HTTPS |
| CreateSignalingChannel | createSignalingChannel() | createChannelLws() @ LwsApiCalls.c:850 | 启动时若 404 则自动插入 CREATE | Creating signaling channel |

所有 HTTPS 请求统一走 lwsCompleteSync() → lwsHttpCallbackRoutine()，SigV4 由 createRequestInfo() 注入

7. 状态机简图

任何步骤 4xx/5xx 均触发指数退避重试（初始 100 ms → 最大 30 s）

8. IAM 最小权限模板

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

删除通道需额外 kinesisvideo:DeleteSignalingChannel；列表需 kinesisvideo:ListSignalingChannels

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

# 控制面调用
grep -E "describeChannelLws|getChannelEndpointLws|createChannelLws" master.log# SigV4 头
grep -E "Authorization:|X-Amz-Date:|X-Amz-Security-Token" master.log# 时钟偏差
grep "Clock skew" master.log# 状态机推进
grep "Signaling client state changed" master.log

10. 常见错误与处置

HTTP	错误名	根因	排查
403	AccessDenied	IAM 未授权/签名错误	核对 IAM、Region、时钟
404	ResourceNotFound	通道不存在	确认 ChannelName/ARN；是否已 Delete
400	RequestTimeTooSkewed	本地时间 > 5 min	NTP 同步；检查容器/VM 时区
400	ThrottlingException	超配额	控制台提升 TPS；退避重试已内置