forked from Rebeccacy/cloud-recording-cn
-
Notifications
You must be signed in to change notification settings - Fork 0
/
webrtc_restful_api.yaml
544 lines (509 loc) · 19 KB
/
webrtc_restful_api.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
openapi: 3.0.0
info:
description: >
Agora WebRTC 开放平台旨在依托 SD-RTN™ 资源，对标准 WebRTC 客户端提供 SFU (Selective Forwarding Unit) 服务。
简单来说，你可以通过在客户端发送 HTTP 请求使用原生的 WebRTC 协议实现 Agora 通话。
> 我们推荐使用安全性较高的 HTTPS 协议发送请求。
## 调用步骤
一次通话的基本流程如下：
1. 发起 HTTP 请求获取通话资源。
2. 获取通话资源后，继续发起推流或者拉流请求。在推流或者拉流的请求中需要填入第一步获取的响应内容，同时填入客户端使用的设备和平台信息上报给 Agora。
3. 通话过程中通过 HTTP 请求将通话质量相关的数据上报给 Agora，以便调查问题。
> 如果没有上报数据，将无法调查质量问题。
## 示例项目
我们提供一个 Web 示例项目，你可以[在线体验](https://webdemo.agora.io/webrtc_http_demo/)，并参考[源代码](https://webdemo.agora.io/webrtc_http_demo/js/index.js)。
## 状态码
下表列出响应包体中可能出现的状态码以及对应的 `detail` 参数值。
> 该表格仅适用于拉流、推流以及上报请求，获取通话资源请求的响应错误码详见具体响应中的描述。
<table>
<tr>
<th>code</th>
<th>detail</th>
<th>描述</th>
</tr>
<tr>
<td>200</td>
<td>"v=0\r\no=- 0 0 IN IP4 127.0.0.1\ ... na=ssrc:55543 label:XrKNrJZpIqv0\r\n"</td>
<td>请求成功。</td>
</tr>
<tr>
<td>400</td>
<td>The request cannot be fulfilled due to bad syntax.</td>
<td>参数值存在不合法字符。</td>
</tr>
<tr>
<td>404</td>
<td>The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.</td>
<td>参数缺失。</td>
</tr>
<tr>
<td>501</td>
<td>internal error</td>
<td>内部错误。</td>
</tr>
<tr>
<td>502</td>
<td>invalid params</td>
<td>参数类型或其他错误。</td>
</tr>
<tr>
<td>503</td>
<td>pull stream failed</td>
<td>cname 或 streamid 不存在或其他原因导致的拉流失败。</td>
</tr>
<tr>
<td>504</td>
<td>push stream failed</td>
<td>推流失败。</td>
</tr>
<tr>
<td>505</td>
<td>stats report failed</td>
<td>上报通话质量失败。</td>
</tr>
</table>
version: Feb 19, 2020
title: WebRTC 开放平台
servers:
- url: 'https://{server_domain}:443/v1'
description: 用于拉流/推流/上报质量数据的服务器。
variables:
server_domain:
description: 获取通话资源请求的响应中的 `server_domain` 字段的值。
default: server_domain
- url: 'https://apdomain'
description: 用于获取通话资源的服务器。
paths:
/api/v1:
post:
summary: 获取通话资源
description: 在开始拉流或者推流之前，你需要首先请求通话资源用于拉流或者推流。
parameters:
- in: header
name: Content-Type
required: true
schema:
type: string
enum:
- application/json
- in: header
name: X-Packet-Service-Type
required: true
schema:
type: integer
enum:
- 0
description: 必须设置为 0。
- in: header
name: X-Packet-URI
required: true
schema:
type: integer
enum:
- 78
description: 必须设置为 78。
- in: header
name: X-Request-From
required: false
schema:
type: string
description:
客户端 IP 地址。
- 如果你使用自己的服务器转发请求需要填写原客户端的外网 IP 地址。
- 如果直接从客户端发送请求则无需填写该字段。
- in: query
name: action
required: true
schema:
type: string
enum:
- wrtc_live
description: 必须设置为 `wrtc_live`。
requestBody:
description: 包含频道相关信息的 JSON 对象。
content:
application/json:
schema:
type: object
required:
- cname
- flag
- key
- opid
- ts
- uid
properties:
cname:
type: string
description: >-
频道名，长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）:
- 26 个小写字母 a-z
- 26 个大写字母 A-Z
- 10 个数字 0-9
- 空格
- "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "\|", "~", ","
flag:
type: integer
description: 保留字段，必须设置为 4096，表示使用 WebRTC 协议。
key:
type: string
description: App ID 或动态密钥 (token)，取决于你的 Agora 项目使用的鉴权机制。详见[校验用户权限](https://docs.agora.io/cn/Agora Platform/token?platform=All Platforms)。
opid:
type: integer
format: int64
description: 操作 ID，用于标记该次请求。一个随机的 64 位无符号整数。
ts:
type: integer
description: 发送请求的时间，Unix 时间戳，单位为毫秒。
uid:
type: integer
format: int32
description: 本地用户的 ID。 32 位无符号整数，设置范围：0 到 (2<sup>32</sup>-1)。如果设为 0 服务器会自动分配一个 `uid`。
example:
cname: test
flag: 4096
key: 674664......82bb2a4
opid: 133
ts: 1575859207102
uid: 0
responses:
'200':
description: 操作成功。此处仅列出需要关注的字段。响应中还包含其他字段。
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: 错误码。0 表示请求成功，其他常见错误参考下表：
<table>
<tr>
<th>code</th>
<th>描述</th>
</tr>
<tr>
<td>1010100</td>
<td>flag 字段为 0。该字段必须设置为 4096。</td>
</tr>
<tr>
<td>1010101</td>
<td>flag 设置错误。该字段必须设置为 4096。</td>
</tr>
<tr>
<td>1010102</td>
<td>flag 设置错误。该字段必须设置为 4096。</td>
</tr>
<tr>
<td>1010200</td>
<td>请求的服务当前不可用。</td>
</tr>
<tr>
<td>1010212</td>
<td>WebRTC 服务当前不可用。</td>
</tr>
<tr>
<td>2010005</td>
<td>App ID 设置错误。</td>
</tr>
<tr>
<td>2010007</td>
<td>频道名不合法。</td>
</tr>
<tr>
<td>2010008</td>
<td>内部错误。</td>
</tr>
<tr>
<td>2010009</td>
<td>动态密钥验证失败。</td>
</tr>
<tr>
<td>2010010</td>
<td>动态密钥失效。生成密钥后需要在一天内使用，超过一天后使用会出现该错误。</td>
</tr>
<tr>
<td>2010011</td>
<td>注册的 App ID 未激活。</td>
</tr>
<tr>
<td>2010013</td>
<td>动态密钥服务过期。</td>
</tr>
<tr>
<td>2010014</td>
<td>未开启动态密钥鉴权，但是在 key 字段传入了动态密钥。</td>
</tr>
<tr>
<td>2010015</td>
<td>开启了动态密钥鉴权，但是在 key 字段传入了 App ID。</td>
</tr>
</table>
uid:
type: integer
description: 本地用户的 ID。
sid:
type: string
description: 用于标识通话的通话 ID。
server_domain:
type: string
description: 用于拉流/推流/上报数据的服务器地址。
example:
code: 0
uid: 3905114124
sid: 8B9 ...... B9F
server_domain: xxx.edge.agora.io
/pullstream/{cname}/{streamid}:
post:
summary: 拉取远端媒体流
description: 成功获取通话资源后，你可以调用该方法拉取远端用户的媒体流。
parameters:
- $ref: '#/components/parameters/channel'
- in: path
name: streamid
required: true
description: 要拉取的远端用户 ID。
schema:
type: integer
- $ref: '#/components/parameters/token'
requestBody:
$ref: '#/components/requestBodies/StreamBody'
responses:
'200':
description: 请求成功。
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: HTTP 状态码。
session:
type: string
description: 用于标识通话的通话 ID。
detail:
type: string
description: Answer SDP。
example:
code: 200
session: 8B9.......B9F
detail: v=0\r\no=- 0 0 ...... label:XrKNrJZpIqv0\r\n
'503':
description: 请求失败
content:
application/json:
schema:
$ref: '#/components/schemas/StreamFail'
example:
code: 503
session: 8B9.......B9F
detail: pull stream failed
/pushstream/{cname}/{streamid}:
post:
summary: 推送本地媒体流
description: 成功获取通话资源后，你可以调用该方法将本地用户的媒体流推送到频道中。
parameters:
- $ref: '#/components/parameters/channel'
- in: path
name: streamid
required: true
description: 本地用户 ID。即获取通话资源响应中的 `uid`。
schema:
type: integer
- $ref: '#/components/parameters/token'
requestBody:
$ref: '#/components/requestBodies/StreamBody'
responses:
'200':
description: 请求成功。
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: HTTP 状态码。
uid:
type: integer
description: 本地用户 ID，即获取通话资源响应中的 `uid`。
session:
type: string
description: 用于标识通话的通话 ID。
detail:
type: string
description: 请求成功返回 Answer SDP；请求失败返回具体的错误描述。
'504':
description: 请求失败
content:
application/json:
schema:
$ref: '#/components/schemas/StreamFail'
example:
code: 504
session: 8B9.......B9F
detail: push stream failed
/statsreport:
post:
summary: 上报通话质量
description: 开始拉流/推流后，你可以调用该方法向 Agora 上报通话质量相关的数据，方便调查问题。
> 我们推荐每 3 秒上报一次。
> 仅支持上报 `StatsReport.type` 为 `VideoBwe` 或者 `ssrc` 的 `StatsReport` 数据。
requestBody:
content:
application/json:
schema:
type: object
required:
- sid
- reports
properties:
sid:
type: string
description: 通话 ID。拉流/推流请求的响应中 `session` 的值。
reports:
type: array
description: 由 `StatsReport` 对象组成的数组。注意 `StatsReport` 对象必须要先转换为 JSON 格式。
items:
type: object
description: >
`StatsReport` 是 WebRTC API 直接导出的媒体质量对象，包括了编解码、ICE、连接候选、音视频流及带宽等质量信息，可以直接通过 `PeerConnection.getStats` 获取。
responses:
'200':
description: 请求成功。
content:
application/json:
schema:
type: object
properties:
session:
type: string
description: 通话 ID。
code:
type: integer
description: HTTP 状态码。
example:
session: 8B9......B9F
code: 200
'505':
description: 请求失败
content:
application/json:
schema:
$ref: '#/components/schemas/StreamFail'
example:
code: 505
session: 8B9.......B9F
detail: stats report failed
components:
schemas:
StreamFail:
type: object
properties:
code:
type: integer
description: HTTP 状态码。
session:
type: string
description: 用于标识通话的通话 ID。
detail:
type: string
description: 具体的错误描述。
requestBodies:
StreamBody:
description: >-
`device_vendor`, `device_model`, `os` 以及 `osVer` 的填写请参考下表。
<table>
<tr>
<th></th>
<th>Android</th>
<th>iOS</th>
<th>macOS</th>
<th>Web</th>
<th>Windows</th>
</tr>
<tr>
<td>device_vendor</td>
<td>android.os.Build.MANUFACTURER</td>
<td>"Apple"</td>
<td>"Apple"</td>
<td>UA</td>
<td>getPropertyValue(pclsObj, L"Manufacturer")</td>
</tr>
<tr>
<td>device_model</td>
<td>android.os.Build.MODEL</td>
<td>struct utsname systemInfo;uname(&systemInfo) systemInfo.machine</td>
<td>sysctlbyname("hw.model", buf, &length, NULL, 0);</td>
<td>-</td>
<td>getPropertyValue(pclsObj, L"Model")</td>
</tr>
<tr>
<td>os</td>
<td>"Android"</td>
<td>"iOS"</td>
<td>"macOS"</td>
<td>-</td>
<td>"Windows"</td>
</tr>
<tr>
<td>osVer</td>
<td>android.os.Build.VERSION.SDK_INT</td>
<td>[[[UIDevice currentDevice] systemVersion] UTF8String]</td>
<td>主版本：[[NSProcessInfo processInfo] operatingSystemVersion].majorVersion子版本：[[NSProcessInfo processInfo] operatingSystemVersion].minorVersion补丁版本：[[NSProcessInfo processInfo] operatingSystemVersion].patchVersion</td>
<td>-</td>
<td>sprintf(verStr, "Windows %d.%d.%d", osvi.dwMajorVersion, osvi.dwMinorVersion, osvi.dwBuildNumber);</td>
</tr>
</table>
required: true
content:
application/json:
schema:
type: object
required:
- ap_response
- sdp
properties:
ap_response:
type: string
description: 字符串内容为请求通话资源得到的响应包体。
sdp:
type: string
description: Offer SDP，浏览器中可以通过 `RTCPeerConnection.createOffer().sdp `得到。
device_vendor:
type: string
description: 使用的设备类型。
device_model:
type: string
description: 使用的设备型号。
os:
type: string
description: 使用的操作系统。
osVer:
type: string
description: 使用的操作系统版本。
example:
device_vendor:
device_model:
os:
os_ver:
ap_response: {xxx}
sdp: v=0\r\no=- 505525827083 ... 24 ulpfec/90000\r\n
parameters:
channel:
name: cname
in: path
required: true
description: 请求通话资源时填写的频道名，不超过 64 字节。
schema:
type: string
format: ascii
token:
name: accessToken
in: query
required: true
description: 请求通话资源使用的 `key`。
schema:
type: string