查询房间列表_实时音视频 SparkRTC_服务端API参考_数据统计分析_华为云

(1)

实时音视频

API 参考

文档版本 01

发布日期 2022-01-27

(2)

非经本公司书面许可，任何单位和个人不得擅自摘抄、复制本文档内容的部分或全部，并不得以任何形式传播。

商标声明

和其他华为商标均为华为技术有限公司的商标。

本文档提及的其他所有商标或注册商标，由各自的所有人拥有。

注意

您购买的产品、服务或特性等应受华为公司商业合同和条款的约束，本文档中描述的全部或部分产品、服务或特性可能不在您的购买或使用范围之内。除非合同另有约定，华为公司对本文档内容不做任何明示或暗示的声明或保证。

由于产品版本升级或其他原因，本文档内容会不定期进行更新。除非另有约定，本文档仅作为使用指导，本文档中的所有陈述、信息和建议不构成任何明示或暗示的担保。

(3)

1 ^{使用前必读}

概述

华为云实时音视频服务（SparkRTC）凭借在视频业务领域长期技术积累，快速为行业提供高并发、低延迟、高清流畅、安全可靠的全场景、全互动、全实时的音视频服务，适用于在线教育、云会议、社交文娱等场景。

您可以使用本文档提供的API对华为云实时音视频服务进行相关操作，如应用管理、合流任务管理等。支持的全部操作请参见API概览。

在调用华为云实时音视频服务的API之前，请确保已经充分了解华为云实时音视频服务的相关概念，详细信息请参见产品介绍。

调用说明

实时音视频提供了REST（Representational State Transfer）风格API，支持您通过 HTTPS请求调用，调用方法请参见如何调用API。

终端节点

终端节点即调用API的请求地址，SparkRTC部署时不区分物理区域，为全局服务。因此，SparkRTC的终端节点如表1-1所示。

表1-1 SparkRTC 的终端节点

区域名称区域终端节点（Endpoint）

所有 ALL rtc-api.myhuaweicloud.com

约束与限制

华为云实时音视频服务设置了API流量控制，避免因短时间内重复调用API导致服务中断的情况出现。API流控限制说明如表1-2所示。

API 参考 1 使用前必读

(6)

表1-2 API 流控限制

接口分类接口名称接口流控

应用管理 ● 创建应用

● 查询应用列表

● 查询单个应用

● 删除应用

● 启用应用

● 停用应用

60次/分钟

录制规则管理 ● 创建或更新录制规则

● 查询录制规则列表

● 查询录制规则

● 更新录制规则

● 删除录制规则

自动录制配置 ● 更新自动录制配置

● 查询自动录制配置

应用回调管理 ● RTC增值（录制）事件

回调配置

● 查询增值（录制）事件回调配置

合流任务管理 ● 启动合流任务

● 查询合流任务

● 修改合流任务

● 停止合流任务

10次/秒

单流任务管理 ● 启动单流任务

● 查询单流任务状态

● 停止单流任务

(7)

接口分类接口名称接口流控

数据统计分析 ● 查询房间列表

● 查询用户列表

● 查询实时规模

● 查询实时规模分布

● 查询实时质量数据

● 查询实时网络

● 查询用量

● 查询历史规模

● 查询历史质量

● 查询用户通话指标

● 查询用户异常体验事件

● 查询用户异常体验事件分布

30次/分钟

(8)

2 ^{API 概览}

华为云实时音视频服务对应的接口列表如下所示，在调用媒体处理API前，您需要先获取用户Token，Token可以用于调用其他API时鉴权，具体如何调用媒体处理API请参考应用示例。

应用管理接口

表2-1 应用管理接口

接口说明

POST /v2/apps 创建应用

GET /v2/apps 查询应用列表

GET /v2/apps/{app_id} 查询单个应用 DELETE /v2/apps/{app_id} 删除应用 POST /v2/apps/{app_id}/enable 启用应用 POST /v2/apps/{app_id}/disable 停用应用

录制规则管理接口

表2-2 录制规则管理接口

接口说明

POST /v2/apps/{app_id}/record-rules 创建或更新录制规则 GET /v2/apps/{app_id}/record-rules 查询录制规则列表 GET /v2/apps/{app_id}/record-rules/

{rule_id} 查询录制规则

PUT /v2/apps/{app_id}/record-rules/

{rule_id} 更新录制规则

API 参考 2 API 概览

(9)

接口说明 DELETE /v2/apps/{app_id}/record-

rules/{rule_id} 删除录制规则

自动录制配置

表2-3 自动录制配置接口

接口说明

PUT /v2/apps/{app_id}/auto-record-

mode 更新自动录制配置

GET /v2/apps/{app_id}/auto-record-

mode 查询自动录制配置

应用回调管理接口

表2-4 应用回调管理接口

接口说明

PUT /v2/apps/{app_id}/record-callback 配置增值（录制）事件回调 GET /v2/apps/{app_id}/record-callback 查询增值（录制）事件回调配置

合流任务管理接口

表2-5 合流任务管理接口

接口说明

POST /v2/apps/{app_id}/mix-stream-

jobs 启动合流任务

GET /v2/apps/{app_id}/mix-stream-

jobs/{job_id} 查询合流任务

PUT /v2/apps/{app_id}/mix-stream-

jobs/{job_id} 修改合流任务

DELETE /v2/apps/{app_id}/mix-stream-

jobs/{job_id} 停止合流任务

(10)

单流任务管理接口

表2-6 单流任务管理接口

接口说明

POST /v2/apps/{app_id}/individual-

stream-jobs 启动单流任务

GET /v2/apps/{app_id}/individual-

stream-jobs/{job_id} 查询单流任务状态 DELETE /v2/apps/{app_id}/individual-

