上海交通大学开发者平台

# API SDK

我们提供了JAVA版的API SDK，用于方便的用JAVA开发使用API的应用，并不是每个API都在SDK中有对应的方法。

# 开发环境

# 环境准备

  • 已安装JDK1.8及以上版本并完成环境配置
  • 已安装Maven

# Maven配置

# 仓库配置

在pom.xml中增加如下仓库配置

<repositories>
    <repository>
        <id>public</id>
        <name>SJTU Release Repository</name>
        <url>https://maven.dev.sjtu.edu.cn/content/groups/public/</url>
        <releases>
            <enabled>true</enabled>
            <updatePolicy>always</updatePolicy>
        </releases>
    </repository>
    <repository>
        <id>public-snapshots</id>
        <name>SJTU Snapshots Repository</name>
        <url>https://maven.dev.sjtu.edu.cn/content/groups/public-snapshots/</url>
        <snapshots>
            <enabled>true</enabled>
            <updatePolicy>always</updatePolicy>
        </snapshots>
    </repository>
</repositories>

<pluginRepositories>
    <pluginRepository>
        <id>public</id>
        <name>SJTU Release Repository</name>
        <url>https://maven.dev.sjtu.edu.cn/content/groups/public/</url>
    </pluginRepository>
</pluginRepositories>
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

# 依赖配置

在pom.xml中增加如下依赖配置

<dependency>
    <groupId>sjtu</groupId>
    <artifactId>sjtu-api</artifactId>
    <version>1.0-SNAPSHOT</version>
</dependency>
1
2
3
4
5

# 获取令牌

可以使用edu.sjtu.oauth.applicationToolkit.OAuth2Util类来获取客户端和密码方式令牌

# 客户端方式

以下方法可以客户端方式获取令牌

public static OAuthToken getToken(String appId, String appSecret, String scopes) throws OAuthSystemException, OAuthProblemException
1

# 参数说明

参数名 说明
appId 应用id，申请应用后系统发送邮件中的clientid
appSecret 应用secret，申请应用后系统发送邮件中的secretkey
scopes 申请的授权范围，如果想申请多scope，以空格分隔

# 请求示例


示例 以客户端方式请求存储令牌
OAuthToken token = OAuth2Util.getToken("clientId","secret","storage")
String accessToken = token.getAccessToken();
1
2

# 密码方式

以下方法可以密码方式获取令牌

public static OAuthToken getToken(String appId, String appSecret, String userName, String userPwd, String scopes) throws OAuthSystemException, OAuthProblemException
1

# 参数说明

参数名 说明
appId 应用id，申请应用后系统发送邮件中的clientid
appSecret 应用secret，申请应用后系统发送邮件中的secretkey
userName 用户jAccount
userPwd 用户密码
scopes 申请的授权范围，如果想申请多scope，以空格分隔

# 请求示例


示例 以密码方式请求发送通知令牌
OAuthToken token = OAuth2Util.getToken("clientId","secret","tester","password","send_notification");
String accessToken = token.getAccessToken();
1
2

# 刷新令牌

令牌有有效期，有效期到了之后可以通过刷新令牌的方式获取新令牌，以下方法可以用于刷新令牌

public static OAuthToken refreshToken(String appId, String appSecret, OAuthToken token) throws OAuthSystemException, OAuthProblemException
1

# 参数说明

参数名 说明
appId 应用id，申请应用后系统发送邮件中的clientid
appSecret 应用secret，申请应用后系统发送邮件中的secretkey
token 上次获取的OAuthToken

# 请求示例


示例 刷新令牌
OAuthToken token = OAuth2Util.getToken("clientId","secret","storage")
...
token = OAuth2Util.refreshToken("clientId","secret",token);
1
2
3

# 有效利用token的有效时间

应该有效的利用access token的有效时间，避免不必要的获取和更新access token。建议使用类似如下的代码来实现：

public class TokenUtil {
  private volatile OAuthToken token;
  private volatile long tokenExpireWhen;
  private ReadWriteLock lock = new ReentrantReadWriteLock();

  private String getAccessToken() throws Exception {
    lock.readLock().lock();
    try {
      if (System.currentTimeMillis() > tokenExpireWhen) {
        lock.readLock().unlock();
        lock.writeLock().lock();
        try {
          if (System.currentTimeMillis() > tokenExpireWhen) {  
            if (token == null) {
                token = OAuth2Util.getToken(appId, appSecret, userName, password, 0x2000000l);
            } else {
                token = OAuth2Util.refreshToken(appId, appSecret, token);
            }
            tokenExpireWhen = System.currentTimeMillis() + token.getExpiresIn() * 1000 - 300000; //提前5分钟更新
          }
        } finally {
          lock.readLock().lock();
          lock.writeLock().unlock();
        }
      }
      return token.getAccessToken();
    } finally {
      lock.readLock().unlock();
    }
  }
}
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

# 使用API类

# 初始化

如果使用Spring框架可以在配置文件里做如下配置

<bean class="edu.sjtu.api.applicationToolkit.API">
    <property name="baseApiUri" value="https://api.sjtu.edu.cn"/>
</bean>
1
2
3

然后就可以在需要使用API的类里注入

@Autowired
private API api;
1
2

或者在需要使用的地方创建API对象也可

API api = new API();
api.setBaseApiUri("https://api.sjtu.edu.cn/");
1
2

API类中缺省的连接超时和读数据超时都是10秒，如果想自己配置请用以下构造方法

API api = new API("https://api.sjtu.edu.cn/" , 10000 , 30000);
1

# Profile

