被控核心API服务

草案

被控端核心功能接口，在这里添加的API必须是客户端核心功能赖以生存的，否则迁移到扩展API中

识别码

申请识别码

基本信息

Path： /fastcode/apply

Method： POST

接口描述：

申请验证码并返回登录信息

Request

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是
Authorization	Bearer {$AccessToken}	是		如果有授权码授权，需要提交
User-Agent	SLRC/x.x (Windows)	是

Body

{
    "mac": "00:0a:bc:ef:11:22", // mac 地址
    
    "refresh": true // 强制刷新识别码
}

Reponse

{
   "fastcode": "1726478184",
   "password": ""
}

登录

主机授权

基本信息

Path： /authorization

Method： POST

接口描述：

通过授权码获取客户端的授权，原客户端接口每次请求提交授权码和密码，先后续所有操作必须通过授权进行

授权为绑定帐号下的应用角色，拥有该客户端应用的所有权限，以及某些所有者帐号的权限（如：下单，查看对应用户身份的广告信息等）

授权通用与整个oray体系的所有API

Request

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是		123
X-ClientID	xxxxxx	是		客户端标识的ID
User-Agent	SLRC/x.x (Windows)	是		客户端类型（版本）标识

Body

{
    "licensecode": "abcd-ef01-2345-6789-0000", // 授权码
    
    "password": "xxxxxxx" // 授权码密码
}

Reponse

{
   "access_token": "xxxx",
   "refresh_token": "xxxx",
   "refresh_expires": 7200
}

登录服务器分发

基本信息

Path： /servers/dispatches

Method： POST

接口描述：

分发客户端登录服务器，并预处理相关登录业务

Request

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是
Authorization	Bearer {$AccessToken}	是		从主机授权接口获取的AccessToken

Reponse

{
   "login": {
      "server": "rc10.oray.com"
   },
   "track": "tk-sl.oray.com"
}

主机服务

更新主机信息

基本信息

Path： /info

Method： PUT

接口描述：

Request

Headers

参数名称	参数值	是否必须	示例	备注
Authorization	Bearer {$AccessToken}	是		主机授权
Content-Type	application/json	是		请求数据格式

Body

{
   "remoteid": 130,
   "name": "",
   "cpu": ""
}

绑定主机

基本信息

Path： /hosts

Method： POST

接口描述：

本接口整合并简化了葵码绑定 （原来 /sunlogin/prelogon）& 帐号授权绑定 （原创建主机）

帐号绑定：

先走帐号授权流程：http://yapi.orayer.com:3000/project/51/interface/api/1229 获取帐号授权，通过授权头传递 access_token绑定。

葵码绑定：

直接提供葵码即可

Request

Headers

参数名称	参数值	是否必须	示例	备注
Authorization	Bearer ${AccessToken}	是		通过帐号服务获取的授权Token，帐号绑定必须提供，葵码省略
Content-Type	application/json	是		JSON
User-Agent	SLRC/x.x (Windows)	是		客户端标识

Body

{
    "mac": "00:00:00:00:00:00", // mac地址

    "name": "主机名称", // 主机名
    
    // 识别码，提交后自动绑定到主机上
    "fastcode": {
        "fastcode": "123456789",
        "password": "xxxxxxxxxxx"
    }, 

    "licensekey": "xxx" // 葵码，通过葵码绑定主机，与HTTP头的用户授权token互斥
}

Reponse

{
    "remoteid": 1234123, // 主机ID

    "name": "主机名称", // 主机名

    "ownerid": 45346123, // 所有者的ID

    "mac": "00:00:00:00:00:00", // mac地址

    "createtime": "15654615234", // timestamp
    
    "license": {
        
        "licensecode": "abcd-ef01-2345-6789-0000", // 授权码
        
        "password": "xxxxxx" // 密码
    }
}

配置上传

基本信息

Path： /configs

Method： POST

接口描述：

Request

Headers

参数名称	参数值	是否必须	示例	备注
Authorization	Bearer {$AccessToken}	是		主机授权
Content-Type	application/x-www-form-urlencoded	是

配置下载

基本信息

Path： /configs

Method： GET

接口描述：

返回当前主机的配置

Request

Headers

参数名称	参数值	是否必须	示例	备注
Authorization	Bearer {$AccessToken}	是		主机授权

Query

参数名称	是否必须	示例	备注
modules	否	hostinfo,common,camera,wakeup	指定获取的模块，缺省全部返回

Reponse

<?xml ?>.....

异常返回

异常返回

基本信息

Path： /errors

Method： GET

接口描述：

不是接口，统一定义错误的文档，一切的业务错误以及程序力所能及的致命错误（非网络，部分5xx）。错误返回为统一格式。

Http Statuscode	Error	说明

Request

Reponse

{
    "error": "category/error", // 错误代码，完整的实际应该是连上域名一个URL格式的 ${host}/${error}，见本文档备注
    "message": "error detail" // 错误的详细信息，非面向用户
}