stream-jobs/{job_id} 停止单流任务

数据统计分析接口

表2-7 数据统计分析接口

接口说明

GET /v1/{project_id}/rtc/rooms 查询房间列表 GET /v1/{project_id}/rtc/users 查询用户列表 GET /v1/{project_id}/rtc/realtime/

scale 查询实时规模

GET /v1/{project_id}/rtc/realtime/

scale/dimension 查询实时规模分布 GET /v1/{project_id}/rtc/realtime/

quality 查询实时质量数据

GET /v1/{project_id}/rtc/realtime/

network 查询实时网络

GET /v1/{project_id}/rtc/history/usage 查询用量 GET /v1/{project_id}/rtc/history/scale 查询历史规模 GET /v1/{project_id}/rtc/history/

quality 查询历史质量

GET /v1/{project_id}/rtc/client/qos/

details 查询用户通话指标

GET /v1/rtc/data/abnormal-event 查询用户异常体验事件 GET /v1/rtc/data/abnormal-event/

dimension 查询用户异常体验事件分布

(11)

3 ^{如何调用 API}

3.1 构造请求 3.2 认证鉴权 3.3 返回结果

3.1 构造请求

本节介绍REST API请求的组成，并以调用IAM服务的获取用户Token说明如何调用 API，该API获取用户的Token，Token可以用于调用其他API时鉴权。

您还可以通过这个视频教程了解如何构造请求调用API：https://

bbs.huaweicloud.com/videos/102987。

请求 URI

请求URI由如下部分组成：

{URI-scheme}://{Endpoint}/{resource-path}?{query-string}

尽管请求URI包含在请求消息头中，但大多数语言或框架都要求您从请求消息中单独传递它，所以在此单独强调。

表3-1 URI 中的参数说明

参数描述

URI-scheme 表示用于传输请求的协议，当前所有API均采用HTTPS协议。

Endpoint 指定承载REST服务端点的服务器域名或IP，不同服务不同区域的 Endpoint不同，您可以从地区和终端节点获取。

例如IAM服务在“华北-北京四 ”区域的Endpoint为“iam.cn- north-4.myhuaweicloud.com”。

resource-path 资源路径，也即API访问路径。从具体API的URI模块获取，例如

“获取用户Token”API的resource-path为“/v3/auth/tokens”。

API 参考 3 如何调用 API

(12)

参数描述

query-string 查询参数，是可选部分，并不是每个API都有查询参数。查询参数前面需要带一个“?”，形式为“参数名=参数取值”，例如“?

limit=10”，表示查询不超过10条数据。

例如您需要获取IAM在“华北-北京四”区域的Token，则需使用“华北-北京四”区域的Endpoint（iam.cn-north-4.myhuaweicloud.com），并在获取用户Token的URI部分找到resource-path（/v3/auth/tokens），拼接起来如下所示。

https://iam.cn-north-4.myhuaweicloud.com/v3/auth/tokens

图3-1 URI 示意图

说明

为查看方便，在每个具体API的URI部分，只给出resource-path部分，并将请求方法写在一起。

这是因为URI-scheme都是HTTPS，而Endpoint在同一个区域也相同，所以简洁起见将这两部分省略。

请求方法

HTTP请求方法（也称为操作或动词），它告诉服务你正在请求什么类型的操作。

表3-2 HTTP 方法

方法说明

GET 请求服务器返回指定资源。

PUT 请求服务器更新指定资源。

POST 请求服务器新增资源或执行特殊操作。

DELETE 请求服务器删除指定资源，如删除对象等。

HEAD 请求服务器资源头部。

PATCH 请求服务器更新资源的部分内容。

当资源不存在的时候，PATCH可能会去创建一个新的资源。

在获取用户Token的URI部分，您可以看到其请求方法为“POST”，则其请求为：

POST https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens

(13)

请求消息头

附加请求头字段，如指定的URI和HTTP方法所要求的字段。例如定义消息体类型的请求头“Content-Type”，请求鉴权信息等。

详细的公共请求消息头字段请参见表3-3。

表3-3 公共请求消息头

名称描述是否必选示例

Host 请求的服务器信

息，从服务API的 URL中获取。值为 hostname[:port]。

端口缺省时使用默认的端口，https的默认端口为443。

否

使用AK/SK认证时该字段必选。

code.test.com or

code.test.com:443

Content-Type 消息体的类型（格式）。推荐用户使用默认值application/json，

有其他取值时会在具体接口中专门说明。

是 application/json

Content-

Length 请求body长度，单

位为Byte。否 3495

X-Project-Id project id，项目编号。请参考12.3 获取项目ID章节获取项目编号。

否

如果是专属云场景采用AK/SK认证方式的接口请求或者多project 场景采用AK/SK认证的接口请求，则该字段必选。

e9993fc787d94b6c886cb aa340f9c0f4

X-Auth-Token 用户Token。

用户Token也就是调用获取用户Token接口的响应值，该接口是唯一不需要认证的接口。

请求响应成功后在响应消息头

（Headers）中包含的“X-Subject- Token”的值即为 Token值。

否

使用Token认证时该字段必选。

注：以下仅为Token示例片段

MIIPAgYJKoZIhvcNAQcCo ...ggg1BBIINPXsidG9rZ

(14)

说明

API同时支持使用AK/SK认证，AK/SK认证是使用SDK对请求进行签名，签名过程会自动往请求中添加Authorization（签名认证信息）和X-Sdk-Date（请求发送的时间）请求头。

AK/SK认证的详细说明请参见3.2 认证鉴权的“AK/SK认证”。

对于获取用户Token接口，由于不需要认证，所以只添加“Content-Type”即可，添加消息头后的请求如下所示。

POST https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens Content-Type: application/json

