--- title: 认证与 Token description: 认证与 Token 的接口路径、方法、参数和返回字段。 slug: developer-api-auth lang: zh category: 认证 API category_order: 8 order: 2 hide_in_nav: true keywords: - API - 认证与 Token - 开发者 --- # 认证与 Token ### PDF 第 1 页 企业开发 API V6.6 上海画擎信息科技有限公司 姜大军 ### PDF 第 2 页 目录 一、 获取企业开发账号 ..............................................................................................................................................................................4 二、 认证 API ............................................................................................................................................................................................. 6 认证接口一（登录回调方式） ................................................................................................................................................................6 认证接口二（免登录方式 – JWT token 方式，在私有云部署中，需要开启 jwt token 的登录方式） ....................................... 6 获取 token .................................................................................................................................................................................................8 刷新 token .................................................................................................................................................................................................8 三、 文件访问 API ..................................................................................................................................................................................... 8 获取文件列表 ............................................................................................................................................................................................9 获取文件信息 ............................................................................................................................................................................................9 创建文件夹 ..............................................................................................................................................................................................10 预上传文件 ..............................................................................................................................................................................................10 上传文件 ..................................................................................................................................................................................................11 获取下载文件地址 ..................................................................................................................................................................................12 获取下载多文件地址 ..............................................................................................................................................................................12 获取下载文件缩略图地址 ......................................................................................................................................................................13 修改文件信息 ..........................................................................................................................................................................................13 修改文件名 ..............................................................................................................................................................................................13 删除文件(到回收站） .............................................................................................................................................................................14 删除文件（从回收站） ..........................................................................................................................................................................14 清空回收站 ..............................................................................................................................................................................................14 恢复文件（从回收站） ..........................................................................................................................................................................14 获取文件的所有版本信息 ......................................................................................................................................................................15 设置文件当前版本 ..................................................................................................................................................................................15 移动文件 ..................................................................................................................................................................................................15 拷贝文件 ..................................................................................................................................................................................................15 拷贝文件进度 ..........................................................................................................................................................................................16 文件日志 ..................................................................................................................................................................................................16 创建素材库分类 ......................................................................................................................................................................................17 创建子素材库 ..........................................................................................................................................................................................17 共享文件相关 API ................................................................................................................................................................................. 17 获取文件的分享 url ................................................................................................................................................................................ 18 获取分享的权限列表 ..............................................................................................................................................................................18 获取用户对于单个文件有权设置的分享角色 ......................................................................................................................................18 创建链接分享 ..........................................................................................................................................................................................18 关闭链接分享 ..........................................................................................................................................................................................19 设置链接分享密码 ..................................................................................................................................................................................19 邀请人员参与分享 ..................................................................................................................................................................................19 获取所有分享参与人 ..............................................................................................................................................................................20 设置分享参与人的权限角色 ..................................................................................................................................................................20 删除分享参与人 ......................................................................................................................................................................................20 提醒关注 ..................................................................................................................................................................................................21 移除某人的关注 ......................................................................................................................................................................................21 获取关注文件的用户列表 ......................................................................................................................................................................21 获取可以关注文件的用户列表，并且标记已关注文件的用户 ..........................................................................................................21 企业部门相关 API ................................................................................................................................................................................. 22 获取当前企业信息 ..................................................................................................................................................................................22 获取企业所有部门信息 ..........................................................................................................................................................................22 创建企业部门 ..........................................................................................................................................................................................22 获取部门角色列表 ..................................................................................................................................................................................23 添加部门人员 ..........................................................................................................................................................................................23 删除部门人员 ..........................................................................................................................................................................................24 获取自己所在部门信息 ..........................................................................................................................................................................24 获取部门人员 ..........................................................................................................................................................................................24 添加企业成员 ..........................................................................................................................................................................................25 更新成员信息 ..........................................................................................................................................................................................25 获取企业成员信息 ..................................................................................................................................................................................26 获取企业所有成员 ..................................................................................................................................................................................26 获取企业日志 ..........................................................................................................................................................................................26 消息推送 API ......................................................................................................................................................................................... 27 发布公告 ..................................................................................................................................................................................................27 获取发布的公告 ......................................................................................................................................................................................27 发送部门讨论 ..........................................................................................................................................................................................27 获取部门讨论 ..........................................................................................................................................................................................28 获取企业日志 ..........................................................................................................................................................................................28 四、 JWT token 登录 .................................................................................................................................................................................29 五、 附录 - 通用 API 调用返回状态码 ............................................................................................................................................... 30 ### PDF 第 3 页 状态码 result_code ................................................................................................................................................................................. 30 ### PDF 第 4 页 ## 一、 获取企业开发账号 登录巴别鸟私有云企业管理后台，在首页中设置开发者账号： 打开后填写回调函数地址：http://xxx.xxx.xxx.xxx/public/babelAuthResult.do 填写后点击确定后自动产生开发者 id (client_id)和开发者密钥(client_secret)： 注：jwtToken 为相应的生成 jwtToken 时的加密密钥。 ### PDF 第 5 页 ### PDF 第 6 页 ## 二、 认证 API ### 认证接口一（登录回调方式） #### `/api/authorize.do` #### HTTP 请求方式 GET #### URL 参数 参数名 Comment(说明) response_type 必须为 code（必填） string client_id 开发者的 id（必填） string redirect_uri 回调函数地址，需要和注册时保持一致（必填） string data 任意数据，回调时传回 string 例如： /api/authorize.do?response_type=code&client_id=xxxxx&redirect_uri=http://xxx.xxx.xxx&data=xxx 通过浏览器访问 返回结果 如果用户未登录，则会跳转到登录页，登录后如果未授权，则会 302 跳转到授权页，如果用户已经授权，则会 302 跳转到 redirect_uri 并且带上授权码和 data，类似于 http://xxx.xxx.xxx?code=xxx&data=xxx code 有效期 5 分钟。 认证接口二（免登录方式 – JWT token 方式，在私有云部署中，需要开启 jwt token 的登录方 式） #### `/api/authorizeByJWT.do` #### HTTP 请求方式 GET #### URL 参数 参数名 Comment(说明) response_type 必须为 code（必填） string client_id 开发者的 id（必填） string jwt_token Jwt token，（必填） string 是对{client_id: xxxxxxx} 加密 形成的字符串 email email(可选), 传入用户的邮箱，以该用户进行登录，不填以企业管理员进行登录，string phone phone(可选), 传入用户的手机号，以该用户进行登录，不填以企业管理员进行登录， string babelId babelId(可选), 传入用户的工号，以该用户进行登录，不填以企业管理员进行登录， string ### PDF 第 7 页 例如： /api/authorizeByJWT.do?response_type=code&client_id=xxxxx&jwt_token=xxx 说明：使用这个 api，如果不填 email, phone, babelId 系统将自动以管理员身份登录，否则会以 email, phone, babelId 对应的用户去 登录，不会显示登录界面去登录。注（email, phone, babelId）只需其中一个就可。 返回结果 { "success": true "code": "xxxxxxxxxxxxxxxxxxxxxxxxx", } jwt_token 为 自己写程序生成 样例代码如下: import java.util.Date; import java.util.HashMap; import java.util.Map; import javax.crypto.SecretKey; import javax.crypto.spec.SecretKeySpec; import io.jsonwebtoken.Claims; import io.jsonwebtoken.JwtBuilder; import io.jsonwebtoken.Jwts; import io.jsonwebtoken.SignatureAlgorithm; import net.sf.json.JSONObject; /** * 生成标准 jwt 使用的 token * */ public class JWT_App { static String skey = "babeldfdfer95840834-t8e-9-9-5934-5943-5886256"; // 密钥 在巴别鸟后台 开发者账号处 填入的 jwtToken 字段。 public static void main( String[] args ) { HashMap clientInfo = new HashMap(); clientInfo.put("client_id", "7459492016147273"); // 为开发者账户中的 client_id try { String token = createTokenJWT(clientInfo); System.out.println("----> login token:" + token); String token1 = "eyJhbGciOiJIUzI1NiJ9.eyJkdXJhdGlvbiI6NjAsInBheWxvYWQiOnsiY2xpZW50X2lkIjoiNzQ1OTQ5MjAxNjE0NzI3MyJ9LCJ0aW1lIjoxNjkxNDg4MzY4NTk0fQ.pRFCwXd2snMr IgFWOFwYbvyAeeNhoFINGk_Wmv7d24g"; JSONObject parsed = parseTokenJWT(token1); System.out.println("-----> parsed:" + parsed); System.out.println("-----> 将此 token 作为参数放在 url 中即可， 如:"); } catch (Exception e) { System.out.println(e.getMessage()); } } public static String createTokenJWT(Map config) throws Exception { HashMap data = new HashMap(); data.put("time", new Date().getTime()); data.put("duration", 60); data.put("payload", config); SignatureAlgorithm signatureAlgorithm = SignatureAlgorithm.HS256; SecretKey key = generalKey(); JwtBuilder builder = Jwts.builder() .setClaims(data) .signWith(signatureAlgorithm, key); System.out.println( " builder :" + builder); return builder.compact(); } public static JSONObject parseTokenJWT(String jwt) throws Exception { SecretKey key = generalKey(); Claims claims = Jwts.parser() .setSigningKey(key) .parseClaimsJws(jwt) .getBody(); System.out.println("----> claims:" + claims.toString()); Long time = (Long)claims.get("time"); long duration = (Integer)claims.get("duration"); Long now = new Date().getTime(); if (now - time > 1000 * duration) return null; // ------------------- 超过 10 分钟的 token 无效 JSONObject obj = JSONObject.fromObject(claims.get("payload")); return obj; } public static SecretKey generalKey(){ String stringKey = skey; byte[] encodedKey = stringKey.getBytes(); SecretKey key = new SecretKeySpec(encodedKey, 0, encodedKey.length, "HmacSHA256"); return key; } } ### PDF 第 8 页 ### 获取 token #### `/api/token.do` **HTTP 方法：** `POST` #### HTTP Header 该接口使用 Basic Auth 的方式校验 client 的信息。具体做法是在 header 中添加类似于"Authorization: Basic xxxxxxxxx"。其中 "xxxxxxxxx"是通过开发者 id (client_id)和开发者秘钥(client_secret)算出来的，具体算法为 Base64Encode(client_id + ":" + client_secret) Base64Encode 自行选择工具进行 Base64 编码 #### URL 参数 参数名 Comment(说明) grant_type（必填） 必须为 authorization_code string code（必填） 授权码，即回调地址接收到的授权码，授权码的有效期为 5 分钟，用过一次，无论成功 还是失败，授权码都会失效 string 例如： /api/token.do?grant_type=authorization_code&code=xxx&redirect_uri=http://xxx.xxx.xxx 返回结果 access_token 接口访问标识 refresh_token 用来刷新 access_token，有效时间为 30 天 expires_in access_token 的有效时间，单位为 s ### 刷新 token #### `/api/refreshToken.do` **HTTP 方法：** `POST` #### HTTP Header 该接口使用 Basic Auth 的方式校验 client 的信息。具体做法是在 header 中添加类似于"Authorization: Basic xxxxxxxxx"。其中 "xxxxxxxxx"是通过 client_id 和 client_secret 算出来的，具体算法为 Base64Encode(client_id + ":" + client_secret) #### URL 参数 参数名 Comment(说明) grant_type（必填） 必须为 refresh_token string refresh_token（必填） 即接口 2 中获取到的 refresh_token string 例如： /api/refreshToken.do?grant_type=refresh_token&refresh_token=xxx 返回结果 access_token 接口访问标识, refresh_token 用来刷新 access_token，有效时间为 30 天 expires_in access_token 的有效时间 为 3600，单位为 s ## 三、 文件访问 API 所有的接口在访问时需要在 HTTP header 中带上 access_token。对于含有请求参数的接口，通常是一些 POST、 PUT 或者 DELETE 接口，还需要设置 Content-Type 来指定参数的格式。如果需要访问不同版本的 API，就需要 在请求路径上指定具体版本，如果需要返回不同格式的 response body，那么还需要设置 Accept。所有的参数都应 该采用 utf-8 的编码。 ### PDF 第 9 页 #### Headers： Authorization：存放 access_token，格式为："Bearer " + access_token。 Content-Type：指明请求参数的格式。如果是 POST、PUT 或者 DELETE 请求，需要指定"application/json"，我 们目前不支持其他请求参数的格式，比如 xml。如果是其他类型比如 GET 请求，可以不在 header 中设置 Content-Type。 Accept：用于指定响应结果的格式以及 api 的版本信息。目前只支持返回 json 格式的 response，所以一般情况下 指定"application/json"。 若接口访问成功，我们会返回 json 格式的 response，并且 HTTP 的 status code 为 200。所有请求成功的 response 的 json 都会带有"success: true”。response 的 header 里的 X-Babel-Version 表示此次请求访问的 api 的版本号。 ### 获取文件列表 #### `/nd/api/file/list_dir` **HTTP 方法：** `GET` #### URL 参数 参数名 Comment(说明) parent_id 父文件夹 id（必填） string 当 parent 为 1 时返回企业文件夹内容，2 返回个人文件夹内容，3 返回我的 项目，4 返回我加入的分享，其它 fileId 返回正常的文件夹中的内容。 page_size 页的大小 number page 页号 number type 类型：分为 1 - file，2 - folder，0 - all 三种类型 string #### 返回字段说明 属性名 类型 说明 files 数组 文件信息 {fileId, name, …} total int 总数量 page int 页容量 success boolean 获取成功标记 code int 返回错误码 0 表示成功 ### 获取文件信息 #### `/nd/api/file/fileinfo` **HTTP 方法：** `GET` #### URL 参数 参数名 Comment(说明) id 文件 id（必填） string #### 返回字段说明 fileInfo 信息 属性名 类型 说明 file Object 文件信息 { id, name, …} ### PDF 第 10 页 success boolean 获取成功标记 code int 返回错误码 0 表示成功 ### 创建文件夹 #### `/nd/api/file/create_folder` **HTTP 方法：** `POST` #### POST 请求体参数 参数名 Comment(说明) parent_id 目标文件夹 id（必填） string name 文件名（必填） string #### 返回字段说明 属性名 类型 说明 file Object 文件信息 { id, name, …} success boolean 获取成功标记 code int 返回错误码 0 表示成功 ### 预上传文件 用于返回第二步上传文件时所需要的参数(url、upload_token) #### `/api/file/preUploadFile.do` **HTTP 方法：** `GET` #### URL 参数 参数名 Comment(说明) parent_id 目标文件夹 id（必填）(在根目录下上传可忽略此项) string name 文件名（必填） string file_id 上传新版本时需要指定上传那个文件的新版本(上传新文件可忽略此项) string #### 正确的返回结果如下 {"upload_token":"92808ecfc2ac4e0ebc0b912edac3be4a","url":"http://testdocument.babel.cc/api/file/uploadPdf.do","su ccess":true,"code":0} #### 返回字段说明 属性名 类型 说明 url string 该 url 仅能使用 1 次，且有效期为 1 小时 调用此 url 上传文件，成功后会返回 fileId， fileName、version 等 upload_token string 上传文件时作为 post 的参数 ### PDF 第 11 页 ### 上传文件 注意，本 api 的 url 是预上传接口返回的, 这里没有具体的 url，只是参数说明 https://xxx.xxx.xxx:xxx/api/file/uploadXXX.do（具体的 url 是由上一节 /api/file/preUploadFile.do 中返回的 url） POST #### POST 请求体参数 参数名 Comment(说明) file 文件二进制数据(上传数据) upload_token /api/file/preUploadFile.do 请求中的返回值 #### 返回信息如下 {"fileId":"7728538212615908","version":0,"fileName":"mesos.pdf","fileSize":848854,"success":true,"code":0} 上传相关代码 示例 加入 ‘com.squareup.okhttp3:okhttp:3.3.1’ 包 private void uploadFile(final String fileName, String parentId, final DaoCallback callback){ preUploadFile(fileName, parentId, new DaoCallback() { @Override public void onSuccess(JSONObject data) { int code = data.optInt("code", -1); final String url = data.optString("url", null); final String uploadToken = data.optString("upload_token"); if (code == 0) { // File file = new File(filePath); RequestBody fileContent = RequestBody.create(MultipartBody.FORM, file); RequestBody requestBody = new MultipartBody.Builder() .setType(MultipartBody.FORM) .addFormDataPart("file", fileName, fileContent) .addFormDataPart("upload_token", uploadToken) .build(); Request request = new Request.Builder() .url(url) .post(requestBody) .build(); // 上传需要较长的时间，因此需要设置较长的 timeout OkHttpClient okHttpClient = new OkHttpClient(); okHttpClient.newCall(request) .enqueue(new okhttp3.Callback() { @Override public void onFailure(okhttp3.Call call, IOException e) { callback.onFailure(-1, null); } @Override public void onResponse(okhttp3.Call call, okhttp3.Response response) throws IOException { int httpCode = response.code(); if (httpCode == 200) { try { JSONObject result = new JSONObject(response.body().string()); response.body().close(); boolean success = result.getBoolean("success"); if (success) { callback.onSuccess(null); } else { int code = result.getInt("code"); String msg = result.optString("msg"); callback.onFailure(code, msg); } } catch (JSONException e) { callback.onFailure(-2, null); } } else { callback.onFailure(httpCode, null); } } }); } } @Override public void onFailure( int errorCode, String msg){ Log.e("FileTransfer", "filePreUpload 失败 errorCode=" + errorCode); } }); } ### PDF 第 12 页 private void preUploadFile(String fileName, String parentId, final DaoCallback callback) { String preUploadUrl = "http://private.babel.cc:80/api/file/preUploadFile.do?name=1234.jpg&parent_id=0"; // 传入相应的参数 name, parent-id String authorization = "Bearer d48d0a0e253c4a2985d8c5653f717d71"; //根据说明 生成 Request request = new Request.Builder().url(preUploadUrl) .addHeader("Authorization", authorization) .build(); OkHttpClient okHttpClient = new OkHttpClient(); okHttpClient.newCall(request).enqueue(new okhttp3.Callback() { @Override public void onFailure(okhttp3.Call call, IOException e) { Log.d("", ""); } @Override public void onResponse(okhttp3.Call call, okhttp3.Response response) throws IOException { Log.d("",""); int httpCode = response.code(); if (httpCode == 200) { JSONObject result = null; try { result = new JSONObject(response.body().string()); } catch (JSONException e) { e.printStackTrace(); } try { boolean success = result.getBoolean("success"); if (success) { String url = result.getString("url"); callback.onSuccess(result); } else { int code = result.getInt("code"); String msg = result.optString("msg"); callback.onFailure(code, msg); } } catch (JSONException e) { callback.onFailure(-2, null); } } else { callback.onFailure(httpCode, null); } } }); } ### 获取下载文件地址 #### `/api/file/getFileDownloadUrl.do` **HTTP 方法：** `GET` #### URL 参数 参数名 Comment(说明) fileId 需要下载的文件 id（必填） string version 文件的版本号（可选） number #### 返回信息如下 {"code":0,"success":true,"type":"文件类型","url":"文件下载地址"} ### 获取下载多文件地址 #### `/api/file/downloadMultiFiles.do` **HTTP 方法：** `GET` #### URL 参数 参数名 Comment(说明) fileIdArr 由需要下载的文件 id 组成的字符串，由符号“!“(半角)分割，比如下载 id 为 133 与 233 的两 个文件，则 fileIdArr 的值为“133!233” string 类型 ### PDF 第 13 页 #### 返回信息如下 {"code":0,"success":true,"type":"文件类型","url":"文件下载地址"} 返回值 url 为多个文件打包后的下载地址。 ### 获取下载文件缩略图地址 #### `/api/file/downloadThumbnail.do` **HTTP 方法：** `GET` #### URL 参数 参数名 Comment(说明) fileId 需要下载的文件 id（必填） string version 文件的版本号（可选） number size 需要显示的缩略图尺寸，取宽高中的最大值 #### 返回信息如下 {"code":0,"success":true, "url":"文件下载地址"} 返回值 url 为多个文件打包后的下载地址。 ### 修改文件信息 #### `/nd /api/file/update_file` **HTTP 方法：** `POST` ### 修改文件信息 #### POST 请求体参数 参数名 Comment(说明) file_id 文件 id（必填） string name 新文件名 （可选） string description 文件说明 （可选） string #### 返回信息如下 {"code":0,"success":true} ### 修改文件名 #### `/nd /api/file/rename` **HTTP 方法：** `POST` ### 修改文件信息 #### POST 请求体参数 参数名 Comment(说明) file_id 文件 id（必填） string name 新文件名 string #### 返回信息如下 {"code":0,"success":true} ### PDF 第 14 页 ### 删除文件(到回收站） #### `/nd /api/file/remove_file` **HTTP 方法：** `POST` #### POST 请求体参数 参数名 Comment(说明) file_ids[] 目标文件 id 数组（必填） string[] #### 返回信息如下 {"code":0,"success":true} ### 删除文件（从回收站） #### `/nd /api/file/remove_from_trash` **HTTP 方法：** `POST` #### POST 请求体参数 参数名 Comment(说明) file_ids[] 目标文件 id 数组（必填） string[] #### 返回信息如下 {"code":0,"success":true} ### 清空回收站 #### `/nd /api/file/empty_trash` **HTTP 方法：** `POST` #### POST 请求体参数 参数名 说明 #### 返回信息如下 {"code":0,"success":true} ### 恢复文件（从回收站） #### `/nd /api/file/restore_file` **HTTP 方法：** `POST` #### POST 请求体参数 参数名 Comment(说明) file_ids[] 目标文件 id 数组 string[] restoreAll 不填写 file_ids, restoreAll 为 true，时恢复回收站中所有文件，boolean #### 返回信息如下 ### PDF 第 15 页 {"code":0,"success":true} ### 获取文件的所有版本信息 #### `/nd /api/file/versions` **HTTP 方法：** `GET` #### URL 参数 参数名 Comment(说明) file_id 目标文件 id（必填） string #### 返回信息如下 {"code":0,"versions":[],"success":true} ### 设置文件当前版本 #### `/nd /api/file/version` **HTTP 方法：** `POST` #### POST 请求体参数 参数名 Comment(说明) file_id 目标文件 id （必填） string version 版本号（必填） number #### 返回信息如下 {"code":0,"success":true} ### 移动文件 #### `/nd /api/file/move` **HTTP 方法：** `POST` #### POST 请求体参数 参数名 Comment(说明) file_ids 需要移动的目标文件 id 数组（必填） string target_id 需要移动到的目标文件夹 id（必填） string #### 返回信息如下 {"code":0,"success":true} ### 拷贝文件 #### `/nd /api/file/copy` **HTTP 方法：** `POST` #### POST 请求体参数 参数名 Comment(说明) ### PDF 第 16 页 file_ids 需要拷贝的目标文件 id 数组（必填） string target_id 需要拷贝到的目标文件夹 id（必填） string #### 返回信息如下 { "code": 0, "copyKey": "81427630-054a-11ef-8355-db93b4b1d006","fileNum": 10, "success": true} ### 拷贝文件进度 #### `/nd /api/file/copy_progress` **HTTP 方法：** `POST` #### POST 请求体参数 参数名 Comment(说明) copyKey 查看拷贝进度 copyKey 由 copy 接口返回（必填） string #### 返回信息如下 { "code": 0, "completed": 10,"total": 10, "result": {}, "success": true} ### 文件日志 #### `/nd /api/file/file_logs` **HTTP 方法：** `GET` #### GET 请求体参数 参数名 Comment(说明) file_id 目标文件 id 数组（必填） string startIndex 获取日志的起始顺序 第几条日志开始返回（选填） int 默认 0， pageSize 每页返回的个数（选填） int type 日志类型(选填) int 默认 0, 查看所有记录， 1 仅查看访问记录，2 仅查看上传下载，3 仅查看匿名用 户，4 仅查看分享及邀请，5 仅查看删除记录 userName 某个用户名 (选填) string, 返回某个用户的日志 lang 语言(选填) 默认 cn, string 返回日志的语言 cn(中文) en(英文) #### 返回信息如下 {"code":0,"success":true, "logs":[], "total":50} ### 设置用户是否有权访问素材库 #### `/nd /api/file/ set_user_access_material_library` **HTTP 方法：** `POST` #### GET 请求体参数 参数名 Comment(说明) userId 用户的 id 数组数型 [usrId1, userId2]（必填） string can 是否可访问 数值类型 （必填） int 默认 0， 0： 不可访问， 1:可以访问 #### 返回信息如下 {"code":0,"success":true} ### PDF 第 17 页 ### 创建素材库分类 #### `/nd /api/file/create_material_class` **HTTP 方法：** `POST` #### POST 请求体参数 参数名 Comment(说明) destDirFileId 目标文件夹 的 fileId（必填） string name 创建分类库的名称（必填） string accessType 分类可见性 (选填) 默认为公开 0. 0: // 公开 1: // 需要申请 2: // 部门公开 3: // 部门申请 4: // 保密 managerIds 负责人的 id 数组类型 [usrId1,userId2] departmentIds 分类可见性-限定部门 的部门 id (选填) 数组类型 [departmentId1,departmentId2] #### 返回信息如下 {"code":0, "success":true, "materialClass": {}} ### 创建子素材库 #### `/nd /api/file/create_material_folder` **HTTP 方法：** `POST` #### POST 请求体参数 参数名 Comment(说明) destDirFileId 目标文件夹 的 fileId（必填） string name 创建分类库的名称（必填） string accessType 分类可见性 (选填) 默认为公开 0. 0: // 公开 1: // 需要申请 2: // 部门公开 3: // 部门申请 4: // 保密 managerId 负责人的 id (选填) string departmentIds 分类可见性-限定部门 的部门 id (选填) 数组类型 [departmentId1,departmentId2] assistantIds 素材库助理人员的 id （选填） 数组类型 [usrId1,userId2] #### 返回信息如下 {"code":0, "success":true, "materialFolder": {}} ## 共享文件相关 API ### PDF 第 18 页 ### 获取文件的分享 url #### `/nd/api/share/shareurl` **HTTP 方法：** `GET` 获取文件的分享链接（先打开分享后，再获取该链接） #### URL 参数 参数名 Comment(说明) file_id 文件 id string is_https 返回的 share_url 协议是否为 https 0 为 http, 1 为 https， 默认 0 number #### 返回字段说明 {"code":0,"url":"https://private.babel.cc/share.do?s=http://private.babel.cc/share.do?s=MjY2OTYzNTk3OTU2NzEzOTtXZWQgSnVsIDAxIDIwMj AgMTg6MzM6NTAgR01UKzA4MDAgKEhvbmcgS29uZyBTdGFuZGFyZCBUaW1lKQ%3D%3D","success":true} ### 获取分享的权限列表 #### `/nd/api/share/share_roles` **HTTP 方法：** `GET` #### URL 参数 参数名 Comment(说明) #### 返回字段说明 {"code":0,"roles":[],"success":true} ### 获取用户对于单个文件有权设置的分享角色 #### `/nd/api/share/share_role_forfile` **HTTP 方法：** `GET` #### URL 参数 参数名 Comment(说明) file_id 文件 id string #### 返回字段说明 {"code":0,"roles":[],"success":true} ### 创建链接分享 #### `/nd/api/share/open_link_share` **HTTP 方法：** `POST` 打开分享，获取新的分享链接，之前的链接失效。 ### PDF 第 19 页 #### POST 请求体参数 参数名 Comment(说明) file_id 预分享的文件 id（必填） string link_role_id 分享的角色 string is_https 返回的 share_url 协议是否为 https number anonymousVisit 是否允许匿名访问，1 为允许，0 为不允许（可选，默认为 1） number #### 返回字段说明 {"code":0,"share_url":"http://private.babel.cc/share.do?s=http://private.babel.cc/share.do?s=MjY2OTYzNTk3OTU2NzEzOTtXZWQgSnV sIDAxIDIwMjAgMTg6MzM6NTAgR01UKzA4MDAgKEhvbmcgS29uZyBTdGFuZGFyZCBUaW1lKQ%3D%3D","password":"","success":tru e} ### 关闭链接分享 #### `/nd/api/share/close_link_share` **HTTP 方法：** `POST` 关闭我打开的分享链接 #### POST 请求体参数 参数名 Comment(说明) file_id 分享的文件 id（必填） string #### 返回字段说明 {"code":0,"success":true} ### 设置链接分享密码 #### `/nd/api/share/set_share_password` **HTTP 方法：** `POST` 文件链接分享已打开，设置链接分享的密码。 #### POST 请求体参数 参数名 Comment(说明) file_id 预分享的文件 id（必填） string password 链接分享的密码 string is_https 返回的 share_url 协议是否为 https number #### 返回字段说明 {"code":0,"success":true, "share_url": "http://private.babel.cc/share.do?s=xxxxxxxxxxx"} ### 邀请人员参与分享 #### `/nd/api/share/invite_share` **HTTP 方法：** `POST` ### PDF 第 20 页 可以根据用户的邮箱或者手机来邀请某些人来访问文件 #### POST 请求体参数 参数名 Comment(说明) file_id 文件 id（必填） string share_role 分享的权限的 id（以上所有人共享此权限）（必填） string emails[] 邮箱数组 string[] phones[] 手机号的数组 string[] #### 返回字段说明 {"code":0,"success":true} ### 获取所有分享参与人 #### `/nd/api/share/share_participants` **HTTP 方法：** `GET` #### URL 参数 参数名 Comment(说明) file_id 文件 id（必填） string #### 返回字段说明 {"code":0,"users":[],"success":true} ### 设置分享参与人的权限角色 #### `/nd/api/share/set_participant_role` **HTTP 方法：** `POST` #### POST 请求体参数 参数名 Comment(说明) file_id 文件 id（必填） string babelshare_id int（必填） 用户 id string role_id int（必填） 角色 id string #### 返回字段说明 {"code":0,"success":true} ### 删除分享参与人 #### `/nd/api/file/remove_share_participant` **HTTP 方法：** `POST` #### POST 请求体参数 参数名 Comment(说明) ### PDF 第 21 页 file_id 文件 id（必填） string babelshare_ids[] int （必填） 用户 id string #### 返回字段说明 {"code":0,"success":true} ### 提醒关注 #### `/nd/api/file/focus_file` **HTTP 方法：** `POST` #### POST 请求体参数 参数名 Comment(说明) file_id 文件 id（必填） string user_ids[] 提醒的用户的 id，此 id 应该在文件参与人中选取，否则提醒不会起作用（必填）string[] #### 返回字段说明 {"code":0,"success":true} ### 移除某人的关注 #### `/nd/api/file/unfocus_file` **HTTP 方法：** `POST` #### POST 请求体参数 参数名 Comment(说明) file_id 文件 id（必填）string user_ids[] 提醒的用户的 id，此 id 应该在文件参与人中选取，否则提醒不会起作用（必填） string[] #### 返回字段说明 {"code":0,"success":true} ### 获取关注文件的用户列表 #### `/nd/api/file/user_focusfile` **HTTP 方法：** `GET` #### URL 参数 参数名 Comment(说明) file_id 文件 id（必填） string #### 返回字段说明 {"code":0,"users":[],"success":true} ### 获取可以关注文件的用户列表，并且标记已关注文件的用户 #### `/nd/api/file/user_can_focusfile` ### PDF 第 22 页 **HTTP 方法：** `GET` #### URL 参数 参数名 Comment(说明) file_id 文件 id（必填） string #### 返回字段说明 ## 企业部门相关 API ### 获取当前企业信息 #### `/nd/api/enterprise/current` **HTTP 方法：** `GET` #### URL 参数 参数名 Comment(说明) 无 #### 返回字段说明 {"code":0,"enterprise":{},"success":true} ### 获取企业所有部门信息 #### `/nd/api/enterprise/departments` **HTTP 方法：** `GET` #### URL 参数 参数名 Comment(说明) 无 #### 返回字段说明 属性名 类型 说明 departments []数组 返回所有的部门信息 tree {}json 数据 返回部门的父子结构信息 code int sucess boolean ### 创建企业部门 #### `/nd/api/enterprise/create_department` **HTTP 方法：** `POST` ### PDF 第 23 页 #### POST 请求体参数 参数名 Comment(说明) parent_dep 父部门 id， 0 表示跟部门（必填）string name 部门名称（必填）string description 部门描述 string #### 返回字段说明 属性名 类型 说明 department {} json 数据结构 code int sucess boolean ### 获取部门角色列表 #### `/nd/api/enterprise/dep_role` **HTTP 方法：** `GET` #### URL 参数 参数名 Comment(说明) #### 返回字段说明 属性名 类型 说明 roles []数组 { id, filePermission,enterpriseId,filePermission,managerPermission, default,nameEn,name} code int sucess boolean ### 添加部门人员 #### `/nd/api/enterprise/add_dep_mem` **HTTP 方法：** `POST` #### POST 请求体参数 参数名 Comment(说明) department_id 部门 id（必填）string user_ids[] 用户列表 string[] role_id 用户在部门中的角色 string ### PDF 第 24 页 #### 返回字段说明 属性名 类型 说明 ### 删除部门人员 #### `/nd/api/enterprise/remove_dep_mem` **HTTP 方法：** `POST` #### POST 请求体参数 参数名 Comment(说明) department_id 部门 id（必填）string user_ids[] 人员的 id（必填）string[] #### 返回字段说明 属性名 类型 说明 ### 获取自己所在部门信息 #### `/nd/api/enterprise/mydeparments` **HTTP 方法：** `GET` #### URL 参数 参数名 Comment(说明) 无 #### 返回字段说明 属性名 类型 说明 departments []数组 返回我所在的部门信息 code int sucess boolean ### 获取部门人员 #### `/nd/api/enterprise/departmentmembers` ### PDF 第 25 页 **HTTP 方法：** `GET` #### URL 参数 参数名 Comment(说明) department_id 部门 id（必填）string #### 返回字段说明 属性名 类型 说明 users 数组 ： {id, name, avatrUrl,} ### 添加企业成员 #### `/nd/api/enterprise/add_ent_mem` **HTTP 方法：** `POST` #### POST 请求体参数 参数名 Comment(说明) email Email 邮箱 string password 密码 string enterprise_role 企业成员角色, 可选 number department_ids[] 该用户的部门， 可选 string[] department_roles[] 在部门中的角色， 可选 string[] sex 性别 0 - 未设置 1 - 男 2 - 女 number name 用户名 string phone 手机号， 可选 string babelId 工号，可选 string spacelimit 个人空间限制，单位 GB, 0 表示不限制 number can_ownfile 用户能否拥有个人文件， -1 - 使用企业总体设置, 0 - 没有个人文件, 1 - 有个人文件 number remarks 用户描述， 可选 string join_time 用户加入企业时间，Unix time, 单位秒 number password_is_md5 传入密码是否需要 md5 加密, 0 非 md5 密码， 1 md5 加密过的密码 number ### 更新成员信息 #### `/api/updateUserInfo.do` **HTTP 方法：** `POST` #### POST 请求体参数 参数名 Comment(说明) email 邮箱地址（搜索关键字，必须）string password 密码（修改密码，可选）string frozen 1 – 表示冻结， 0 – 表示解冻 （冻结该账号，可选）number password_is_md5 传入密码是否需要 md5 加密, 0 非 md5 密码， 1 md5 加密过的密码 number phone 手机号 (可选) string ### PDF 第 26 页 ### 获取企业成员信息 #### `/api/getEnterpriseMember.do` **HTTP 方法：** `GET` #### URL 参数 参数名 Comment(说明) email 邮箱地址（搜索关键字）string phone 手机号（搜索关键字）string babelId 工号（搜索关键字）string email/phone/babelId 可选择其一 #### 返回字段说明 {"code":0,"success":true,"user":{}} ### 获取企业所有成员 #### `/nd/api/enterprise/enterprise_members` **HTTP 方法：** `POST` #### POST 请求体参数 参数名 Comment(说明) lang 语言类型，cn 中文 ，en 英文 , 可选 options { departmentId: // 部门 id，不填写就是企业所有人员 roleId: // 角色 id， 不填写就是不限角色 "userType": 0, // 0 - 企业内人员， 1 - 外部人员 "keyName": "", // 搜索关键字： 人名，手机号，邮箱， 不填写就是所有人员 "startIndex": 0， "pageSize": 20, status: // 0 - 所有账号， 1 - 停用的账号 } 可选 #### 返回字段说明 {"code":0,"success":true,"members":{},"total":xx} ### 获取企业日志 #### `/nd/api/enterprise/enterprise_logs` **HTTP 方法：** `POST` #### POST 请求体参数 参数名 Comment(说明) department_id 部门 id，不填写就是所有部门的日志 string 可选 keyword 日志的相关搜索关键字 string 可选 ### PDF 第 27 页 startTime 日志起始时间 number 可选 endTime 日志截止时间 number 可选 startIndex int 可选 pageSize int 可选 #### 返回字段说明 {"code":0,"success":true,"logs":{},"total":xx} ## 消息推送 API ### 发布公告 #### `/nd/api/enterprise/broadcast` **HTTP 方法：** `POST` #### POST 请求体参数 参数名 Comment(说明) title 公告内容字符串（必填） string content 内容（必填）string target_users[] UserId 数组，如果为空则表示全部人员接收，string[] target_deps[] 目标部门，该部门及子部门所有成员都会收到通知，string[] target_users 与 target_deps 至少要填 1 个 #### 返回字段说明 {"code":0,"success":true} ### 获取发布的公告 #### `/nd/api/enterprise/broadcast` **HTTP 方法：** `GET` #### URL 参数 参数名 Comment(说明) start_index number pagesize number #### 返回字段说明 {"code":0,"broadcasts":[],"total":19,"success":true} ### 发送部门讨论 #### `/nd/api/file/send_dep_discussion` **HTTP 方法：** `POST` ### PDF 第 28 页 #### POST 请求体参数 参数名 Comment(说明) dep_id 部门 id（必填） string message 信息字符（必填） string json 字符串, 格式{Type: “Text”, Body:”你好” } #### 返回字段说明 {"code":0,"messageId":99,"success":true} ### 获取部门讨论 #### `/nd/api/file/dep_discussion` **HTTP 方法：** `POST` #### POST 请求体参数 参数名 Comment(说明) dep_id 部门 id（必填）string pagesize 页的大小 string start_id 消息 id,只会获取此消息之前的消息，为空则获取最新消息 string #### 返回字段说明 {"msgArr":[],"gotMoreMessages":1,"code":0,"success":true} ### 获取企业日志 #### `/nd/api/enterprise/enterprise_logs` **HTTP 方法：** `GET` #### URL 参数 参数名 Comment(说明) department_id 部门 id（）string pagesize 页的大小 number，默认值 1000 start_index 消息起始位置, number keyword 日志关键词 string startTime 起始日期: 秒 number endTime 截止日期 秒 number #### 返回字段说明 {"logs":[],"total":0,"code":0,"success":true} total 返回所有符合条件的(与分页 pageSize 无关) ### PDF 第 29 页 ## 四、 JWT token 登录 在私有云部署中，可以开启 jwt token 的登录方式，在这种情况下，允许通过下面的 url 直接以某用户的身份免登录进入网盘系 统： #### `/account/tokenLogin.do` 参数： 参数名称 可选性 说明 可选值 默认值 userToken 必填 含有登录用户的加密信息（构造方 无 法详见下面的说明） fileId 可选 要访问的文件（夹）的 id，如果不 无 填写则打开用户根目录 closeTitleBar 可选 是否关闭标题栏 1 - 关闭 0 - 不关闭 0 disableEntMark 可选 是否隐藏左上角企业标识 1 - 隐藏 0 - 不隐藏 0 disableUserMark 可选 是否隐藏右上角用户设置入口 1 - 隐藏 0 - 不隐藏 0 defaultLang 可选 设置界面使用的语言 cn 中文 en 英文 zh-HK 繁体 cn defaultClrTheme 可选 设置界面颜色主题 normal 标准模式，dark 暗色模式 normal 比如下面是以英文及暗色模式并隐藏右上角用户标志进入用户根目录界面 #### `/account/tokenLogin.do` userToken=xxxxxxxxxxxxxxxx defaultClrTheme=dark defaultLang=en disableUserMark=1 userToken 的构建 userToken 是含有登录用户信息的加密字符串，加密信息是通过标准的双方传输可信数据的安全机制 JWT 创建的口令字， JWT 加密的用户信息 JSONObject 内容如下： { payload: { email: “xxx@xxx.com”/“135XXXXXXX”/“XXXX”} time: now } 说明：其中 email, 可以是邮箱，手机号，工号； 代码如下： public static void main( String[] args ) { HashMap user = new HashMap(); user.put("email", "yuanchaozhao@qq.com"); try { //token login String userToken = createTokenJWT(user); System.out.println("----> login token:" + userToken); JSONObject parsed = parseTokenJWT(userToken); System.out.println("-----> parsed:" + parsed); System.out.println("-----> 将此 token 作为参数放在 url 中即可， 如:"); System.out.println("/account/tokenLogin.do?userToken=" + userToken); } catch (Exception e) { System.out.println(e.getMessage()); } } 其它代码 参考 jwtToken 的生成代码，在认证接口二处有提供。 备注： JWT 即 JSON Web Tokens 的简写， 是满足工业标准 RFC7519 的一种通信加密解密机制，请参考： https://jwt.io/ ### PDF 第 30 页 ## 五、 附录 - 通用 API 调用返回状态码 ## 状态码 result_code 码值 说明 0 成功 1 未知错误 2 参数错误 7 空间不足 12 禁止的用户操作 13 无效的 token ---------------------------------- 结束 the end --------------------------------