Restful API概述

NQSky EMM 4.0 Server API  是基于Restful API 的接口。开发人员可以通过API对EMM业务数据添加,编辑,查询和删除(CRUD),从而根据不同的需求和使用场景,把EMM 的功能集成到自己的应用服务中。

本文档提供的EMM API接口涉及了以下EMM模块:

  1. 用户(组): EMM 用户用户组管理接口。通过API , 开发人员可以创建,修改查询或删除用户(组),根据模版导入用户等功能。
  2. 设备:在EMM服务中注册设备与激活设备的信息获取,以及对设备的管控。
  3. 策略与合规:策略与合规为管理员提供了功能强大的移动设备管理功能,可以分为:设备策略,合规和围栏策略。其中设备策略包括:配置策略与限制策略。合规分为系统合规,应用合规和失联合规,围栏策略包括时间围栏与地理围栏。
  4. 应用: 通过API, 开发人员可以实现应用上传,分发与删除等操作。
  5. 内容(MCM):EMM 系统提供了内容(文件)客户端。开发人员通过API可以实现对内容的上传和分发等操作。
  6. 日志报表:开发人员通过此类API可以获得EMM平台提供的报表统计功能。

API 命名惯例

EMM 4.0 Restful API 是通过访问的URL来定义接口的,URL的格式为:

https://{BASE-URL}/mdm/调用参数?token=XXX

例如:

https://172.16.10.61/mdm/groups/1?access_token=0e0aeea1afb7458e9b164db5d1a26253

文档中每个API都会提供代码示例,通用格式为:

调用方法 /URL/调用参数?token=XXX

其中URL都采用相对路径。

例如:

GET /groups/{groupId}?access_token=xxx

其中 GET 为HTTP的标准调用方法,包括:GET,PUT,POST,DELETE。

GET: 通过API获取数据。

PUT: 通过API添加或更新数据。

POST:通过API 批量添加数据。

DELETE:通过API 删除数据。

获取授权令牌

1. 描述

在调用EMM Server API 之前,开发人员应该已经获得了EMM Server的管理员账号,密码,租户信息。通过调用获取令牌接口获取accessToken。调用 EMM Server API 的其他接口都应该包含一个合法的accessToken,EMM Server 通过验证token来决定调用者的合法性。

2. 输入说明

输入参数 参数含义 类型 必填 备注
loginId 用户名 String Y
Password 密码 String Y
tenantId 租户ID String N 非多租户环境可以不填

3. 输出说明

输出参数 参数含义 类型 备注
errorCode 错误码 Integer 执行失败才返回
accessToken 访问令牌 String
lincenseInfoKey license信息

输出参数 参数说明 参数类型 备注
countDownDays License剩余试用天数 Int
fileIsExist License授权文件是否存在 boolean
licenseResult License文件是否有效 boolean
rightful License是否合法 boolean
upgradeTime 升级时间 String 格式:yyyy-MM-dd
remark 备注 String
customerName 客户名称 String
currentCount 当前已激活设备数量 Int
upTime 授权到期时间 String 格式:yyyy-MM-dd
deviceCount 授权可激活设备数量 Int
licenseType 授权类型 Int 1:试用,2:生产
mam 是否MAM授权 Int
mcm 是否MCM授权 Int
mdm 是否MDM授权 Int
Object

4. 调用示例

POST https://{BASE-URL}/mdm/token

输入
loginId=admin&password=123&tenantId=mdm
输出
HTTP/1.1 200 OK 
Content-Type:application/json;charset=UTF-8
{
"lincenseInfoKey": {
"licenseResult": true,
"fileIsExist": true,
"mdm": 1,
"mam": 1,
"mcm": 1,
"countDownDays": 640,
"customerName": "mdm~",
"licenseType": 1,
"upTime": "2017-12-19",
"upgradeTime": "2017-12-19",
"deviceCount": 500,
"currentCount": 0,
"remark": "",
"fileStream": null,
"fileName": null,
"rightful": true
},
"accessToken": "cb906b1359ab4768a45c18d608a3c2e1"
}

在以后调用其他API的输入参数中,都应该传入有效accessToken。如果调用失败,服务返回HTTP401,errorCode 103,说明令牌过期。调用者应该在此通过获取令牌接口重新申请新的有效Token。

根据发送accessToken的位置,分为以下两种认证方式:

方式一:request header统一认证

在调用API时,请求头中添加Authorization把认证信息上送到服务器端。

示例:

DELETE /logout
Authorization: Bearer 49ea5969df03471ca10addee88afa425

方式二:url参数认证

在调用API时,把认证字符串当做普通参数上送到服务器端,参数的名称是access_token

示例:

DELETE /logout?access_token=49ea5969df03471ca10addee88afa425

注:API文档的示例采用的是第二种方式。

错误码说明:

Http Status Code errorCode Desc
401 100 用户名密码验证失败
101 未携带访问令牌
102 访问令牌无效
103 访问令牌过期
104 租户不存在
500 114 服务器内部错误

 

 

 

400

 

 

 

109 参数值错误
112 请求参数类型错误
113 非空参数为空
115 组无效
116 用户无效
125 邮件发送失败
165 License授权文件不存在或者License已过期失效
166 License为锁定状态
167 登录失败锁定ip
168 验证码错误
169 验证码超时
170 该管理员没有可管理的组,禁止登录
171 没有权限执行此操作