请求消息体（可选）

该部分可选。请求消息体通常以结构化格式（如JSON或XML）发出，与请求消息头中 Content-Type对应，传递除请求消息头之外的内容。若请求消息体中的参数支持中文，则中文字符必须为UTF-8编码。

每个接口的请求消息体内容不同，也并不是每个接口都需要有请求消息体（或者说消息体为空），GET、DELETE操作类型的接口就不需要消息体，消息体具体内容需要根据具体接口而定。

对于获取用户Token接口，您可以从接口的请求部分看到所需的请求参数及参数说明。将消息体加入后的请求如下所示，加粗的斜体字段需要根据实际值填写，其中

username

为用户名，

domainname

为用户所属的帐号名称，

********

为用户登录密码，

xxxxxxxxxxxxxxxxxx

为project的名称，如“cn-north-1”，您可以从地区和终端节点获取。

说明

scope参数定义了Token的作用域，下面示例中获取的Token仅能访问project下的资源。您还可以设置Token的作用域为某个帐号下所有资源或帐号的某个project下的资源，详细定义请参见获取用户Token。

POST https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens Content-Type: application/json

{ "auth": { "identity": { "methods": [ "password"

],

"password": { "user": {

"name": "username", "password": "********", "domain": {

"name": "domainname"

} } } }, "scope": { "project": {

"name": "xxxxxxxxxxxxxxxxxx"

} } } }

到这里为止这个请求需要的内容就具备齐全了，您可以使用curl、Postman或直接编写代码等方式发送请求调用API。对于获取用户Token接口，返回的响应消息头中“x-

(15)

subject-token”就是需要获取的用户Token。有了Token之后，您就可以使用Token认证调用其他API。

3.2 认证鉴权

调用接口有如下两种认证方式，您可以选择其中一种进行认证鉴权。

● Token认证：通过Token认证调用请求。

● AK/SK认证：通过AK（Access Key ID）/SK（Secret Access Key）加密调用请求。

推荐使用AK/SK认证，其安全性比Token认证要高。

Token 认证

说明

Token的有效期为24小时，需要使用一个Token鉴权时，可以先缓存起来，避免频繁调用。

Token在计算机系统中代表令牌（临时）的意思，拥有Token就代表拥有某种权限。

Token认证就是在调用API的时候将Token加到请求消息头，从而通过身份认证，获得操作API的权限。Token可通过调用获取用户Token接口获取。

云服务存在两种部署方式：项目级服务和全局级服务。其中：

● 项目级服务需要获取项目级别的Token，此时请求body中auth.scope的取值为 project。

● 全局级服务需要获取全局级别的Token，此时请求body中auth.scope的取值为 domain。

调用本服务API需要项目级别的Token，即调用获取用户Token接口时，请求body中 auth.scope的取值需要选择project，如下所示。

{ "auth": { "identity": { "methods": [ "password"

],

"name": "username", "password": "********", "domain": {

"name": "domainname"

} } } }, "scope": { "project": {

"name": "xxxxxxxx"

} } } }

获取Token后，再调用其他接口时，您需要在请求消息头中添加“X-Auth-Token”，

其值即为Token。例如Token值为“ABCDEFJ....”，则调用接口时将“X-Auth-Token:

ABCDEFJ....”加到请求消息头即可，如下所示。

POST https://iam.cn-north-1.myhuaweicloud.com/v3/auth/projects Content-Type: application/json

(16)

您还可以通过这个视频教程了解如何使用Token认证：https://

bbs.huaweicloud.com/videos/101333。

AK/SK 认证

说明

AK/SK签名认证方式仅支持消息体大小12MB以内，12MB以上的请求请使用Token认证。

AK/SK认证就是使用AK/SK对请求进行签名，在请求时将签名信息添加到消息头，从而通过身份认证。

● AK（Access Key ID）：访问密钥ID。与私有访问密钥关联的唯一标识符；访问密钥ID和私有访问密钥一起使用，对请求进行加密签名。

● SK（Secret Access Key）：与访问密钥ID结合使用的密钥，对请求进行加密签名，可标识发送方，并防止请求被修改。

使用AK/SK认证时，您可以基于签名算法使用AK/SK对请求进行签名，也可以使用专门的签名SDK对请求进行签名。详细的签名方法和SDK使用方法请参见API签名指南。

说明

签名SDK只提供签名功能，与服务提供的SDK不同，使用时请注意。

3.3 返回结果

状态码

请求发送以后，您会收到响应，包含状态码、响应消息头和消息体。

状态码是一组从1xx到5xx的数字代码，状态码表示了请求响应的状态，完整的状态码列表请参见12.1 状态码。

对于获取用户Token接口，如果调用后返回状态码为“201”，则表示请求成功。

响应消息头

对应请求消息头，响应同样也有消息头，如“Content-type”。

对于获取用户Token接口，返回如图3-2所示的消息头，其中“x-subject-token”就是需要获取的用户Token。有了Token之后，您就可以使用Token认证调用其他API。

(17)

图3-2 获取用户 Token 响应消息头

响应消息体（可选）

该部分可选。响应消息体通常以结构化格式（如JSON或XML）返回，与响应消息头中 Content-Type对应，传递除响应消息头之外的内容。

对于获取用户Token接口，返回如下消息体。为篇幅起见，这里只展示部分内容。

