巴别鸟巴别鸟文档
章节导航开发 API 概览

开发 API 概览

巴别鸟开发 API 用于把企业网盘的认证、文件、分享、组织、消息和登录能力接入第三方业务系统。左侧栏按接口作用分组，组内直接列出可调用端点。

调用总览

  • 企业管理员在私有云企业管理后台创建开发者账号，获得 client_id、client_secret 和 JWT 相关密钥。
  • OAuth 回调方式使用 /api/authorize.do 获取授权码，再用 /api/token.do 获取 access_token。
  • JWT 免登录方式使用 /api/authorizeByJWT.do 或 /account/tokenLogin.do，私有化部署需开启对应配置。
  • 文件访问 API 请求需要在 HTTP Header 中携带 Authorization: Bearer <access_token>。
  • POST、PUT、DELETE 请求通常使用 Content-Type: application/json。

JWT 声明结构与有效期

已确认两类用途：/account/tokenLogin.do 使用携带用户 email、phone 或 babelId 信息的 userToken 建立网页会话，支持用 fileId 打开指定文件，用 onlyFileList=1 仅显示文件列表；/api/authorizeByJWT.do 使用携带开发者 client_id 信息的 jwt_token，并通过查询参数指定用户，取得 code 后再经 /api/token.do 换取访问及刷新凭证。两种 JWT 不能混用。

以下结构已确认适用于当前部署：time、duration、payload 都是顶层 claims。time 为生成 JWT 时的 Unix 毫秒时间戳，duration 为该 JWT 的有效时长（秒），payload 为业务对象。网页登录的邮箱放在 payload.email；开发者授权的 ID 放在 payload.client_id，当前提供的样例中该 ID 为数字。

网页登录 userToken 解码后的结构（身份及时间为示例值）：

{
  "duration": 60,
  "payload": {"email": "user@example.com"},
  "time": 1790000000000
}

授权 jwt_token 解码后的结构（应用 ID 及时间为示例值）：

{
  "duration": 60,
  "payload": {"client_id": 1000000000001},
  "time": 1790000000000
}

60 表示这两个样例的 JWT 有效 60 秒，不是已确认的固定值或默认值；time 在每次生成时取当前时间，不能复制样例时间使用。这里的有效期属于提交给登录／授权接口的 JWT，不等于网页会话或之后换取的 access_token 的有效期。本次确认范围为当前部署，不据此宣称所有历史版本都相同。

Java JWT 对接样例

以下示例根据巴别鸟 API 对接样例整理，用于演示如何生成 JWT 字符串。实际项目中请把密钥、企业域名、用户邮箱、手机号、工号和 client_id 替换为当前企业管理后台提供的值，不要在前端页面、客户端安装包或公开代码仓库中暴露 JWT 密钥。

JWT 载荷结构包含三个核心字段：

字段 说明
time 生成 token 的时间戳，单位为毫秒
duration token 有效时长，单位为秒
payload 业务对象：当前邮箱登录样例为 {"email":"user@example.com"}；开发者授权样例为 {"client_id":1000000000001}。

常见用法：

  • 用户免登录：生成 userToken 后访问 /account/tokenLogin.do?userToken=<JWT_TOKEN>。
  • OAuth/JWT 授权：生成 jwt_token 后访问 /api/authorizeByJWT.do?response_type=code&client_id=<CLIENT_ID>&jwt_token=<JWT_TOKEN>&email=<USER_EMAIL>，再用返回的 code 换取 access_token。
  • 文件 API 调用：获取 access_token 后，在后续文件、分享、企业等 API 请求 Header 中携带 Authorization: Bearer <access_token>。

最小实现步骤：先构造 payload，邮箱登录使用 {email: "user@example.com"}，开发者授权按当前样例使用数值型 {client_id: 1000000000001}（替换为实际应用 ID，Java 中可用 long）；再构造 JWT claims：{time: 当前毫秒时间戳, duration: 60, payload: payload}；然后使用企业后台配置的 JWT 密钥按 HS256 / HmacSHA256 签名，得到 JWT 字符串；最后把该字符串作为 userToken 或 jwt_token 放入对应 URL。URL 查询参数中的 client_id 使用同一实际应用 ID。

import java.nio.charset.StandardCharsets;
import java.util.HashMap;
import java.util.Map;
import javax.crypto.SecretKey;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.security.Keys;

public final class BabelJwtExample {
    public static String createToken(Map<String, Object> payload) {
        String secret = System.getenv("BABEL_JWT_SECRET");
        if (secret == null || secret.isEmpty()) {
            throw new IllegalStateException("BABEL_JWT_SECRET is required");
        }
        SecretKey key = Keys.hmacShaKeyFor(secret.getBytes(StandardCharsets.UTF_8));
        Map<String, Object> claims = new HashMap<>();
        claims.put("time", System.currentTimeMillis());
        claims.put("duration", 60);
        claims.put("payload", payload);
        return Jwts.builder().claims(claims).signWith(key, Jwts.SIG.HS256).compact();
    }
}

示例采用 JJWT 0.12.x 的调用方式，jjwt-api、jjwt-impl 与 jjwt-jackson 应使用一致的版本，依赖配置参见 JJWT 官方说明。按巴别鸟对接样例使用密钥的 UTF-8 字节；若交付约定不同编码，先与实施方确认，勿自行截断、填充或变换密钥。HS256 密钥不足 256 位时库会拒绝签名，应由管理员提供合适的密钥。

本例只生成签名，不是登录服务或完整的 JWT 验证器。time、duration 是巴别鸟自定义字段，不等同于标准 exp。用户身份必须由可信服务端根据已认证会话确定，生成的 Token 不应写入日志；实际授权与失效行为需在目标部署中联调。

API 分组

分组 主要用途 典型入口
认证 API 开发者账号、OAuth 回调、JWT 免登录、Token 获取和刷新 获取 token
文件 API 文件列表、文件信息、上传下载、版本、移动复制、回收站、素材库分类 获取文件列表
分享 API 分享链接、分享权限、参与人、关注提醒 获取文件的分享 url
企业 API 企业信息、部门、成员、企业日志 获取当前企业信息
消息与登录 API 公告、部门讨论、JWT token 登录、通用状态码 JWT token 登录

表格可左右滚动查看

单接口页面

每个 API 条目均有独立页面，便于开发者按接口查阅路径、方法、参数和返回信息。

JWT 身份与保密提示

/api/authorizeByJWT.do 应明确传入目标用户的 email、phone 或 babelId。源 API 说明不指定用户时可能使用管理员身份，业务集成不应省略身份字段或直接信任外部传入的用户标识。JWT 签名不加密载荷，不要放入敏感明文；生产环境不要输出 Token 到控制台日志。

巴别鸟企业网盘文档内容会随产品版本、授权模块和部署配置更新；具体能力以实际部署与管理员配置为准。

本页 Markdown · AI 文档目录