巴别鸟巴别鸟文档

开发 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。

Java JWT 对接样例

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

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

字段 说明
time 生成 token 的时间戳，单位为毫秒
duration token 有效时长，单位为秒
payload 业务载荷。用于用户免登录时可放入 email、phone 或 babelId；用于 /api/authorizeByJWT.do 时可放入 client_id

常见用法：

  • 用户免登录：生成 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: "<CLIENT_ID>"}；再构造 JWT claims：{time: 当前毫秒时间戳, duration: 60, payload: payload}；然后使用企业后台配置的 JWT 密钥按 HS256 / HmacSHA256 签名，得到 JWT 字符串；最后把该字符串作为 userToken 或 jwt_token 放入对应 URL。

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 到控制台日志。

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