{ "token": {

"expires_at": "2019-02-13T06:52:13.855000Z", "methods": [

"password"

],

"catalog": [ {

"endpoints": [ {

"region_id": "az-01", ...

当接口调用出错时，会返回错误码及错误信息说明，错误响应的Body体格式如下所示。

{ "error_msg": "The format of message is error", "error_code": "AS.0001"

}

其中，error_code表示错误码，error_msg表示错误描述信息。

(18)

4 ^应用示例

4.1 示例1：创建单流录制任务 4.2 示例2：创建合流录制任务

4.1 示例 1：创建单流录制任务

场景描述

若您需要对某一个房间的实时音视频进行录制，可以在加入房间后，调用录制接口创建单流录制任务。

前提条件

● 已获取需要使用的SparkRTC服务的终端节点rtc-api.myhuaweicloud.com。

● 已创建用于存储录制文件的OBS桶。可以通过调用OBS 创建桶API进行创建，并在SparkRTC控制台完成OBS桶授权。

API 参考 4 应用示例

(19)

总体流程

1. 获取用户Token

2. 创建SparkRTC应用

3. 创建录制规则

4. 配置录制回调

5. 终端用户加入SparkRTC房间

6. 创建单流录制任务

操作步骤

步骤1 获取用户Token，用于调用SparkRTC接口时进行认证鉴权。

在“我的凭证”页面获取

username

、

password

、

domainname

，调用如下接口获取 Token。详细信息请参见3.1 构造请求。

POST https://iam.myhuaweicloud.com/v3/auth/tokens Content-Type: application/json

{ "auth": { "identity": { "methods": [

(20)

],

"name": "username", //用户名。

"password": "password", //用户登录密码。

"domain": {

"name": "domainname" //用户所属的账号名。

} } } }, "scope": { "domain": {

} } }}

如图4-1所示，红框中的信息为获取用户Token。

图4-1 获取用户 Token

步骤2 调用创建应用接口创建SparkRTC应用。

1. 选择POST请求方法并输入URI。

https://rtc-api.myhuaweicloud.com/v2/apps

2. 请求消息头中增加“X-Auth-Token”，值设置为步骤1中获取的用户Token。

3. Request Body中传入如下参数：

{ "app_name" : "rtctest"

}

4. 请求响应成功后，返回已创建应用的ID。

{ "app_id": "5ff9701f2346968bb306cb43", }

步骤3 调用创建或更新录制规则接口，创建录制规则。

https://rtc-api.myhuaweicloud.com/v2/apps/{app_id}/record-rules

{ "obs_addr": {

(21)

"bucket": "obsName", "location": "cn-north-4", "object": "Record/",

"project_id": "01234567890123456789012345678901"

},

"record_formats": ["MP4"], "mp4_config": {}

}

4. 请求响应成功后，返回已创建的录制规则。

{ "app_id": "5ff9701f2346968bb306cb43",

"rule_id": "5d0ec2c53a2c15625017adb8bbbcd9ab", "create_time": "2021-04-21T10:29:33Z",

"hls_config": { "record_cycle": 0,

"record_max_duration_to_merge_file": 0 },

"mp4_config": { "record_cycle": 7200,

"record_max_duration_to_merge_file": 0,

"record_prefix": "Record/{publish_domain}/{app}/{record_type}/{record_format}/

{stream}_{file_start_time}/{stream}_{file_start_time}"

},

"obs_addr": {

"project_id": "01234567890123456789012345678901"

},

"record_formats": [ "MP4"

],

"update_time": "2021-04-21T10:29:33Z"

}

步骤4 调用RTC增值（录制）事件回调配置接口，配置录制回调。

1. 选择PUT请求方法并输入URI。

https://rtc-api.myhuaweicloud.com/v2/apps/{app_id}/record-callback

{ "url": "http://mydomain.com/callback",

"auth_key": "8923ab8c2dcef4538923ab8c2dcef453"

}

4. 请求响应成功后，返回已创建的回调信息。

{ "app_id": "5ff9701f2346968bb306cb43", "record_callback": {

"auth_key": "8923ab8c2dcef4538923ab8c2dcef453", "update_time": "2021-04-07T12:05:18.0718Z", "url": "http://mydomain.com/callback", "notify_event_subscription": [

"RECORD_NEW_FILE_START", "RECORD_FILE_COMPLETE", "CLOUD_RECORD_OVER"

] } }

步骤5 终端用户通过SparkRTC APP加入某个SparkRTC房间，SparkRTC APP的集成开发请参见客户端SDK，您也可以直接使用SparkRTC Demo进行验证。

步骤6 调用启动单流任务接口，创建录制任务。

(22)

https://rtc-api.myhuaweicloud.com/v2/apps/{app_id}/individual-stream-jobs

{ "room_id": "room001", "user_id": "user001", "is_record_audio": true,

"video_type": "CAMERASTREAM", "resolution": "1280*720",

"resolution_policy": "DOWNWARD", "max_idle_time": 30,

"record_param": {

"record_rule_id": "5d0ec2c53a2c15625017adb8bbbcd9ab"

} }

4. 请求响应成功后，返回录制任务信息。

{ "app_id": "5ff9701f2346968bb306cb43", "create_time": "2021-04-21T10:51:55Z", "is_record_audio": true,

"job_id": "607f87cf00d861eeefffa6c88054cdab", "job_unique_id": "a77bb33dbdc948d8", "max_idle_time": 30,

"push_param": { "rtmp_urls": null },

"record_files": null, "record_param": {

},

"resolution_policy": "DOWNWARD", "resolution": "1280*720",

"room_id": "room001",

"start_time": "2021-04-21T10:51:55Z", "state": "INIT",

"stop_time": "0001-01-01T00:00:00Z",

"stream_name": "s_607f87cf00d861eeefffa6c88054cdab_room001_user001", "update_time": "2021-04-21T10:51:55Z",

"user_id": "user001",

"video_type": "CAMERASTREAM"

}

步骤7 SparkRTC房间结束音视频互动后，您可以在配置的OBS桶中获取录制文件。

----结束

4.2 示例 2：创建合流录制任务

场景描述

4.1 示例1：创建单流录制任务已介绍了如何将房间中的每一个用户的音视频流分别录 制成独立的文件。若您需要将房间中的多个单流用户录制成一个文件，您可以参考此章节内容调用SparkRTC API进行合流录制。

前提条件

● 已获取需要使用的SparkRTC服务的终端节点rtc-api.myhuaweicloud.com。

● 已创建用于存储录制文件的OBS桶。可以通过调用OBS 创建桶API进行创建，并在SparkRTC控制台完成OBS桶授权。

(23)

总体流程

1. 获取Token

2. 创建应用

3. 创建录制规则

4. 配置录制回调

5. 终端用户加入房间

6. 创建合流录制任务

操作步骤

步骤1 获取用户Token，用于调用SparkRTC接口时进行认证鉴权。

在“我的凭证”页面获取

username

、

password

、

domainname

，调用如下接口获取 Token。详细信息请参见3.1 构造请求。

POST https://iam.myhuaweicloud.com/v3/auth/tokens Content-Type: application/json

{ "auth": { "identity": { "methods": [

(24)

],

"name": "username", //用户名。

"password": "password", //用户登录密码。

"domain": {

} } } }, "scope": { "domain": {

} } }}

如图4-2所示，红框中的信息为获取用户Token。

图4-2 获取用户 Token

步骤2 调用创建应用接口创建SparkRTC应用。

https://rtc-api.myhuaweicloud.com/v2/apps

{ "app_name" : "rtctest"

}

4. 请求响应成功后，返回已创建应用的ID。

{ "app_id": "5ff9701f2346968bb306cb43", }

步骤3 调用创建或更新录制规则接口，创建录制规则。

https://rtc-api.myhuaweicloud.com/v2/apps/{app_id}/record-rules

{ "obs_addr": {

(25)

"project_id": "01234567890123456789012345678901"

},

"record_formats": ["MP4"], "mp4_config": {}

}

4. 请求响应成功后，返回已创建的录制规则。

{ "app_id": "5ff9701f2346968bb306cb43",

"rule_id": "5d0ec2c53a2c15625017adb8bbbcd9ab", "create_time": "2021-04-21T10:29:33Z",

"hls_config": { "record_cycle": 0,

"record_max_duration_to_merge_file": 0 },

"mp4_config": { "record_cycle": 7200,

"record_max_duration_to_merge_file": 0,

"record_prefix": "Record/{publish_domain}/{app}/{record_type}/{record_format}/

{stream}_{file_start_time}/{stream}_{file_start_time}"

},

"obs_addr": {

"project_id": "01234567890123456789012345678901"

},

"record_formats": [ "MP4"

],

"update_time": "2021-04-21T10:29:33Z"

}

步骤4 调用RTC增值（录制）事件回调配置接口，配置录制回调。

1. 选择PUT请求方法并输入URI。

https://rtc-api.myhuaweicloud.com/v2/apps/{app_id}/record-callback

{ "url": "http://mydomain.com/callback",

"auth_key": "8923ab8c2dcef4538923ab8c2dcef453"

}

4. 请求响应成功后，返回已创建的回调信息。

{ "app_id": "5ff9701f2346968bb306cb43", "record_callback": {

"auth_key": "8923ab8c2dcef4538923ab8c2dcef453", "update_time": "2021-04-07T12:05:18.0718Z", "url": "http://mydomain.com/callback", "notify_event_subscription": [

"RECORD_NEW_FILE_START", "RECORD_FILE_COMPLETE", "CLOUD_RECORD_OVER"

] } }

步骤5 终端用户通过SparkRTC APP加入某个SparkRTC房间，SparkRTC APP的集成开发请参见客户端SDK，您也可以直接使用SparkRTC Demo进行验证。

步骤6 调用启动合流任务接口，创建录制任务。

(26)

https://rtc-api.myhuaweicloud.com/v2/apps/{app_id}/mix-stream-jobs

{ "mix_param": {

"encode_template": "1920x1080_30_4620", "max_idle_time": 30,

"layout_template": "nine_grids_view" //若视频布局为屏幕共享，则填写为screen_share_left或 screen_share_right。

},

"record_param": {

} }

layout_template：视频布局模板编号。

– nine_grids_view：九宫格模板（自适应模板）。

每个用户画面平铺在画布上，大小一致。根据用户数量，动态调整每个画面的大小和位置，最多支持25个画面。不同人数的实际布局效果如下图所示：

▪

如果实际视频流的宽高比与视窗的宽高比不一致，则视频画面会裁剪以适配视窗的大小。

▪

如果中途有流退出房间，则该条流的画面会被后进入房间的流顶替。

▪

如果房间内的人数不足，则剩余位置显示背景色。

▪

如果用户只发送音频，仍然会占用画面位置。

▪

支持背景图，如果房间内人数不足，则显示背景图。

– screen_share_left、screen_share_right：主视图在左边、右边的屏幕共享 模板（自适应模板）。

屏幕分享（或者主讲人摄像头画面）始终占据屏幕左侧或者右侧大画面位置，其他用户依次垂直排列于旁边，最多支持17个画面。不同人数的实际布局效果如下图所示：

(27)

▪

大视窗画面，可选择主讲摄像头流或共享屏幕流。

▪

大视窗画面，显示指定的UID用户的视频，如果未指定或者指定用户未进入频道，则大视窗区域显示背景色。

▪

左侧大视窗为了保持内容的完整性采用缩放方式处理，右侧小视窗采用裁剪方式适配视窗的大小。

▪

右侧小视窗画面按照加入房间的时间先后顺序排列。

▪

右侧小视窗有流退出房间，则该条流的画面会被后进入房间的流顶替。

▪

如果房间内的人数不足，则剩余位置显示背景色。

(28)

▪

如果用户只发送音频，仍然会占用画面位置。

▪

支持背景图，如果房间内人数不足，则显示背景图。

4. 请求响应成功后，返回合流录制任务信息。

{ "app_id": "5ff9701f2346968bb306cb43", "create_time": "2021-04-21T11:47:32Z", "job_id": "607f9fc100d861eeefff9b300b388dab", "job_unique_id": "87b1f2b8da9c44cd",

"mix_param": {

"layout_template": "nine_grids_view", "encode_template": "1920x1080_30_4620", "max_idle_time": 30

},

"push_param": { "rtmp_urls": null },

"record_param": {

},

"start_time": "2021-04-21T11:47:32Z", "state": "INIT",

"stop_time": "0001-01-01T00:00:00Z",

"stream_name": "m_607f9fc100d861eeefff9b300b388dab_room001", "update_time": "2021-04-21T11:47:32Z"

}

步骤7 SparkRTC房间结束音视频互动后，您可以在配置的OBS桶中获取录制文件。

----结束

(29)

5 ^应用管理

5.1 创建应用 5.2 查询应用列表 5.3 查询单个应用 5.4 删除应用 5.5 启用应用 5.6 停用应用

5.1 创建应用

功能介绍

调用此接口创建应用。

接口约束

不支持同一租户创建多个app_name相同的应用。

调试

您可以在API Explorer中调试该接口。

URI

POST /v2/apps

API 参考 5 应用管理

(30)

请求参数

表5-1 请求 Header 参数

参数是否必选参数类型描述

Content-Type 是 String 内容类型。

X-Auth-Token 否 String 用户Token。使用Token鉴权方式时必选。通过调用IAM服务获取用户Token接口获取（响应消息头中X-Subject-Token的值）。

Authorization 否 String 使用AK/SK方式认证时必选，携带的鉴权信息。

X-Sdk-Date 否 String 使用AK/SK方式认证时必选，请求的发生时间。

X-Project-Id 否 String 使用AK/SK方式认证时必选，携带项目ID信息。

表5-2 请求 Body 参数

app_name 是 String app名称，仅支持填入utf8格式内容

响应参数

状态码： 201

表5-3 响应 Header 参数

参数参数类型描述

X-request-Id String 此字段携带请求ID号，以便任务跟踪。

表5-4 响应 Body 参数

app_id String 应用id

状态码： 400

(31)

error_code String 错误码 error_msg String 错误描述

状态码： 500

请求示例

POST https://rtc-api.myhuaweicloud.com/v2/apps { "app_name" : "rtc"

}

响应示例

状态码： 201

创建成功，返回应用app_id

{ "app_id" : "60d539ba00d861ef0802742ce404400c"

}

状态码： 400

语义有误，当前请求无法被服务器理解，或参数有误

(32)

{ "error_code" : "RTC.00001003", "error_msg" : "InvalidParameterValue"

}

状态码： 500

请求失败，服务器端错误

{ "error_code" : "RTC.00002xxx", "error_msg" : "InternalError"

}

状态码

状态码描述

201 创建成功，返回应用app_id

400 语义有误，当前请求无法被服务器理解，或参数有误 500 请求失败，服务器端错误

错误码

请参见错误码。

5.2 查询应用列表

功能介绍

调用此接口查询应用列表。

调试

URI

GET /v2/apps

表5-9 Query 参数

state 否 String 应用的状态：

● ACTIVATION：应用开启

● DEACTIVATION：应用停用

● ARREARS：应用欠费

(33)

offset 否 Integer 查询结果起始编号，此处代表分

页的页码，默认为0。

limit 否 Integer 查询结果集数量，此处代表每一

页的条数，最小为1，最大为 100。默认为100。

请求参数

响应参数

状态码： 200

count Integer app的总数

(34)

参数参数类型描述 apps Array of App

objects app的列表

表5-13 App

app_name String app名称 app_id String 应用id state AppState

object app状态 scope String RTC覆盖范围。

取值如下：

● DOMESTIC：国内范围。

● OVERSEA：海外范围。

● GLOBAL：全球范围。

tenant_name String 账号名

domain String 域名，App对应域名 create_time String 创建时间，形如

“2006-01-02T15:04:05.075Z”，时区为：UTC authenticatio

n AppAuth

object 鉴权配置 callbacks AppCallbacks

object 回调配置 auto_record_

mode AppAutoReco

rdMode object

自动录制配置

表5-14 AppState

state String 状态

● ACTIVATION：开启

● DEACTIVATION：停用

● ARREARS：欠费

● DELETED：已删除

(35)

update_time String app鉴权的更新时间，形如

“2006-01-02T15:04:05.075Z”，时区为：UTC

表5-15 AppAuth

enable Boolean 开启或关闭URL鉴权

expire Integer 接入RTC建链认证时的signature的有效期。单位：秒。默认300秒。signature由app_key生成 app_key String app鉴权秘钥

“2006-01-02T15:04:05.075Z”，时区为：UTC

表5-16 AppCallbacks

push_callback AppCallback

Url object 转推回调 record_callbac

k AppCallback

Url object 录制回调

表5-17 AppCallbackUrl

url String 回调通知url地址，url必须以http://或https://开头，需要支持POST调用。

auth_key String 回调秘钥，主要用于鉴权。如果不设置或者为空，则回调不会增加鉴权头域字段。

notify_event_s

ubscription Array of

strings 订阅云端录制通知消息。

取值如下：

● RECORD_NEW_FILE_START：开始创建新的录制文件。

● RECORD_FILE_COMPLETE：录制文件生成完成。

update_time String 更新时间，形如

“2006-01-02T15:04:05.075Z”，时区为：

UTC。

(36)

表5-18 AppAutoRecordMode

mode String 录制模式。

● AUTO_RECORD_OFF：关闭自动录制。

● AUTO_INDIVIDUAL_RECORD：开启单流自动录制，此时record_rule_id必须非空。

record_rule_id String 录制规则id。

“2006-01-02T15:04:05.075Z”，时区为：

UTC。

状态码： 400

状态码： 500

error_code String 错误码

(37)

参数参数类型描述 error_msg String 错误描述

请求示例

GET https://rtc-api.myhuaweicloud.com/v2/apps

响应示例

状态码： 200 查询应用列表

{ "count" : 1, "apps" : [ {

"app_name" : "example",

"app_id" : "123456789abcdefghijklmno", "state" : {

"state" : "ACTIVATION",

"update_time" : "2020-07-26T07:03:05.075Z"

},

"scope" : "DOMESTIC",

"tenant_name" : "hwstaff_pub_videortc",

"domain" : "123456789abcdefghijklmno.rtc.huawei.com", "project_id" : "ad7456ce8ef89adf567",

"create_time" : "2020-07-26T07:03:05.075Z", "authentication" : {

"enable" : true, "expire" : 300,

"app_key" : "12345ABCDEF12345",

"update_time" : "2020-07-26T07:03:05.075Z"

},

"callbacks" : { "push_callback" : { "url" : "", "auth_key" : "", "update_time" : ""

},

"record_callback" : {

"url" : "http://mydomain.com", "auth_key" : "78912374ae8cdb38",

"update_time" : "2020-07-26T07:53:05.075Z"

} },

"auto_record_mode" : {

"mode" : "AUTO_RECORD_OFF",

"update_time" : "2020-07-26T07:53:05.075Z"

} } ] }

状态码： 400

}

