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

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. 端到端交互时序

Client (SDK) Control Plane 1. 通道存在性校验 POST /describeSignalingChannel {ChannelName} POST /createSignalingChannel {ChannelName} 200 {ChannelARN} POST /describeSignalingChannel alt [404 ResourceNotFound & auto-create=true] 200 {ChannelARN, Version, CreationTime} 2. 获取数据面终端 POST /getSignalingChannelEndpoint {ChannelARN, Protocols:[HTTPS,WSS], Role:MASTER} 200 {ResourceEndpointList:[{Protocol:HTTPS, ResourceEndpoint:...}, {Protocol:WSS, ...}]} Client (SDK) Control Plane

4. 请求/响应详解

4.1 DescribeSignalingChannel

Method : POST
URI : /describeSignalingChannel
Body:

json 复制代码

{
  "ChannelName": "myChannel"
}

Response:

json 复制代码

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

json 复制代码

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

Response:

json 复制代码

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

json 复制代码

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

Response 同 Describe，含新生成 ARN。

5. SigV4 签名与代码实现

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

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

6. SDK 源码映射

n| ---- | ---- | ---- | ---- | ---- |

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

7. 状态机简图

404 & auto-create=true 200 200 200 200 WSS connected DESCRIBE CREATE GET_ENDPOINT GET_ICE_CONFIG CONNECT READY

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

8. IAM 最小权限模板

json 复制代码

{
  "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. 日志关键词与快速检索

bash 复制代码

# 控制面调用
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；退避重试已内置

11. 小结

职责：控制面仅负责"资源发现"与"生命周期"，不涉媒体与信令内容
协议：统一 HTTPS + SigV4 + JSON，区域级终端节点，幂等设计
SDK：C-SDK 用 libwebsockets 封装，状态机驱动，指数退避重试，自动时钟校正
排错：先看 IAM → 时钟 → 配额 → 日志关键词；80% 问题为权限/时钟/拼写

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

describeChannelLws() → src/source/Signaling/LwsApiCalls.c:798
getChannelEndpointLws() → src/source/Signaling/LwsApiCalls.c:1039
createChannelLws() → src/source/Signaling/LwsApiCalls.c:850
状态机定义 → <src/source/Signaling/StateMachine.c>
SigV4 生成 → <src/source/Common/Auth.c>

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