上屏系统-接口规范-ALL In One
Posted
tags:
篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了上屏系统-接口规范-ALL In One相关的知识,希望对你有一定的参考价值。
1.概述1.1.用途及阅读方法
上屏API是上屏系统的后台接口,管理平台界面实现需要遵循本接口规范。
1.2.通信协议
客户端和服务器通过HTTP协议通信,客户端使用HTTP GET方法或POST方法向服务器发送请求,服务器返回json格式的业务数据或操作结果给客户端。
尽管接口同时支持GET和POST方法,建议查询数据时使用GET方法,修改和添加数据时使用POST方法。
1.4.接口请求
接口的请求地址是个URL地址,每个接口URL地址都包括接口位置和请求参数,例如:
http://ip/res/?action=get&token=123456
其中:
http://ip/res/ 是接口请求的URL位置,“ip”在实际请求中要替换成服务器的ip地址或域名。
符号?后面是参数列表,以name=value的形式体现。
其中:
action参数是在所有接口中都要有的,该参数表明了请求业务的类型。
token参数提供一个安全认证符号给服务器,服务器用token来验证客户端的合法性,除了登录验证接口之外,其他接口都需要token参数。
所有参数都可以采用GET或POST方法提交。
在使用ajax做POST提交时,应当在接口位置结尾加上反斜杠"/",以免参数提交失败。如:http://ip/res/
有关URL地址的编码规范,请参考HTTP 1.1规范。
1.5.接口响应
服务器在收到接口请求后,首先判断token的正确性,如果token错误,则返回认证错误的消息给客户端。如果token正确,服务器返回json格式的文本内容给客户端。返回给客户端的json文本描述了服务器对请求的处理结果和响应数据。
1.6.接口安全
客户端必须首先通过身份认证才能继续调用接口,在一个“挑战—>应答”模式的身份认证过程中完成身份认证,认证通过后,服务器为客户端分配一个临时令牌token,在后续的请求中,token作为一项必选参数提供,服务器通过token识别用户身份和验证请求的合法性。
在没有接口调用时,token的有效期为30分钟,之后客户端再调用接口时必须重新进行身份认证,获取新的token。
为了确保一定的安全性,客户端应妥善保存token值。
1.7.URL编码
当URL请求参数值中包含URL地址保留字符时,应对参数值进行URL编码。
具体参见“RFC2396: Uniform Resource Identifiers (URI): Generic Syntax”。
当请求参数包含中文字符时,应对中文字符采用UTF-8编码。
1.8.描述约定
本文档在描述接口的URL地址时,如果没有特殊说明,会省略掉URL前面的相同部分。
例如,
http://ip/res/?action=get&token=123456 简化为 res/?action=get&token=123456,或者按如下方式描述:
接口: res
参数: action=get&token=123456
在描述参数时,省略token参数的描述,在示例中也会省略。在实际调用中必须把token参数加上。
在对参数进行描述时,用【必选】表示该参数必须提供,【保留】表示该参数可以接受但尚未被使用。
1.9.返回消息结构
返回的json消息数据结构具有严格的一致性,客户端可以采用一致的接收和解析方式处理返回消息。
简单消息
简单的返回消息包含对请求的处理结果,结构如下:
{
"code":0,
"err_desc":""
}
其中:
code 为 0 表示处理成功,其它值表示处理失败。
err_desc是对错误的描述,在code为0时err_desc会被省略。
特殊情况,在用户认证的login1和login2接口中,err_desc具有特殊用途用法,具体参见接口描述。除这两个接口之外,err_desc都表示错误描述。
带业务数据的消息
有的返回消息除了包含处理结果信息,还包含业务数据记录集,结构如下:
{
"code":0,
"data":{
"count":1,
"items":[{
"_id": "abcdef",
"server":"g3",
"ip":"127.0.0.1",
}]
}
}
其中:
data 业务数据的根节点:
count 业务数据的条数,可能的值为0 ~ n
items 业务数据,是一个数组,数据条数由count属性定义。当count为0时,items属性可能为null或者不存在。
本文档后续章节中,在描述items元素的属性时,会省略一些属性的描述,即实际调用接口返回的属性在本文档中可能会没有描述,这种情况下请直接忽略被忽略描述的属性值。本文档中描述的属性是实际返回内容的一个子集,没有描述到的内容对集成本系统没有影响。
带分页数据的消息
如果返回数据较多,服务器会对返回的数据进行分页,客户端可以按照页码请求指定范围的数据。带分页信息的返回数据结构如下:
{
"code":0,
"data":{
"page":1,
"page_size":"20",
"pages":"1",
"total":"2",
"count":2,
"items":[...]
}
}
分页数据信息在data元素下,意义如下:
page 当前页码
page_size 每页数据记录条数
pages 总共的页数
total 总数据条数
count 当前返回页的数据条数
如果返回的数据带有分页信息,则可以在调用接口时使用page参数来请求指定页码的数据。
1.10.主键和公共属性
接口返回的业务对象(资源、用户、设备等)数据,都包含一个_id属性,具有全局唯一性,是数据表的主键。在请求更新、删除接口时,需要传入对象的_id属性。接口要求在传入主键时使用id作为传入属性名。具体见接口定义部分。
所有业务对象都具备如下公共属性:
_id 主键,一个32位的字符串
ctime 创建时间,UNIX时间戳
mtime 修改时间,UNIX时间戳
state 状态
状态值:整数 1=正常,2=禁用
1.11.参考
[1] RFC 2616, Hypertext Transfer Protocol -- HTTP/1.1[S].
[2] RFC 3986, Uniform Resource Identifier (URI): Generic Syntax[S].
[3] http://www.json.org/ Introducing JSON
2.注册用户
注册一个新用户。
注册完成的用户是否可以登录和管理系统,由后台逻辑约定。
2.1.注册新用户
- 用途
注册新用户。 - 接口
user/?action=regedit
参数:
name=姓名&pwd=123&[email protected]&phone=13888888888&addr=北京
name 姓名
email 邮件地址,系统要求使用注册的邮件地址作为登录服务器的用户名。
pwd 用户密码,用于登录系统
phone 联系电话
addr 联系地址 - 响应
{ "code":0, "err_desc":"" }
3.登录认证
客户端调用流媒体服务器接口,首先要做的是身份认证,认证通过后才可以调用流媒体服务器的接口。
服务器和客户端通过“挑战->应答”方式(challenge-response)进行身份认证交互,在这个过程中,客户端需要调用两次接口向服务器证明身份。认证过程中不需要传递密码,密码用于签名验证。
身份认证的过如下:
1)客户端使用“用户名”作为参数调用“login1”接口,向服务器发出身份认证请求
1.1)服务器确认用户是否是有效的用户:
1.2)若不是,则不做进一步处理,返回错误信息
1.3)若是,服务器产生一个“随机数(挑战字符串)”发送给客户端
2)客户端使用“用户密码”和“随机数(挑战字符串)”作为输入,按约定的算法生成一个hash值,用该hash值作为 调用“login2”接口的参数,请求login2接口。
2.1)服务器用收到的hash值与自己的计算结果比较,若二者相同,则通过认证;否则,认证失败
2.2)若认证通过,服务器返回“token”给客户端,否者返回错误信息。
3.1.login1接口
- 用途
客户端向服务器申请进行身份认证,服务器返回“挑战字符串”给客户端。 - 请求
user/?action=login1&[email protected]
email 使用注册的邮件地址作为登录服务器的用户名。
- 响应
{ "code": 0, "data": { "count": 1, "items": [ { "id": "5ad55392e1382313ff021c3b", "chcode": "pum0odo40qu1tts5" } ] } }
code 等于0,表示用户有效,items段返回挑战数据:
?id 挑战识别编号,原样带入login2接口;
?chcode 挑战字符串。
code 不等于0,其他值表示错误,此时 err_desc 的内容是错误描述。
3.2.login2接口
- 用途
对login1接口返回“挑战字符串”进行hash运算,将运算结果提交给服务器,进行身份合法性认证。 - 请求
user/?action=login2&id=id&hash=8c96202be3da1b23a96c4c838eb34d93
id 由接口login1返回,原样带入。
hash是使用用户密码和挑战字符串作为输入计算出的md5摘要值(hash),算法如下:hash=md5(md5(password)+challenge_code)
算法描述:首先计算出密码的hash值,然后在生成的密码hash值尾部拼接上挑战字符串形成新的字符串,最后计算这个新字符串的hash值。
hash算法采用md5算法,生成的摘要采用16进制编码,编码生成的字符采用小写字母。
例如,字符串111111的hash值是 96e79218965eb72c92a549dd5a330112 - 响应
code >0 其他值表示错误,此时 err_desc 的内容是错误描述。
code 0 表示登录成功,在data数据段返回token和用户信息。
{
"code": 0,
"data": {
"count": 1,
"items": [
{
"_id": "5ad4594fe1382314030eabb2",
"name": "王见",
"email": "[email protected]",
"root": "5ad4594fe1382314030eabb2",
"phone": "13888888888",
"addr": "北京",
"token": "6df901hvwqj4rqsj"
}
]
}
}
_id 用户编号
name 用户名
email 邮件地址
phone 联系电话
addr 地址
token 认证令牌,用于请求后续接口
root 文档根目录的id,用于请求用户资源
3.3.logout接口
- 用途
退出登录,服务器销毁用户登录信息,作废“token”。
建议客户端在退出系统时总是调用该接口。 - 请求
user/?action=logout&token=vvkphp5ca79c538n
- 响应
{ "code":0, }
4.添加和更新资源
4.1.添加图片资源
-
用途
向目录中添加一个资源。 -
请求
res/?action=addImage
参数:parent=5accb333e1382314030eaba2&name=我的图片&img_url=&img_small=
parent 目录编号,必选,指明向哪个目录添加资源。
name 资源名称。
img_url 图片资源的URL地址。
img_small 图片缩略图URL地址。 - 响应
{ "code": 0, "err_desc":"5acd8c7be1382313ff021c2b" }
如果添加成功,则err_desc属性值为添加资源的编号。
如果添加失败,则err_desc属性值为错误描述。
4.2.添加视频资源
-
用途
向某个目录中添加一个视频资源。 -
请求
res/?action=addVideo
参数:parent=5accb333e1382314030eaba2&name=我的视频&img_url=&img_small=
parent 目录编号,必选,指明向哪个目录添加资源。
name 资源名称。
img_url 封面图片URL地址。
img_small 封面图片缩略图URL地址。 - 响应
{ "code": 0, "err_desc":"5acd8c7be1382313ff021c2b" }
如果添加成功,则err_desc属性值为添加资源的编号。
如果添加失败,则err_desc属性值为错误描述。
4.3.添加音频资源
-
用途
向某个目录中添加一个音频资源。 -
请求
res/?action=addAudio
参数:
与添加视频相同。 - 响应
与添加视频相同。
4.3.添加直播资源
-
用途
向某个目录中添加一个直播资源。 -
请求
res/?action=addLive
参数:
与添加视频相同。 - 响应
与添加视频相同。
4.4.添加串流资源
-
用途
向某个目录中添加一个串流资源。 -
请求
res/?action=addStreaming
参数:parent=5accb333e1382314030eaba2&name=我的摄像头&server_id=222&img_url=&img_small=&url=&prot=&demand=yes&video_bitrate=200&audio_bitrate=56&width=600&height=400
parent 【必选】目录编号,指明向哪个目录添加资源。
name 【必选】资源名称。
img_url 封面图片URL地址。
img_small 封面图片缩略图URL地址。
server_id 【必选】流媒体服务器编号,可以通过查询流媒体服务器接口查阅。
url 【必选】串流的输入地址。
prot 串流的输入协议,参见概述部分支持的协议。省略该参数服务器会自动判断,结果有可能是错误的。
demand yes|no 是否是按需取流,yes是,no否。
video_bitrate 如果要对视频流重新编码,需要设置编码码率,单位kbps,否者省略该参数。
width 重新编码的画面宽度
height 重新编码的画面高度
audio_bitrate 如果要对音频流重新编码,需要设置编码码率,单位kbps,否者省略该参数。
video_only 如果只有视频,将该值设为 on
audio_only 如果只有音频,将该值设为 on - 响应
与添加视频相同。
4.5.删除资源
-
用途
删除一个资源。
使用本接口可以删除资源,也可以删除目录。
如果目录下有资源,则不允许删除。删除目录时,如果目录下有资源会返回错误。 -
请求
res/?action=delete&id=5accb333e1382314030eaba2
id 要删除资源的编号。 - 响应
{ "code": 0, "err_desc":"" }
4.6.删除多个资源
-
用途
通过一次提交多个资源编号来删除多个资源。
使用本接口可以删除资源,也可以删除目录。
如果目录下有资源,则不允许删除。删除目录时,如果目录下有资源会返回错误。 -
请求
res/?action=deleteMany&id=5accb333e1382314030eaba2,5accb333e1382314030eaba0
id 要删除资源的编号列表,多个资源的编号使用半角逗号隔开。 - 响应
{ "code": 0, "err_desc":"" }
4.7.添加资源播出地址
-
用途
视频资源、音频资源、直播资源和串流资源,这些类型的资源都有一个或多个播出地址,使用该接口向资源中追加播出地址。
可以通过多次调用本接口为一个资源添加多个播出地址。 -
请求
res/?action=addOutput
参数:id=5accb333e1382314030eaba2&name=&url=&prot=&bitrate=
id 资源编号。
name 播出地址的名称。
url 播出地址。
prot 播出协议,如果省略,系统会自动探测播出协议。
bitrate 播出码率,可选。 - 响应
{ "code": 0, "err_desc":"" }
4.8.删除资源播出地址
-
用途
删除某个资源的播出地址。 -
请求
res/?action=removeOutput
参数:id=5accb333e1382314030eaba2&output_id=5accb333e1382314030eaba0
id 资源编号。
output_id 播出地址的编号,该编号在查询资源接口中返回。 - 响应
{ "code": 0, "err_desc":"" }
4.9.修改资源
-
用途
修改资源的信息。
使用本接口可以修改资源信息,也可以修改目录的信息。
可以传入上述添加资源接口中的一个或多个参数值,但是要根据修改的资源类型不同传入相应的参数,例如修改目录时只能传入name参数,修改串流资源时可以传入ur参数等。 -
请求
res/?action=update
参数:id=5accb333e1382314030eaba0&name=我的子目录
id 资源编号。
可接受的修改的参数列表:
name 资源名称。
img_url 封面图片URL地址。
img_small 封面图片缩略图URL地址。
url 串流的输入地址,仅在修改串流资源时有效。
prot 串流的输入协议,仅在修改串流资源时有效。
user 用户名,可选,仅在修改串流资源时有效。
pwd 密码,可选,仅在修改串流资源时有效。
demand yes|no 是否是按需取流,yes是,no否,仅在修改串流资源时有效。 - 响应
{ "code": 0, "err_desc":"" }
4.10.添加子目录
-
用途
向一个目录中添加一个子目录。 -
请求
res/?action=addFolder
参数:parent=5accb333e1382314030eaba0&name=我的子目录
parent 上级目录编号。
name 新增目录的名称。 - 响应
{ "code": 0, "err_desc":"" }
5.资源查询接口
5.1 资源概述
-
资源类型
系统支持的资源类型包括5类: 图片文件、音频文件、视频文件、直播流、监控流。
目录也是资源,是一类特殊的资源,其基本属性与资源相同。
目录和资源由 ftype 属性区分。 -
目录
资源都存放在目录中,一个目录中只能存放固定类型的资源。
目录中允许存放的资源类型由目录的 rtype 属性约定。在业务实现上,只能往图片目录中添加图片资源,往视频目录中添加视频资源,以此类推。
目录中可以创建子目录,子目录的级别没有限制。 -
根目录
根目录是系统中最顶级的一个目录,一个系统只有一个根目录。
根目录有_id属性,通过该属性可以查询根目录下的子目录,根目录不可以编辑和删除。
根目录的_id属性在用户登录后从用户信息中获取。(测试阶段也可以预先拿到这个_id进行测试)。
根目录下的一级子目录由系统初始化完成,不可以通过接口增加和删除。
一级子目录下的子目录和资源是我们要管理的对象,可以通过接口进行增删改查操作。 -
资源属性
资源属性包括通用属性和差异属性。
通用属性对所有类型资源适用,差异属性只能用于某种类型的资源。
通用属性:{ "_id": "5accb3a1e1382313ff021c28", "parent": "5accb333e1382314030eaba2", "ftype": 1, "rtype": 5, "name": "我的视频1", "ctime": 1523364769, "mtime": 1523410016, "state": 1, "img": { "url": "http://img.ruiboyun.net/5accb3a1e1382313ff021c28.jpg", "small": "http://img.ruiboyun.net/5accb3a1e1382313ff021c28_s.jpg" } }
_id 资源的唯一编号
parent 资源所在目录的编号
ftype 资源的文件类型,参见下文定义
rtype 资源的类型,参见下文定义
name 资源名称
ctime 创建时间
mtime 修订时间
state 状态,参见下文定义
img 定义图片资源的URL地址,或其它类型资源的封面图片地址。
?url 图片URL地址
?small 图片缩略图地址 -
ftype定义
?使用整数来定义:
?1 = 资源
?2 = 目录
?3 = 链接【保留】 - rtype定义
?使用整数来定义:
?1 = 纯文本文件【保留】;
?2 = html文件【保留】;
?3 = 图片文件;
?4 = 音频文件;
?5 = 视频文件;
?10= 直播流;
?20= 监控流;
5.2 资源管理流程
资源管理从查询根目录下的子目录开始。一个根目录下会包含多个子目录,用于存放不同类型的资源。
每个注册用户都有一个根目录,这个根目录的_id在用户成功登录后包含在返回信息中,具体参见登录接口。
获得根目录的_id属性后,先查询到一级子目录。然后根据业务需要管理一级子目录下的目录和资源。
例如:
根目录_id为“myroot”,则可以通过查询目录接口查询一级子目录:
res/?action=folder&parent=myroot
通常会查询到5个子目录,名称为:图片、音频、视频、直播、监控。(也可能会有变化)
然后根据以下接口进行子目录内的资源管理。
5.3 查询目录
-
用途
查询指定目录下的子目录。 - 请求
res/?action=folder&parent=myroot
parent 上级目录编号,必选,指定要查询哪个目录下的资源。 - 响应
{ "code": 0, "data": { "count":2, "items": [ { "_id": "5accb333e1382314030eaba0", "parent": "myroot", "ftype": 2, "rtype": 3, "name": "图片资源", "ctime": 1523364659, "state": 1 }, { "_id": "5accb333e1382314030eaba2", "parent": "myroot", "ftype": 2, "rtype": 5, "name": "视频资源", "ctime": 1523364659, "state": 1 } ] } }
返回一个或多个子目录的信息。
5.4 查询资源
-
用途
查询指定目录下的资源。 -
请求
res/?action=resource&parent=5accb333e1382314030eaba2
parent 上级目录编号,必选,指定要查询哪个目录下的资源。 - 响应
{ "code": 0, "data": { "count": 1, "items": [ { "_id": "5accb3a1e1382313ff021c28", "parent": "5accb333e1382314030eaba2", "ftype": 1, "rtype": 5, "name": "我的视频1", "ctime": 1523364769, "mtime": 1523410016, "state": 1, "img": { "url": "http://img.ruiboyun.net/5accb3a1e1382313ff021c28.jpg", "small": "http://img.ruiboyun.net/5accb3a1e1382313ff021c28_s.jpg" }, "output": [ { "_id": "5acd64b7e1382313ff021c2a", "name": "rtmp直播", "prot": "rtmp", "url": "rtmp://video.ruiboyun.net/live/live1", "bitrate": null } ] } ] } }
返回一个或多个资源的信息。基本属性信息参见上文定义。
音频资源、视频资源、直播资源、监控资源都有output属性,定义资源的播出地址。
一个资源可以由多个播出地址,使用播出地址的_id属性进行区分。
output 资源的播出地址,一个资源可以包含多个播出地址。
?_id 播出地址的编号,用于唯一识别一个资源的一个播出地址。
?name 播出地址名称
?prot 播出协议,系统支持的协议类型可以通过查询可用协议接口获得。。
?url 播出url地址
?bitrate 播出url多媒体流的比特率
5.5 查询资源和目录
- 用途
查询指定目录下的子目录和资源。
使用该接口可以一次查询到某个目录下的子目录和资源信息。 - 请求
res/?action=all&parent=myroot
parent 上级目录编号,必选,指定要查询哪个目录下的资源。 - 响应
响应数据与以上两个接口相同。
5.6 查询支持的视频流协议
- 用途
查询系统中支持的输入输出协议。用于在添加串流和添加播出地址时使用。 -
请求
res/?action=protocols - 响应
{ "code": 0, "data": { "count": 1, "items": [ { "rtmp": "rtmp", "rtsp": "rtsp", "rtspt": "rtsp tcp", "rtp": "rtp", "udp": "udp", "onvif": "onvif", "hls": "hls", "http-mp4": "mp4 over http", "http-flv": "FLV over http", "mms": "mms", "mmsh": "mms-http" } ] } }
items段中包含协议属性值和显示名称。
如: http-flv是属性的值,FLV over http是在网页上显示的内容。
6.管理服务器
6.1.查询服务器
-
用途
查询服务器。 - 请求
server/?action=list - 响应
{
"code": 0,
"data": {
"count": 1,
"items": [
{
"_id": "5ad48b99e1382314006902f6",
"name": "我的服务器",
"ip": "cloud.ruiboyun.net",
"user": "admin",
"live": "live",
"vod": "vod",
"ctime": 1523878809,
"mtime": 1523951519,
}
]
}
}
_id 服务器编号
name 服务器名称
ip 服务器ip地址
user 登录g3的用户名
live 使用的直播应用
vod 使用的点播应用
ctime 创建时间
mtime 修改时间
6.2.添加服务器
-
用途
添加服务器。 - 请求
server/?action=add
参数:action=add&name=我的服务器&ip=cloud.ruiboyun.net&user=admin&pwd=noveltv&live=live&vod=vod
name 名称
ip 服务器ip地址
user 登录g3的用户名
pwd 登录G3的密码
live 使用的直播应用
vod 使用的点播应用
ctime 创建时间
mtime 修改时间 - 响应
{ "code": 0, }
6.2.修改服务器
-
用途
添加服务器。 -
请求
server/?action=update
参数:action=update&id=123&name=我的服务器&ip=cloud.ruiboyun.net&user=admin&pwd=noveltv&live=live&vod=vod
id 服务器编号
name 名称
ip 服务器ip地址
user 登录g3的用户名
pwd 登录G3的密码
live 使用的直播应用
vod 使用的点播应用 - 响应
{ "code": 0, }
7.设备管理接口
这里的设备是指展示视频的大屏幕和屏幕控制主机。
7.1.查询设备
-
用途
查询设备。 - 请求
device/?action=list - 响应
{
"code": 0,
"data": {
"count": 1,
"items": [
{
"_id": "5add8b12e1382314011fe73d",
"name": "我的设备2",
"seq": "x1",
"pwd": "111",
"resolution": "1280x720",
"os": "Windows",
"ip": "192.168.1.23",
"ctime": 1524468498,
"mtime": 1524468554,
"state": 1,
}
]
}
}
_id 编号
name 名称
ip p地址
seq 设备编号,登录设备时需要配合密码一起使用
pwd 登录设备的密码
resolution 屏幕分辨率
os 操作系统
ctime 创建时间
mtime 修改时间
state 设备状态
7.2.添加设备
-
用途
添加设备。 -
请求
device/?action=add
参数:name=我的设备&ip=192.168.1.23&pwd=111&resolution=1280x720&os=Windows
_id 编号
name 名称
ip p地址
pwd 登录设备的密码
resolution 屏幕分辨率
os 操作系统 - 响应
{ "code": 0, }
7.3.修改设备
-
用途
修改设备。 -
请求
device/?action=update
参数:name=我的设备&ip=192.168.1.23&pwd=111&resolution=1280x720&os=Windows&state=1
_id 编号
name 名称
ip p地址
pwd 登录设备的密码
resolution 屏幕分辨率
os 操作系统
state 设备状态,可以使用该状态控制启用或禁用 - 响应
{ "code": 0, }
以上是关于上屏系统-接口规范-ALL In One的主要内容,如果未能解决你的问题,请参考以下文章
centos7 下安装zimbra all in one系统
Ubuntu系统上All-in-one部署OpenStack