# 获取用户信息

对应API接口 详细文档
GET https://api.sjtu.edu.cn/v1/me/profile 授权码 basicessentialprofileprivacy SDK

调用方法

public Profile getProfile(String accessToken) throws APIException
1

# Task

# 发送任务更新消息

对应API 详细文档
POST https://api.sjtu.edu.cn/v2/task/message 客户端 tasks SDK

调用方法

public void postMessage(String accessToken, String account, String messageType, String extraId) throws APIException
1

参数说明

参数名 说明
accessToken 令牌
account 账号(uid)
messageType 消息类型，缺省不填就是task(tid)
extraId 事件id

# Enterprise

# 取用户的权限

对应API 详细文档
GET https://api.sjtu.edu.cn/v1/enterprise/user/rights?account={account} 授权码客户端 basicessentialprivacyprofile SDK

调用方法

public List<Right> getRights(String accessToken) throws APIException
1

# 查询部门

对应API 详细文档
GET https://api.sjtu.edu.cn/v1/enterprise/organizes SDK

调用方法

  • 根据部门id获取部门
public Organize getOrganize(String organizeId)
1

Organize 部门 Structure

{
    "organizeId":{string},      // 部门id
    "organizeName":{string},    // 部门名称
    "parentOrganizeId":{string},// 父部门id
    "independent":{boolean},    // 是否是独立部门
    "disabled":{boolean}        // 是否禁用
},
1
2
3
4
5
6
7
  • 根据部门id获取其父级独立部门(顶级部门)
public Organize getIndependentOrganize(String organizeId, boolean useIndependentFlag)
1

参数说明

参数名 说明
organizeId 部门id
useIndependentFlag 是否使用部门结构中的independent字段判断是否独立部门

对于独立部门(顶级部门)的判断是根据数据中的parentOrganizeId字段是否为空来确定的，parentOrganizeId为空一定是独立部门，如果useIndependentFlag设置为true，那么可以额外用independent字段是否为true来确定是否独立部门。

  • 根据部门id以及指定的独立部门判断策略获取其父级独立部门
public Organize getIndependentOrganize(String organizeId, IndependentOrganizeStrategy strategy)
1

其中IndependentOrganizeStrategy接口定义如下

public interface IndependentOrganizeStrategy {
    boolean isIndependent(InternalOrganize internalOrganize);
}
1
2
3

用户可以自己实现该接口并作为参数传入该方法作为独立部门的判断策略，来获取指定部门的上级独立部门

# File

# 上传文件

对应API 详细文档
PUT https://api.sjtu.edu.cn/v1/file 客户端 storage SDK

调用方法

public CanvasFile putFile(String accessToken, File file) throws APIException
public CanvasFile putFile(String accessToken, InputStream fileContent, String fileName) throws APIException
1
2

# 修改文件

对应API 详细文档
POST https://api.sjtu.edu.cn/v1/file/{id} 客户端 storage SDK

调用方法

public CanvasFile putFile(String accessToken, String id, File file) throws APIException
1

# 获取文件信息

对应API 详细文档
GET https://api.sjtu.edu.cn/v1/file/{id}/meta 客户端 storage SDK

调用方法

public CanvasFile getFile(String accessToken, String id) throws APIException
1

# 修改文件信息

对应API 详细文档
POST https://api.sjtu.edu.cn/v1/file/{id}/meta 客户端 storage SDK

调用方法

public CanvasFile modifyFile(String accessToken, CanvasFile file) throws APIException
1

# Notification

# 发送通知

对应API 详细文档
PUT https://api.sjtu.edu.cn/v1/notification 密码 send_notification SDK

调用方法分多种，罗列如下：

  • 通用方法
public void putNotification(String accessToken, Notification notification) throws APIException
public void putNotification(String accessToken, String json) throws APIException
1
2
  • 发送短信通知
public void putSmsNotification(String accessToken, List<String> to, String message) throws APIException
1

参数说明

参数名 说明
accessToken 令牌
to 接收的手机号
message 短信内容
  • 发送邮件通知
public void putEmailNotification(String accessToken, List<String> emails, String subject, String body, boolean html) throws APIException
1

参数说明

参数名 说明
accessToken 令牌
emails 接收的邮箱
subject 标题
body 邮件内容
html 是否是html格式
  • 发送邮件和短信通知
public void putEmailAndSmsNotification(String accessToken, List<String> emails, List<String> phones, String subject, String body, boolean html, String message) throws APIException
1

参数说明

参数名 说明
accessToken 令牌
emails 接收的邮箱
phones 接收的手机号
subject 标题
body 邮件内容
html 是否是html格式
message 短信内容
  • 发送交我办通知
public void putAppOrSmsNotification(String accessToken, List<String> accounts, List<String> phones, String title, String message) throws APIException
1

参数说明

参数名 说明
accessToken 令牌
accounts 接收的账号
phones 接收的手机号
如果为null或长度为0，表示不需要短信做为后备方式
否则说明需要在交我办通知发送失败时发送短信，此时手机号必须和账号一一对应
title 通知标题
message 通知内容

# Mail

# 发邮件

对应API 详细文档
PUT https://api.sjtu.edu.cn/v1/mail/ 授权码密码 send_mail SDK

调用方法

public void putMail(String accessToken, Mail mail) throws APIException
1

# 标记邮件状态

对应API 详细文档
POST https://api.sjtu.edu.cn/v1/mail/{mailId} 授权码密码 send_mail SDK

调用方法

public void changeMailStatus(String accessToken, String mailId, MailStatus status) throws APIException
1

←