VNNOX_API
Page tree

Versions Compared

Old Version 1

changes.mady.by.user NovaStar

Saved on

compared with

New Version Current

changes.mady.by.user NovaStar

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Tip
titleWelcome to your new documentation space!

This is the home page for your documentation space within Confluence. Documentation spaces are great for keeping technical documentation organised and up to date.

Panel
titleNext you might want to:
  •  Customise the home page - Click "Edit" to start editing your home page
  •  Check out our sample pages - Browse the sample pages in the sidebar for layout ideas
  •  Create additional pages - Click "Create" and choose "Blank Page" to get started
  •  Manage permissions - Click "Space Tools" and select "Permissions" in the sidebar to manage what users see

Search this documentation

Livesearch
spaceKeyVAPI

Popular Topics

Popular Labels
spaceKeyVAPI
count10

Featured Pages

Content by Label
showLabelsfalse
spacesVAPI
sorttitle
showSpacefalse
typepage
labelsfeatured

Recently Updated Pages

...

概要

此文档描述了Vnnox系统的REST API(v1)，如果您在使用中有任何问题请及时联系

Anchor
banben
banben
版本

默认情况下当客户端访问https://cn.vnnox.com时，系统将使用V1 版REST API提供服务，我们建议您在http请求的heaer中的`Accept`字段加上服务版本号。格式如下：

Code Block
firstline1
titleHTTP header
linenumberstrue
Accept:application/nova.vnnox.v1+json

注：为了不影响第三方功能对接，当前v1版本的REST API接口及接口中的数据会以增量方式更新。

请求简述
Anchor
qingqiu
qingqiu

所有请求均通过HTTPS协议，API请求链接为https://cn.vnnox.com，所有数据的请求及相应均通过json格式。

Request Header

Code Block
firstline1
titleHTTP Request Header
linenumberstrue
Content-Type:application/json;charset=utf-8


Response数据结构

Code Block
firstline1
titledata structure
linenumberstrue
collapsetrue
{
    "http_code": 200,            //http状态码(重要：请使用http协议本身的状态码做异常捕获，response data中http_code字段后期会取消掉)
    "data": {...some data...},   //数据部分
    "status": [10000001]         //业务相关状态码
}

请求列表

通过GET请求获取资源信息时，如果未指定资源唯一ID，则请求的为资源的列表，返回的数据list中包含了符合查询规则的集合list

Code Block
firstline1
titlelist users
linenumberstrue
collapsetrue
{
    "http_code": 200,
    "data": {
        "userList": [
            {
                "uid": "2",
                "oid": "6",
                "wid": "311",
                "enable": "1",
                "org_reg": "0",
                "uName": "user1",
                "user_conf": {...},
                "user_statistic": {... },
                "workgroup": {... },
                "role": [...]
            },
            {
                "uid": "20",
                "oid": "6",
                "wid": "3113",
                "enable": "1",
                "org_reg": "0",
                "uName": "user2",
                "user_conf": {...},
                "user_statistic": {...},
                "workgroup": {... },
                "role": [... ]
            }
        ],
        "count": "3"
    },
    "status": [
        10000001
    ]
}


请求详情

如果在资源请求中指定唯一ID,则请求的为单个资源，返回的数据只包含当前资源

Code Block
firstline1
titleuser
linenumberstrue
collapsetrue
{
    "http_code": 200,
    "data": {
        "uid": "2567",
        "oid": "67",
        "wid": "3114",
        "enable": "1",
        "org_reg": "0",
        "uName": "lileilei_3",
        "user_conf": {...},
        "role": [...],
        "workgroup": [...],
        "systemMediaApprove": "0"
    },
    "status": [
        10405001
    ]
}


参数说明
Anchor
canshu
canshu

很多API方法使用可选参数，如`GET`请求中会存在`资源名称`和`查询参数`:

Code Block
firstline1
titleGET
{host}/Rest/Medias?offset=0&limit=10&search=&sort=last_amendment_time&sortType=desc

在上述例子中，‘Rest’、‘Medias’代表了资源名称，`offset`、`limit`、`search`、`sort`、`sortType`代表了查询参数。

在`POST`、`PUT`请求中，无法包含在url中的参数需要格式化为JSON 并使用 Content-Type : 'application/json'方式请求接口

服务地址
Anchor
fuwu
fuwu

Vnnox REST API均使用`host` + `resource` + `parameters` 的请求方式与服务器交互，`host`指服务器地址：https://cn.vnnox.com/，`resource`指资源及资源路径，一般为`Rest/{资源名}/`， `parameters`为资源标识或者查询参数：


Code Block
firstline1
titlehost
GET {host}/Rest/Medias?offset=0&limit=10&search=&sort=last_amendment_time&sortType=desc
GET {host}/Rest/Medias/{media_id}
PUT {host}/Rest/Player/{player_id}
DELETE {host}/Rest/User/{user_id}
POST {host}/Rest/Worker

如上面的例子，本文档所有涉及{host}均指https://cn.vnnox.com，建议第三方开发者将{host}信息作为可配置项

错误调试
Anchor
cuowu
cuowu

在REST API请求时会有3类错误：

1、服务级错误：网络或运营商导致的服务级别错误。（建议第三方应用中捕获http不等于2xx的状态码，如404、502等）


Code Block
firstline1
HTTP/1.1 502 Bad Gateway


2、系统级错误：REST API 请求中传入了非法参数或者数据格式错误。（建议第三方在应用中捕获 json.status[0] = 1）

Code Block
firstline1
HTTP/1.1 200 ok

{
    "data": "系统级错误，请联系VNNOX管理员，谢谢！",
    "status": [1]
}

3、业务级错误：REST API因业务限制返回的状态码/错误码（json.status）。（建议第三方应用根据状态码说明处理API结果）

Code Block
firstline1
HTTP/1.1 200 ok

{
    "http_code": 200,
    "data": {
        "roleName": ""
    },
    "status": [50101201]
}


HTTP方法
Anchor
htt
htt

Vnnox REST API 目前支持4中HTTP方法：

方法名描述
GET用于获取资源状态
POST用于创建资源
DELETE用于删除资源
PUT用于修改资源状态


认证
Anchor
renzheng
renzheng

Vnnox REST API使用Oauth2.0认证，请使用认证接口获取token(加入到 HTTP-header中)

Code Block
firstline1
titleHTTP header
token:5c1354529946bc49360641f7f321611698deb371

分页
Anchor
fenye
fenye

当请求资源列表时，需要指定分页参数：


Code Block
firstline1
titlePage
GET {host}/Rest/Player?offset=0&limit=10&search=&sort=name&sortType=asc


参数名说明
offset初始数据位置
limit限定数据个数
search根据检索条件返回列表（返回符合搜索条件的资源列表，可为空）
sort排序字段( 根据特定字段排序 )
sortType排序规则(asc / desc)


Anchor
cishu
cishu
次数限制

使用Oauth2.0认证的REST API访问，同一个用户获取的token访问频次建议1小时内不要超过3000次。

Anchor
daili
daili
用户代理

所有的API请求一般都会包含User-Agent header，例如浏览器会默认设定为`Mozilla/5.0`等，如果第三方应用对接VNNOX REST API，请参照如下设置：

Code Block
firstline1
titleHTTP header
User-Agent: Vnnox-User-App

如果应用的HTTP请求中没有此参数设定，系统无法验证当前用户的Request请求来源，可能会影响到数据的访问。