状态码： 500

查询出错，服务器端错误

(38)

}

状态码

状态码描述

200 查询应用列表

400 语义有误，当前请求无法被服务器理解，或参数有误 500 查询出错，服务器端错误

错误码

5.3 查询单个应用

功能介绍

调用此接口查询单个应用详情。

调试

URI

GET /v2/apps/{app_id}

表5-23 路径参数

app_id 是 String 应用id

请求参数

(39)

响应参数

状态码： 200

app_name String app名称 app_id String 应用id state AppState

object app状态 scope String RTC覆盖范围。

取值如下：

● DOMESTIC：国内范围。

● OVERSEA：海外范围。

● GLOBAL：全球范围。

tenant_name String 账号名

domain String 域名，App对应域名 create_time String 创建时间，形如

“2006-01-02T15:04:05.075Z”，时区为：UTC

(40)

参数参数类型描述 authenticatio

n AppAuth

object 鉴权配置 callbacks AppCallbacks

object 回调配置 auto_record_

mode AppAutoReco

rdMode object

自动录制配置

state String 状态

● DELETED：已删除 update_time String app鉴权的更新时间，形如

“2006-01-02T15:04:05.075Z”，时区为：UTC

表5-28 AppAuth

enable Boolean 开启或关闭URL鉴权

