获取 XXD 服务器信息

2019-11-04 16:12:10
先知
93
最后编辑:先知 于 2019-11-22 09:32:24

XXD 服务器不仅为客户端提供 Socket 连接接口,还提供了 HTTP 协议接口。

这些接口主要用于客户端在登录之前获取 XXD 服务器基本信息以及文件上传下载功能。

我们首先来给大家介绍一下 客户端在登录之前获取 XXD 服务器基本信息。

获取 XXD 服务器信息

请求地址为:

XXD 服务器地址/sysGetServerInfo

例如:

https://demo.xxd.com:11443/sysGetServerInfo

客户端通过 HTTP 协议使用此地址向 XXD 服务器发起 POST 请求,请求的数据为一个字符串,格式为:

'data=postData'

其中请求字符串中的postData为请求数据对象系列化后的 JSON 字符串。请求数据对象定义如下:

{
    method: 'sysGetServerInfo',
    params: [
        serverName,
        account,
        password,
        apiVersion
    ],
    v: clientVersion,
    d: deviceType,
    lang: clientLang
}

请求数据对象中变量定义如下:

  • serverName:要登录的后端服务器名称,如果为默认后端服务器则可以留空为'';
  • account:要执行登录验证的用户账号;
  • password:用于进行登录验证的用户密码(加密后);
  • apiVersion:本地接口数据定义文件版本;
  • clientVersion:为客户端版本号;
  • lang:为客户端界面选用的语言类型,例如'zh-cn'、'en;等;
  • deviceType:为客户端类型,可选值包括'desktop'(桌面端)和'mobile'(移动端)。

下面为一个 POST 请求数据示例:

data={"method":"sysGetServerInfo","params":["","demo8","e10adc3949ba59abbe56e057f20f883e","3.0.0"],"v":"2.4.0", "d": "desktop"

客户端在发起此请求时需要设置 HTTP 请求头部信息中的 Content-Type 属性值为 'application/x-www-form-urlencoded; charset=UTF-8'。

该请求如果用户名密码都成功则返回 HTTP 状态码200,并且在请求响应内容中返回一个 JSON 对象字符串,

该对象通常包含如下字段:

字段名称 类型 说明
version 字符串 表示 XXD 服务器版本
token 字符串 表示 XXD 服务器端加密密匙字符串
uploadFileSize 数字 表示 XXD 服务器端允许上传端最大文件大小,单位为字节,如果为0表示不允许客户端上传文件到 XXD 服务器
chatPort 数字 表示要使用 WebSocket 协议连接到 XXD 服务器端所使用的端口号
apiScheme 对象 当服务器检查到客户端缓存的 API 数据定义版本与服务器端不一致时通过此字段返回当前使用的 API 数据定义文件内容,通常为xxb/api-scheme.json中的 JSON 内容;如果服务器端没有可用的 API 数据定义文件则返回false,如果服务器端 API 数据定义版本与客户端缓存一致则返回true或者版本号
clientUpdate 对象 服务器提示客户端有新版本升级的信息
push 对象 移动端离线消息推送功能配置信息

下面为一个示例对象:

{
    version: 'v2.4.0',
    token: 'eed13af53b4c56ebd9c6ecbf22017725',
    uploadFileSize: 33554432,
    chatPort: 11444,
    clientUpdate: {
        version: '3.0.1',
        desc: '3.0.1 更新了,推荐升级!',
        changeLog: '',
        downloads: {
            win32zip: 'http://xuan.im/downloads/win32zip.zip',
            win64zip: 'http://xuan.im/downloads/win64zip.zip',
            linux32zip: '',
            linux64zip: '',
            macOSzip: '',
        }
    },
    push: {},
}

当发送错误时或遇到特殊情况会返回特定的 HTTP 状态码,目前包括:

  • 401:用户名或密码验证失败;
  • 402:用户被暂时禁用;
  • 403:用户被永久禁用。
发表评论
评论通过审核后显示。