标签：api
1.概述上屏API是上屏系统的后台接口，管理平台界面实现需要遵循本接口规范。
客户端和服务器通过HTTP协议通信，客户端使用HTTP GET方法或POST方法向服务器发送请求，服务器返回json格式的业务数据或操作结果给客户端。
尽管接口同时支持GET和POST方法，建议查询数据时使用GET方法，修改和添加数据时使用POST方法。
接口的请求地址是个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规范。
服务器在收到接口请求后，首先判断token的正确性，如果token错误，则返回认证错误的消息给客户端。如果token正确，服务器返回json格式的文本内容给客户端。返回给客户端的json文本描述了服务器对请求的处理结果和响应数据。
客户端必须首先通过身份认证才能继续调用接口，在一个“挑战—>应答”模式的身份认证过程中完成身份认证，认证通过后，服务器为客户端分配一个临时令牌token，在后续的请求中，token作为一项必选参数提供，服务器通过token识别用户身份和验证请求的合法性。
在没有接口调用时，token的有效期为30分钟，之后客户端再调用接口时必须重新进行身份认证，获取新的token。
为了确保一定的安全性，客户端应妥善保存token值。
当URL请求参数值中包含URL地址保留字符时，应对参数值进行URL编码。
具体参见“RFC2396: Uniform Resource Identifiers (URI): Generic Syntax”。
当请求参数包含中文字符时，应对中文字符采用UTF-8编码。
本文档在描述接口的URL地址时，如果没有特殊说明，会省略掉URL前面的相同部分。
例如，
http://ip/res/?action=get&token=123456 简化为 res/?action=get&token=123456，或者按如下方式描述：
接口： res
参数： action=get&token=123456
在描述参数时，省略token参数的描述，在示例中也会省略。在实际调用中必须把token参数加上。
在对参数进行描述时，用【必选】表示该参数必须提供，【保留】表示该参数可以接受但尚未被使用。
返回的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参数来请求指定页码的数据。
接口返回的业务对象（资源、用户、设备等）数据，都包含一个_id属性，具有全局唯一性，是数据表的主键。在请求更新、删除接口时，需要传入对象的_id属性。接口要求在传入主键时使用id作为传入属性名。具体见接口定义部分。
所有业务对象都具备如下公共属性：
_id 主键，一个32位的字符串
ctime 创建时间，UNIX时间戳
mtime 修改时间，UNIX时间戳
state 状态
状态值：整数 1=正常，2=禁用
[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
注册一个新用户。
注册完成的用户是否可以登录和管理系统，由后台逻辑约定。
user/?action=regedit参数：
name=姓名&pwd=123&email=admin@domain.com&phone=13888888888&addr=北京name 姓名
email 邮件地址，系统要求使用注册的邮件地址作为登录服务器的用户名。
pwd 用户密码，用于登录系统
phone 联系电话
addr 联系地址
{
"code":0,
"err_desc":""
}客户端调用流媒体服务器接口，首先要做的是身份认证，认证通过后才可以调用流媒体服务器的接口。
服务器和客户端通过“挑战->应答”方式（challenge-response）进行身份认证交互，在这个过程中，客户端需要调用两次接口向服务器证明身份。认证过程中不需要传递密码，密码用于签名验证。
身份认证的过如下：
1）客户端使用“用户名”作为参数调用“login1”接口，向服务器发出身份认证请求
1.1）服务器确认用户是否是有效的用户：
1.2）若不是，则不做进一步处理，返回错误信息
1.3）若是，服务器产生一个“随机数（挑战字符串）”发送给客户端
2）客户端使用“用户密码”和“随机数（挑战字符串）”作为输入，按约定的算法生成一个hash值，用该hash值作为 调用“login2”接口的参数，请求login2接口。
2.1）服务器用收到的hash值与自己的计算结果比较，若二者相同，则通过认证；否则，认证失败
2.2）若认证通过，服务器返回“token”给客户端，否者返回错误信息。
user/?action=login1&email=admin@domain.comemail 使用注册的邮件地址作为登录服务器的用户名。
{
"code": 0,
"data": {
"count": 1,
"items": [
{
"id": "5ad55392e1382313ff021c3b",
"chcode": "pum0odo40qu1tts5"
}
]
}
}code 等于0，表示用户有效，items段返回挑战数据：
?id 挑战识别编号，原样带入login2接口;
?chcode 挑战字符串。
code 不等于0，其他值表示错误，此时 err_desc 的内容是错误描述。
user/?action=login2&id=id&hash=8c96202be3da1b23a96c4c838eb34d93id 由接口login1返回，原样带入。
hash是使用用户密码和挑战字符串作为输入计算出的md5摘要值(hash)，算法如下：
hash=md5(md5(password)+challenge_code)算法描述：首先计算出密码的hash值，然后在生成的密码hash值尾部拼接上挑战字符串形成新的字符串，最后计算这个新字符串的hash值。
hash算法采用md5算法，生成的摘要采用16进制编码，编码生成的字符采用小写字母。
例如，字符串111111的hash值是 96e79218965eb72c92a549dd5a330112
{
"code": 0,
"data": {
"count": 1,
"items": [
{
"_id": "5ad4594fe1382314030eabb2",
"name": "王见",
"email": "wangjian@ruiboyun.net",
"root": "5ad4594fe1382314030eabb2",
"phone": "13888888888",
"addr": "北京",
"token": "6df901hvwqj4rqsj"
}
]
}
}_id 用户编号
name 用户名
email 邮件地址
phone 联系电话
addr 地址
token 认证令牌，用于请求后续接口
root 文档根目录的id，用于请求用户资源
user/?action=logout&token=vvkphp5ca79c538n{
"code":0,
}用途
向目录中添加一个资源。
请求
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属性值为错误描述。
用途
向某个目录中添加一个视频资源。
请求
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属性值为错误描述。
用途
向某个目录中添加一个音频资源。
请求
res/?action=addAudio
参数：
与添加视频相同。
用途
向某个目录中添加一个直播资源。
请求
res/?action=addLive
参数：
与添加视频相同。
用途
向某个目录中添加一个串流资源。
请求
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=400parent 【必选】目录编号，指明向哪个目录添加资源。
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
用途
删除一个资源。
使用本接口可以删除资源，也可以删除目录。
如果目录下有资源，则不允许删除。删除目录时，如果目录下有资源会返回错误。
请求
res/?action=delete&id=5accb333e1382314030eaba2
id 要删除资源的编号。
{
"code": 0,
"err_desc":""
}用途
通过一次提交多个资源编号来删除多个资源。
使用本接口可以删除资源，也可以删除目录。
如果目录下有资源，则不允许删除。删除目录时，如果目录下有资源会返回错误。
请求
res/?action=deleteMany&id=5accb333e1382314030eaba2,5accb333e1382314030eaba0
id 要删除资源的编号列表，多个资源的编号使用半角逗号隔开。
{
"code": 0,
"err_desc":""
}用途
视频资源、音频资源、直播资源和串流资源，这些类型的资源都有一个或多个播出地址，使用该接口向资源中追加播出地址。
可以通过多次调用本接口为一个资源添加多个播出地址。
请求
res/?action=addOutput
参数：
id=5accb333e1382314030eaba2&name=&url=&prot=&bitrate=id 资源编号。
name 播出地址的名称。
url 播出地址。
prot 播出协议，如果省略，系统会自动探测播出协议。
bitrate 播出码率，可选。
{
"code": 0,
"err_desc":""
}用途
删除某个资源的播出地址。
请求
res/?action=removeOutput
参数：
id=5accb333e1382314030eaba2&output_id=5accb333e1382314030eaba0id 资源编号。
output_id 播出地址的编号，该编号在查询资源接口中返回。
{
"code": 0,
"err_desc":""
}用途
修改资源的信息。
使用本接口可以修改资源信息，也可以修改目录的信息。
可以传入上述添加资源接口中的一个或多个参数值，但是要根据修改的资源类型不同传入相应的参数，例如修改目录时只能传入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":""
}用途
向一个目录中添加一个子目录。
请求
res/?action=addFolder
参数：
parent=5accb333e1382314030eaba0&name=我的子目录parent 上级目录编号。
name 新增目录的名称。
{
"code": 0,
"err_desc":""
}资源类型
系统支持的资源类型包括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 = 链接【保留】
资源管理从查询根目录下的子目录开始。一个根目录下会包含多个子目录，用于存放不同类型的资源。
每个注册用户都有一个根目录，这个根目录的_id在用户成功登录后包含在返回信息中，具体参见登录接口。
获得根目录的_id属性后，先查询到一级子目录。然后根据业务需要管理一级子目录下的目录和资源。
例如：
根目录_id为“myroot”，则可以通过查询目录接口查询一级子目录：
res/?action=folder&parent=myroot通常会查询到5个子目录，名称为：图片、音频、视频、直播、监控。（也可能会有变化）
然后根据以下接口进行子目录内的资源管理。
用途
查询指定目录下的子目录。
{
"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
}
]
}
}返回一个或多个子目录的信息。
用途
查询指定目录下的资源。
请求
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多媒体流的比特率
请求
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是在网页上显示的内容。
用途
查询服务器。
{
"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 修改时间
用途
添加服务器。
action=add&name=我的服务器&ip=cloud.ruiboyun.net&user=admin&pwd=noveltv&live=live&vod=vodname 名称
ip 服务器ip地址
user 登录g3的用户名
pwd 登录G3的密码
live 使用的直播应用
vod 使用的点播应用
ctime 创建时间
mtime 修改时间
{
"code": 0,
}用途
添加服务器。
请求
server/?action=update
参数：
action=update&id=123&name=我的服务器&ip=cloud.ruiboyun.net&user=admin&pwd=noveltv&live=live&vod=vodid 服务器编号
name 名称
ip 服务器ip地址
user 登录g3的用户名
pwd 登录G3的密码
live 使用的直播应用
vod 使用的点播应用
{
"code": 0,
}这里的设备是指展示视频的大屏幕和屏幕控制主机。
用途
查询设备。
{
"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 设备状态
用途
添加设备。
请求
device/?action=add
参数：
name=我的设备&ip=192.168.1.23&pwd=111&resolution=1280x720&os=Windows_id 编号
name 名称
ip p地址
pwd 登录设备的密码
resolution 屏幕分辨率
os 操作系统
{
"code": 0,
}用途
修改设备。
请求
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,
}标签：api
原文地址：http://blog.51cto.com/livestreaming/2106850