expire Integer 接入RTC建链认证时的signature的有效期。单位：秒。默认300秒。signature由app_key生成 app_key String app鉴权秘钥

“2006-01-02T15:04:05.075Z”，时区为：UTC

表5-29 AppCallbacks

push_callback AppCallback

Url object 转推回调 record_callbac

k AppCallback

Url object 录制回调

(41)

表5-30 AppCallbackUrl

url String 回调通知url地址，url必须以http://或https://开头，需要支持POST调用。

auth_key String 回调秘钥，主要用于鉴权。如果不设置或者为空，则回调不会增加鉴权头域字段。

notify_event_s

ubscription Array of

strings 订阅云端录制通知消息。

取值如下：

● RECORD_NEW_FILE_START：开始创建新的录制文件。

● RECORD_FILE_COMPLETE：录制文件生成完成。

“2006-01-02T15:04:05.075Z”，时区为：

UTC。

表5-31 AppAutoRecordMode

mode String 录制模式。

● AUTO_RECORD_OFF：关闭自动录制。

● AUTO_INDIVIDUAL_RECORD：开启单流自动录制，此时record_rule_id必须非空。

record_rule_id String 录制规则id。

“2006-01-02T15:04:05.075Z”，时区为：

UTC。

状态码： 400

(42)

状态码： 404

