# Enterprise APIs

本组API用于获取用户的岗位、权限,获取学校组织机构等信息。

# 取用户的岗位、身份信息

# 功能介绍

用于取用户的岗位、身份

# 请求参数

除了access_token无其他参数

# 响应参数

所有API的响应参数都具有相同的通用结构,本文档只描述通用结构中entities数组返回的数据对象。

  • Position岗位身份 Structure
{
    "account":{string}                  //用户account
    "name":{string}                     //用户姓名
    "positions":[{                      //三元组数组
        "post":{                        //岗位
            "postCode":{string}         //岗位代码
            "postName":{string}         //岗位名称
            "formal":{boolean}          //是否正式岗
        },
        "dept":{                        //部门
            "organizeId":{string}       //部门编号
            "organizeName":{string}     //名称
            "parentOrganizeId":{string} //上级部门编号
            "independent":{boolean}     //是否顶级部门
        }
    }]                                    
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 请求示例

GET /v1/enterprise/user/positions?access_token=token HTTP/1.1
Host: api.sjtu.edu.cn
1
2

# 响应示例


示例 成功返回的数据
HTTP/1.1 200 
Content-Type: application/json;charset=UTF-8

{
    "errno":0,
    "error":"Succeed.",
    "total":1,
    "entities":[{
        "account":"testprofile",
        "name":"张三",
        "positions":[{
            "post":{
                "postCode":"BuiltInStudent",
                "postName":"学生",
                "bizTypes":[],
                "formal":true
            },
            "dept":{
                "organizeId":"03000",
                "organizeName":"电子信息与电气工程学院",
                "independent":true
            }
        }]
    }]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# 取用户的权限

# 功能介绍

应用可以在分级授权系统中给不同岗位身份的用户指定权限,使用本接口获取用户在该应用中所有权限,以此方便的实现应用的权限管理。
可用授权码方式或者客户端凭据授予方式获取令牌,其区别在于account参数的处理,详见以下请求参数部分。

# 请求参数

# 响应参数

所有API的响应参数都具有相同的通用结构,本文档只描述通用结构中entities数组返回的数据对象。

  • Right 用户权限 Structure
{
    "id":{guid},                    // id
    "name":{string},                // 权限名称
    "code":{string},                // 权限代码
    "description":{string},         // 权限描述
    "type":{string},                // 权限类型枚举:app、menu、button
    "index":{int},                  // 菜单属性:排序号
    "parent":{      
        "id":{string}               // 菜单属性:父权限id 
    },          
    "target":{string},              // 菜单属性:打开方式枚举:iframe、blank、inline
    "uri":{string},                 // 菜单属性:链接地址或内嵌的组件名。例如:vue://Home@http://example.com/vue.js
    "client":{      
        "id":{string}               // 所属应用系统的id(即oauth的client_id)
    },      
    "organizes":[{                  // 该用户对于此权限的数据权限范围(按部门),空或空集表示无限制
        "id":{string}               // 部门编号
        "name":{string}             // 名称
    }],     
    "businesses":[{                 // 该用户对于此权限的数据权限范围(按业务分类),空或空集表示无限制
        "organize":{                // 部门,空表示不限制部门
            "id":{string}           // 部门编号
            "name":{string}         // 名称
        }
        "business":{                // 业务,空表示不限制业务
            "bizType":{string}      // 业务大类代码
            "bizCode":{string}      // 业务分类代码
        }  
    }],
    "roles":[{                      // 该用户是通过何种角色拥有的此权限,业务系统应尽量避免使用此信息
        "id":{string}               // 角色编号
        "name":{string}             // 角色名称
    }]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

# 请求示例

GET /v1/enterprise/user/rights?access_token=token HTTP/1.1
Host: api.sjtu.edu.cn
1
2

# 响应示例


示例 成功返回的数据
HTTP/1.1 200 
Content-Type: application/json;charset=UTF-8

{
    "errno": 0,
    "error": "Succeed.",
    "total": 1,
    "entities": [{
        "id": "25fe0d2a-8b78-11eb-8d18-fa163ecd40a6",
        "name": "测试权限",
        "code": "testRight",
        "description": "",
        "parent": {
            "id": "2c229007-8b78-11eb-8d18-fa163ecd40a6"
        },
        "client": {
            "id": "322ab472-8b78-11eb-8d18-fa163ecd40a6",
            "name": "测试"
        },
        "organizes": [
            {
                "id": "12100",
                "name": "管理科学系"
            },
            {
                "id": "12500",
                "name": "会计系"
            }
        ],
        "businesses": [
            {
                "business": {
                    "bizType": "SR_Business_Science",
                    "bizCode": "sr_l_ptjdb"
                },
                "organize": {
                    "id": "12100",
                    "name": "管理科学系"
                }
            },
            {
                "business": {
                    "bizType": "SR_Business_Science",
                    "bizCode": "sr_l_gjhzb_s"
                },
                "organize": {
                    "id": "12500",
                    "name": "会计系"
                }
            }
        ],
        "roles": [
            {
                "id": "1b7af9da-8b78-11eb-8d18-fa163ecd40a6",
                "name": "测试角色"
            }
        ]
    }]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

# 查询岗位中的用户信息

  • GET https://api.sjtu.edu.cn/v1/enterprise/position/dept:post:biz/users 客户端 basic

# 功能介绍

按路径参数中的部门和岗位查询用户,注意此接口不能查询身份岗位

# 请求参数

  • 路径参数 dept:post:biz组合中,post为岗位代码,必须指定;dept为部门代码,为空或*表示不指定;biz为业务代码,可为空表示不指定。

# 响应参数

所有API的响应参数都具有相同的通用结构,本文档只描述通用结构中entities数组返回的数据对象。

返回的用户信息结构

{
    "account":{string},     // 用户账号
    "name":{string}         // 用户姓名
}
1
2
3
4

# 请求示例


示例 查询40100部门的在Developers岗位中的用户
GET /v1/enterprise/position/40100:Developers/users?access_token=token HTTP/1.1
Host: api.sjtu.edu.cn
1
2

示例 查询所有在Developers岗位中的用户
GET /v1/enterprise/position/*:Developers/users?access_token=token HTTP/1.1
Host: api.sjtu.edu.cn
1
2

示例 查询所有在Developers岗位负责test业务的用户
GET /v1/enterprise/position/*:Developers:test/users?access_token=token HTTP/1.1
Host: api.sjtu.edu.cn
1
2

# 响应示例


示例 响应返回数据
HTTP/1.1 200 
Content-Type: application/json;charset=UTF-8

{
    "errno":0,
    "error":"Succeed.",
    "total":1,
    "entities":[{
        "account":"tester",
        "name":"张三"
    }]
}
1
2
3
4
5
6
7
8
9
10
11
12

# 为用户配置岗位

  • PUT https://api.sjtu.edu.cn/v1/enterprise/position/dept:post/users?code={account} 授权码 profile

# 功能介绍

为参数dept:code指定的全局角色增加用户。 注意:

  • 所需scope为profile,需用户授权。授权用户必须在分级授权中有权限管理该岗位
  • dept:post组合的全局角色必须存在(预定义过),否则会抛 GLOBAL_ROLE_NOT_FOUND 错误
  • 新增授权时,如果用户已在该院系的岗位会抛 USER_ALREADY_IN_POSITION 错误;但取消授权时不做判断

# 请求参数

  • 路径参数dept:post,dept表示部门,post表示岗位
  • 请求参数code指定需要授权用户的jAccount

# 响应参数

所有API的响应参数都具有相同的通用结构,本文档只描述通用结构中entities数组返回的数据对象。

errno为0代表成功,如果不成功可以从error获取具体原因

# 取消用户岗位授权

  • DELETE https://api.sjtu.edu.cn/v1/enterprise/position/dept:post/users?code={account} 授权码 profile

# 功能介绍

从参数dept:code指定的全局角色中删除用户。 注意:

  • 所需scope为profile,需用户授权。授权用户必须在分级授权中有权限管理该岗位
  • dept:post组合的全局角色必须存在(预定义过),否则会抛 GLOBAL_ROLE_NOT_FOUND 错误
  • 新增授权时,如果用户已在该院系的岗位会抛 USER_ALREADY_IN_POSITION 错误;但取消授权时不做判断

# 请求参数

  • 路径参数dept:post,dept表示部门,post表示岗位
  • 请求参数code指定需要授权用户的jAccount

# 响应参数

所有API的响应参数都具有相同的通用结构,本文档只描述通用结构中entities数组返回的数据对象。

errno为0代表成功,如果不成功可以从error获取具体原因

# 查询部门

  • GET https://api.sjtu.edu.cn/v1/enterprise/organizes SDK

# 功能介绍

查询学校组织机构树,本API无须获取令牌即可使用。

# 请求参数

无任何参数

# 响应参数

所有API的响应参数都具有相同的通用结构,本文档只描述通用结构中entities数组返回的数据对象。

  • Organize 部门 Structure
{
    "organizeId":{string},      // 部门id
    "organizeName":{string},    // 部门名称
    "parentOrganizeId":{string},// 父部门id
    "independent":{boolean},    // 是否是独立部门
    "disabled":{boolean}        // 是否禁用
},
1
2
3
4
5
6
7

# 响应示例


示例 查询部门返回数据
{
    "errno": 0,
    "error": "Succeed.",
    "total": 932,
    "entities": [
        {
            "organizeId": "01000",
            "organizeName": "船舶海洋与建筑工程学院",
            "independent": true,
            "disabled": false
        },
        ...
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 查询校历

  • GET https://api.sjtu.edu.cn/v1/enterprise/calendar?from={from}&to={to}

# 功能介绍

根据参数指定的起止日期查询校历,本API无须获取令牌即可使用。

# 请求参数

参数名 格式 说明
from yyyy-mm-dd 校历起始日期
to yyyy-mm-dd 校历终止日期

# 响应参数

所有API的响应参数都具有相同的通用结构,本文档只描述通用结构中entities数组返回的数据对象。

  • Calendar 校历 Structure
{
    "day":{string},     // 日期,格式yyyy-mm-dd
    "type":{int},       // 类型 
}
1
2
3
4
  • Calendar Type 类型列表 Data
类型 说明
1 工作日
2 节假日
3 周末
4 寒假
5 暑假

# 请求示例


示例 请求2020年校历
GET /v1/enterprise/calendar?from=2020-01-01&to=2020-12-31 HTTP/1.1
Host: api.sjtu.edu.cn
1
2

# 响应示例


示例 请求2020年校历返回数据
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "errno": 0,
    "error": "Succeed.",
    "total": 0,
    "entities": [
        {
            "day": "2020-01-01",
            "type": 2
        },
        {
            "day": "2020-01-02",
            "type": 1
        },
        ...
        {
            "day": "2020-12-31",
            "type": 1
        }
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23