开放平台 内部资料
开放平台SDK提供了一个过滤器，可用于实现应用接入开放平台时的用户登录逻辑。过滤器中会拦截用户请求，判断用户是否已登录成功，如果登录超时则直接提示“用户未登录或登录超时”。登录成功后执行应用具体业务程序，如果应用需要获取登录用户信息，可调用XyhPrivateApiHelper.loginUserPrivate.getLoginUser(HttpServletRequest request)方法获取。
使用过滤器时需在web.xml文件中加入以下配置
<filter>
<filter-name>XyhOpenBaseFilter</filter-name>
<filter-class>nbugs.xyh.open.filter.XyhOpenBaseFilter</filter-class>
<init-param>
<param-name>XyhOpenBaseFilter</param-name>
<param-value>UTF-8</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>XyhOpenBaseFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
如果在登录超时后希望通过校园号开放平台重新登录则在web.xml文件中再加入以下参数，否则登录超时后过滤器将抛出异常信息：用户未登录或登录超时
<init-param>
<param-name>doLogin</param-name>
<param-value>true</param-value>
</init-param>
在使用SDK提供的过滤器后，可以使用以下方式直接获取当前登录用户的对象，如果用户登录超时，该方法返回NULL。
XyhPrivateApiHelper.loginUserPrivate.getLoginUser(request);
参数说明
| 参数 | 是否必须 | 说明 |
|---|---|---|
| oauth_token | 是 | 用户授权获得的token |
返回示例
{
"grant_code":"aef6e75403594e09bd209e823ad7b6731472262560279",
"expire": 300
}
示例说明
| 字段名 | 字段含义 |
|---|---|
| grant_code | 用户身份的临时码，只能使用一次 |
| expire | 临时码的有效时间，单位：秒 |
SDK使用
XyhPrivateApiHelper.grant.loadCodeByOauthToken(String oauth_token)
调用该方法后返回一个字符串，即为oauth_token换取的code信息
参数说明
| 参数 | 是否必须 | 说明 |
|---|---|---|
| oauth_token | 是 | 应用授权获得的token |
| orgid | 是 | 机构ID |
| cfgkey | 是 | 配置项名称 |
| cfgval | 否 | 配置项对应的值，空值时表示删除该配置信息 |
返回示例
{
"code": 0
}
示例说明
| 字段名 | 字段含义 |
|---|---|
| code | 结果标识码，0表示结果正常，非0表示结果错误，此时msg字段用于描述错误信息 |
SDK使用
XyhPrivateApiHelper.orgCfgPrivate.set(String orgid,String cfgKey,String cfgValue)
接口中的cfgKey为配置项名称，cfgValue为对应配置项的值，该值如果为空表示删除该配置项，接口调用成功后返回true.
参数说明
| 参数 | 是否必须 | 说明 |
|---|---|---|
| oauth_token | 是 | 应用授权获得的token |
用户配卡数据格式
{
"orgid":"331101-S000002",
"cards":[
{
"cardid":"1234",
"userid":"331101-S000002-S000001",
"remark":"我的卡号"
}
]
}
| 参数 | 是否必须 | 说明 |
|---|---|---|
| orgid | 是 | 用户所在组织机构ID |
| cards | 是 | 用户配卡信息列表 |
| cardid | 是 | 卡号，如果为空表示删除userid指定用户的卡号 |
| userid | 是 | 用户ID |
| remark | 否 | 卡的备注信息 |
返回示例
{
"code": 0
}
示例说明
| 字段名 | 字段含义 |
|---|---|
| code | 结果标识码，0表示结果正常，非0表示结果错误，此时msg字段用于描述错误信息 |
SDK使用
XyhPrivateApiHelper.card.modify(String orgid,List<XyhUserCard> cards)
该接口中的cards参数为待用户配卡信息的用户配卡数据列表，配卡信息修改成功后接口返回true，否则接口以异常的方式抛出错误信息。
参数说明
| 参数 | 是否必须 | 说明 |
|---|---|---|
| oauth_token | 是 | 应用授权获得的token |
| userids | 否 | 删除指定用户的配卡信息，多个之间用逗号分隔，该字段与cardids不能同时为空 |
| cardids | 否 | 删除指定的卡号信息，多个之间用逗号分隔，该字段与userids不能同时为空 |
返回示例
{
"code": 0
}
示例说明
| 字段名 | 字段含义 |
|---|---|
| code | 结果标识码，0表示结果正常，非0表示结果错误，此时msg字段用于描述错误信息 |
SDK使用
XyhPrivateApiHelper.card.remove(String orgid,Set<String> userids,Set<String> cardids)
该接口中的orgid为必传，userids和cardids至少选择一个，如果指定了userids接口将删除指定用户的所有配卡，如果指定了cardids接口将删除指定的卡号数据
参数说明
| 参数 | 是否必须 | 说明 |
|---|---|---|
| oauth_token | 是 | 应用授权获得的token |
| portalid | 是 | 入口ID，在企业号下即为corpid |
| funcid | 是 | 应用ID |
| mediaid | 是 | 文件在微信服务器上的ID |
| media_type | 是 | 文件类别，可选值：amr/mp3/gif/png/jpg/jpeg/mp4 |
返回示例(图片文件)
{
"code": "0",
"r": {
"fileId": "02YbLzw9p6mHrKwvZbjczn.jpg",
"fileType": "image",
"fileName": "ed7f559c8a3043399b39562c61b792b2.jpg",
"fileSize": 195456,
"fileCreateTime": 1473780003000,
"fileUrl": "http://jybxiaochong.oss-cn-hangzhou.aliyuncs.com/02YbLzw9p6mHrKwvZbjczn.jpg",
"funcId": 68,
"imageFile": {
"imageType": "jpg",
"imageWidth": 960,
"imageHeight": 1280,
"orientation": "Top, left side (Horizontal / normal)",
"originalImageUrl": "http://pic.nbugs.com/02YbLzw9p6mHrKwvZbjczn.jpg",
"mediumImageUrl": "http://pic.nbugs.com/02YbLzw9p6mHrKwvZbjczn.jpg@800w_1280h_70q.jpg",
"smallImageUrl": "http://pic.nbugs.com/02YbLzw9p6mHrKwvZbjczn.jpg@400w_1280h_70q.jpg"
}
}
}
示例说明
| 字段名 | 字段含义 |
|---|---|
| code | 结果标识码，0表示结果正常，非0表示结果错误，此时msg字段用于描述错误信息 |
| r | 表示一个对象信息 |
| fileId | 上传后文件存储的文件ID |
| fileType | 文件类型，可能的值有：image/audio/video/file |
| fileName | 上传后文件存储的文件名称 |
| fileSize | 文件大小，单位：b |
| fileCreateTime | 文件上传成功的时间戳 |
| fileUrl | 文件上传后的URL |
| funcId | 上传文件的应用ID |
| imageFile | 对应fileType字段，fileType=imgage时用该字段，fileType=audio时将返回voiceFile字段，fileType=video时将返回videoFile字段，fileType=file时无该字段信息 |
| imageType | 图片文件的扩展名 |
| imageWidth | 图片文件的宽度，单位：px |
| imageHeight | 图片文件的高度，单位：px |
| orientation | 图片文件旋转信息 |
| originalImageUrl | 原始图片的URL |
| mediumImageUrl | 中图的URL |
| smallImageUrl | 小图的URL |
SDK使用
XyhPrivateApiHelper.uploader.wxdown(String portalid,int funcid,String mediaid,String mediaType)
上传成功后，接口返回XyhFileUploadResult对象，包含了文件上传成功后的具体信息，是对上述返回示例中字段的封装。
参数说明
| 参数 | 是否必须 | 说明 |
|---|---|---|
| oauth_token | 是 | 应用授权获得的token |
| funcid | 是 | 应用ID |
| content-type | 是 | 请求头信息，用以指定上传文件的类型：如：audio/amr、image/jpg、video/mpeg4等等，也可以将content-type设置为application/octet-stream，然后用content-disposition头信息字段指定文件的信息 |
| content-disposition | 否 | 该字段值的形式如：attachment; filename=sample.text |
返回示例(除图片文件,arm/mp3及mp4文件以外的普通文件)
{
"code": "0",
"r": {
"fileId": "02YbLzw9p6mHrKwvZbjczn.jpg",
"fileType": "image",
"fileName": "ed7f559c8a3043399b39562c61b792b2.jpg",
"fileSize": 195456,
"fileCreateTime": 1473780003000,
"fileUrl": "http://jybxiaochong.oss-cn-hangzhou.aliyuncs.com/02YbLzw9p6mHrKwvZbjczn.jpg",
"funcId": 68
}
}
示例说明
| 字段名 | 字段含义 |
|---|---|
| code | 结果标识码，0表示结果正常，非0表示结果错误，此时msg字段用于描述错误信息 |
| r | 表示一个对象信息 |
| fileId | 上传后文件存储的文件ID |
| fileType | 文件类型，可能的值有：image/audio/video/file |
| fileName | 上传后文件存储的文件名称 |
| fileSize | 文件大小，单位：b |
| fileCreateTime | 文件上传成功的时间戳 |
| fileUrl | 文件上传后的URL |
| funcId | 上传文件的应用ID |
SDK使用
1. XyhPrivateApiHelper.uploader.upload(int funcid,InputStream in,String extName)
2. XyhPrivateApiHelper.uploader.upload(int funcid,String filename)
针对开放平台上传文件的接口，SDK中提供了两种签名形式的接口用于实现上传逻辑，上传成功后都将返回XyhFileUploadResult对象。
参数说明
| 参数 | 是否必须 | 说明 |
|---|---|---|
| oauth_token | 是 | 应用授权获得的token |
| passid | 是 | 用户的PASSID，如果用户账号是手机值，则PASSID是与该值对应的一个唯一值 |
| base64Img | 是 | 用户头像图片的base64编号，放在请求头中以POST方式提交 |
| content-type | 是 | 请求头信息，此处可确定为：multipart/form-data |
返回示例
{
"state": "true",
"passid","206"
}
示例说明
| 字段名 | 字段含义 |
|---|---|
| state | 执行结果，true表示成功，false表示失败 |
| passid | 执行成功时将返回用户的passid信息 |
SDK使用
1. XyhPrivateApiHelper.photo.upload(String passid,File file)
2. XyhPrivateApiHelper.photo.upload(String passid,String base64Imgstr)
针对开放平台上传用户头像的接口，SDK中提供了两种签名形式的接口用于实现上传逻辑，上传成功后都将返回用户头像URL的字符串。