状态码： 500

请求示例

GET https://rtc-api.myhuaweicloud.com/v2/apps/{app_id}

响应示例

状态码： 200

(43)

app详细信息

{ "app_name" : "example",

"app_id" : "123456789abcdefghijklmno", "state" : {

"update_time" : "2020-07-26T07:03:05.075Z"

}, "scope" : "DOMESTIC",

"tenant_name" : "hwstaff_pub_videortc",

"domain" : "123456789abcdefghijklmno.rtc.huawei.com", "project_id" : "ad7456ce8ef89adf567",

"create_time" : "2020-07-26T07:03:05.075Z", "authentication" : {

"enable" : true, "expire" : 300,

"app_key" : "12345ABCDEF12345",

"update_time" : "2020-07-26T07:03:05.075Z"

}, "callbacks" : { "record_callback" : {

"url" : "http://mydomain.com", "auth_key" : "78912374ae8cdb38",

"update_time" : "2020-07-26T07:53:05.075Z"

}

}, "auto_record_mode" : {

"mode" : "AUTO_RECORD_OFF",

"update_time" : "2020-07-26T07:53:05.075Z"

}}

状态码： 400

}

状态码： 404 app编号不存在

}

状态码： 500

查询失败，服务器端错误

}

状态码

状态码描述

200 app详细信息

400 语义有误，当前请求无法被服务器理解，或参数有误

(44)

状态码描述

