巴别鸟巴别鸟文档

开发 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>，再用返回的 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.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;

public class BabelJwtExample {
    // 从企业管理后台或实施交付资料中获取。示例值必须替换，不能直接用于生产环境。
    private static final String JWT_SECRET = "REPLACE_WITH_ENTERPRISE_JWT_SECRET";

    public static void main(String[] args) throws Exception {
        Map<String, Object> user = new HashMap<>();
        user.put("email", "user@example.com");
        // 也可以按企业账号体系改用 phone 或 babelId:
        // user.put("phone", "13800000000");
        // user.put("babelId", "EMP001");

        String userToken = createTokenJWT(user);
        System.out.println("userToken=" + userToken);
        System.out.println("/account/tokenLogin.do?userToken=" + userToken);

        Map<String, Object> clientInfo = new HashMap<>();
        clientInfo.put("client_id", "REPLACE_WITH_CLIENT_ID");
        String jwtToken = createTokenJWT(clientInfo);
        System.out.println("/api/authorizeByJWT.do?response_type=code&client_id=REPLACE_WITH_CLIENT_ID&jwt_token=" + jwtToken);
    }

    public static String createTokenJWT(Map<String, Object> payload) {
        Map<String, Object> claims = new HashMap<>();
        claims.put("time", new Date().getTime());
        claims.put("duration", 60);
        claims.put("payload", payload);

        SecretKey key = generalKey();
        JwtBuilder builder = Jwts.builder()
            .setClaims(claims)
            .signWith(SignatureAlgorithm.HS256, key);
        return builder.compact();
    }

    public static Claims parseTokenJWT(String jwt) {
        SecretKey key = generalKey();
        Claims claims = Jwts.parser()
            .setSigningKey(key)
            .parseClaimsJws(jwt)
            .getBody();

        Long time = ((Number) claims.get("time")).longValue();
        Long duration = ((Number) claims.get("duration")).longValue();
        if (new Date().getTime() - time > 1000L * duration) {
            throw new IllegalStateException("JWT token expired");
        }
        return claims;
    }

    private static SecretKey generalKey() {
        byte[] encodedKey = JWT_SECRET.getBytes(StandardCharsets.UTF_8);
        return new SecretKeySpec(encodedKey, 0, encodedKey.length, "HmacSHA256");
    }
}

如果项目使用 jjwt 旧版本，代码结构可与上例保持一致；如果使用新版 jjwt-api、jjwt-impl 和 jjwt-jackson 拆分依赖，应按当前库版本调整签名和解析方法。联调时建议先在服务端生成 token 并解析校验，再把 token 放入 /account/tokenLogin.do 或 /api/authorizeByJWT.do 验证跳转和授权流程。

API 分组

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

单接口页面

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

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