404 app编号不存在

500 查询失败，服务器端错误

错误码

5.4 删除应用

功能介绍

调用此接口删除单个应用。

调试

URI

DELETE /v2/apps/{app_id}

表5-38 路径参数

请求参数

(45)

响应参数

状态码： 204

状态码： 400

状态码： 404

(46)

状态码： 500

请求示例

DELETE https://rtc-api.myhuaweicloud.com/v2/apps/{app_id}

响应示例

状态码： 400

删除失败，删除条件不满足

}

状态码： 404

删除失败，app编号不存在

}

状态码： 500

删除失败，服务器端错误

{ "error_code" : "RTC.00002xxx",

(47)

"error_msg" : "InternalError"

}

状态码

状态码描述

204 删除成功

400 删除失败，删除条件不满足 404 删除失败，app编号不存在 500 删除失败，服务器端错误

错误码

5.5 启用应用

功能介绍

调用此接口启用单个应用。

调试

URI

POST /v2/apps/{app_id}/enable

表5-47 路径参数

请求参数

(48)

响应参数

状态码： 200

app_id String 应用id state AppState

object 应用状态

state String 状态

● DELETED：已删除

(49)

“2006-01-02T15:04:05.075Z”，时区为：UTC

状态码： 404

状态码： 500

请求示例

POST https://rtc-api.myhuaweicloud.com/v2/apps/{app_id}/enable

响应示例

状态码： 200 启用成功

(50)

{ "app_id" : "123456789abcdefghijklmno", "state" : {

"update_time" : "2020-07-26T07:03:05.075Z"

}}

}

状态码： 500

设置失败，服务器端错误

}

状态码

状态码描述

200 启用成功

500 设置失败，服务器端错误

错误码

5.6 停用应用

功能介绍

调用此接口停用单个应用。

应用停用后，新房间无法新增和加入，已加入的房间可以继续使用。合流、录制功能等也不可用。

调试

URI

POST /v2/apps/{app_id}/disable

(51)

表5-56 路径参数

请求参数

响应参数

状态码： 200

app_id String 应用id state AppState

object 应用状态

(52)

state String 状态

● DELETED：已删除 update_time String app鉴权的更新时间，形如

“2006-01-02T15:04:05.075Z”，时区为：UTC

状态码： 404

状态码： 500

(53)

请求示例

POST https://rtc-api.myhuaweicloud.com/v2/apps/{app_id}/disable

响应示例

状态码： 200 停用成功

{ "app_id" : "123456789abcdefghijklmno", "state" : {

"state" : "DEACTIVATION",

"update_time" : "2020-07-26T07:03:05.075Z"

}}

}

状态码： 500

设置失败，服务器端错误

}

状态码

状态码描述

200 停用成功

500 设置失败，服务器端错误

错误码

(54)

6 ^{录制规则管理}

6.1 创建或更新录制规则 6.2 查询录制规则列表 6.3 查询录制规则 6.4 更新录制规则 6.5 删除录制规则

6.1 创建或更新录制规则

功能介绍

调用此接口创建或更新录制规则。

● 若当前app在请求的location中无录制规则，则会创建新的录制规则

● 若当前app在请求的location中已有录制规则，则会更新原来的录制规则

接口约束

一个app在一个location最多创建一个录制规则。

调试

URI

POST /v2/apps/{app_id}/record-rules

表6-1 路径参数

API 参考 6 录制规则管理

(55)

请求参数

表6-3 请求 Body 参数

obs_addr 是 RecordObsFil

eAddr object 保存录制文件所在的桶信息 record_format

s 是 Array of

strings 录制格式：支持HLS格式和MP4 格式（HLS和MP4为大写）。

● 若配置HLS则必须携带 HLSRecordConfig参数

● 若配置MP4则需要携带 MP4RecordConfig hls_config 否 HLSRecordCo

nfig object HLS格式录制规则管理 mp4_config 否 MP4RecordC

onfig object MP4格式录制规则管理

表6-4 RecordObsFileAddr

location 是 String OBS Bucket所在RegionID project_id 是 String OBS Bucket所在Region的项目

ID

API 参考 6 录制规则管理

查询房间列表_实时音视频 SparkRTC_服务端API参考_数据统计分析_华为云

实时音视频

API 参考

目 录

1 使用前必读... 1

2 API 概览... 4

3 如何调用 API...7

4 应用示例...14

5 应用管理...25

6 录制规则管理...50

7 自动录制配置...82

8 应用回调管理...91

9 合流任务管理...100

10 单流任务管理... 131

11 数据统计分析... 145

12 附录... 196

13 修订记录... 206

1 使用前必读

概述

调用说明

终端节点

约束与限制

2 API 概览

应用管理接口

录制规则管理接口

自动录制配置

应用回调管理接口

合流任务管理接口

单流任务管理接口

数据统计分析接口

3 如何调用 API

3.1 构造请求

请求 URI

请求方法

请求消息头

请求消息体（可选）

username

domainname

********

xxxxxxxxxxxxxxxxxx

3.2 认证鉴权

Token 认证

AK/SK 认证

3.3 返回结果

状态码

响应消息头

响应消息体（可选）

4 应用示例

4.1 示例 1：创建单流录制任务

场景描述

前提条件

总体流程

操作步骤

username

password

domainname

4.2 示例 2：创建合流录制任务

场景描述

前提条件

总体流程

操作步骤

username

password

domainname

▪

▪

▪

▪

▪

▪

▪

▪

▪

▪

▪

▪

▪

5 应用管理

5.1 创建应用

功能介绍

目录

1 ^{使用前必读}

2 ^{API 概览}

3 ^{如何调用 API}

4 ^应用示例

5 ^应用管理

6 ^{录制规则管理}