通过 USIP 集成

Parameter	Type	Example	Description
`user`	`Object`	-	认证成功时，返回 user 对象
`userID`	`string`	ace55655ceabd55	用户的 ID，建议使用 open_uid
`name`	`string`	alice	用户名字，用于前端展示协作者信息
`avatar`	`string`	https://image.xx/acde55acb45bbead55	用户头像 URL，用于前端展示协作者信息

{  "user": {    "userID": "ace55655ceabd55g",    "name": "alice",    "avatar": "https://image.xx/acde55acb45bbead55"  }}

批量获取用户信息

调用场景

多人协作时展示头像和名字、评论列表展示作者信息。

交互流程

协议定义

POST

Headers

无自定义 header，也不会透传用户请求的 header

Body Parameters

Parameter	Type	Example	Description
`userIDs`	`array[string]`	["user_id1", "user_id2"]	用户 ID 数组

{  "userIDs": [    "user_id1",    "user_id2",    "user_id3"  ]}

Response

application/json

Parameter	Type	Example	Description
`users`	`array[Object]`	-	用户对象数组，结构同身份认证接口

{  "users": [    {      "userID": "user_id1",      "name": "name1",      "avatar": "https://xxxx"    },    {      "userID": "user_id2",      "name": "name2",      "avatar": "https://xxxx"    },    {      "userID": "user_id3",      "name": "name3",      "avatar": "https://xxxx"    }  ]}

用户权限角色获取

调用场景

用户读写文档时获取权限角色。

交互流程

协议定义

GET

Headers

无自定义 header，也不会透传用户请求的 header

Query Parameters

Parameter	Type	Example	Description
`userID`	`string`	acd5455e44fc5bb55	用户 ID
`unitID`	`string`	acff-adebc125e45b	文档 ID

curl -X GET "http://sample.univer.ai/role?unitID=acff-adebc125e45b&userID=acd5455e44fc5bb55"

Response

application/json

Parameter	Type	Example	Description
`userID`	`string`	acd5455e44fc5bb55	请求中的用户 ID
`role`	`string`	editor	角色：owner、editor、reader

{  "userID": "acd5455e44fc5bb55",  "role": "editor"}

获取文档的所有协作者

调用场景

在前端设置子表/保护选区权限时，需要获取协作者列表。

交互流程

协议定义

POST

Headers

无自定义 header，也不会透传用户请求的 header

Body Parameters

Parameter	Type	Example	Description
`unitIDs`	`array[string]`	["unit_id1", "unit_id2"]	文档 ID 数组

{  "unitIDs": [    "unit_id1",    "unit_id2",    "unit_id3"  ]}

Response

application/json

Parameter	Type	Example	Description
`collaborators`	`array[Object]`	-	文档协作者对象列表
`unitID`	`string`	unit_id1	文档 ID
`subjects`	`array[Object]`	-	协作者列表
`role`	`string`	editor	角色：owner、editor、reader
`subject`	`Object`	-	协作者信息
`type`	`string`	user	只能设置为 "user"
`id`	`string`	acdef12555b12	用户 ID
`name`	`string`	alice	用户名字
`avatar`	`string`	https://image.ai/36554	用户头像 URL

{  "collaborators": [    {      "unitID": "unit_id1",      "subjects": [        {          "subject": {            "id": "1",            "name": "alice",            "avatar": "https://image.ai/36554",            "type": "user"          },          "role": "owner"        },        {          "subject": {            "id": "2",            "name": "bob",            "avatar": "https://image.ai/36559",            "type": "user"          },          "role": "editor"        }      ]    }  ]}

通知文档最新修改时间

调用场景

用于业务侧展示文档更新时间等。

协议定义

POST

Headers

无自定义 header，也不会透传用户请求的 header

Body Parameters

Parameter	Type	Example	Description
`unitID`	`string`	acff-adebc125e45b	文档 ID
`editTimeUnixMs`	`int`	1762591632345	unix 时间戳（毫秒）

{  "unitID": "unit_id1",  "editTimeUnixMs": 1762591632345}

Response

application/json

Parameter	Type	Example	Description

{}

配置 USIP 接入

.env.custom

# usip about
USIP_ENABLED=true  # 设置为 true 以启用 USIP
USIP_URI_CREDENTIAL=https://your-domain/usip/credential # 配置好身份认证 USIP 的实现 URL
USIP_URI_USERINFO=https://your-domain/usip/userinfo     # 配置好用户信息获取 USIP 的实现 URL
USIP_URI_ROLE=https://your-domain/usip/role             # 配置好权限角色获取 USIP 的实现 URL
USIP_URI_COLLABORATORS=https://your-domain/usip/collaborators # 配置好协作者列表 USIP 的实现 URL
USIP_URI_UNITEDITTIME=https://your-domain/usip/unit-edit-time # 配置好接收文档修改时间 USIP 的实现 URL

USIP_APIKEY=

# auth about
AUTH_PERMISSION_ENABLE_OBJ_INHERIT=false  # 见下面权限设计说明
AUTH_PERMISSION_CUSTOMER_STRATEGIES=      # 见下面权限设计说明

values.yaml

universer:
  config:
    usip:
      enabled: true # 设置为 true 以启用 USIP
      uri:
        userinfo: 'https://your-domain/usip/userinfo' # 配置好用户信息获取 USIP 的实现 URL
        collaborators: 'https://your-domain/usip/collaborators' # 配置好协作者列表 USIP 的实现 URL
        role: 'https://your-domain/usip/role' # 配置好权限角色获取 USIP 的实现 URL
        credential: 'https://your-domain/usip/credential' # 配置好身份认证 USIP 的实现 URL
        unitEditTime: 'https://your-domain/usip/unit-edit-time' # 配置好接收文档修改时间 USIP 的实现 URL
      apikey: ''
    auth:
      permission:
        enableObjInherit: false # 见下面权限设计说明
        customerStrategies: '' # 见下面权限设计说明

注意：启用 USIP 后需配置全部 5 个接口，并确保你的系统正常响应。

如果你的 USIP 服务暴露在公网环境中，为了保证接口请求的安全性，我们可以参考 AI API 的鉴权方式。你可以生成一个 API key，并将其配置到 Univer server 中。当调用 USIP 接口时，请求会携带 x-api-key: API_KEY 的请求头，你可以通过该值来校验请求的合法性。

Univer 权限模型

Univer 使用 RBAC 模型，固定角色为 owner、editor、reader。可以通过配置为某些权限点位设置最低角色。

默认权限点位与最低角色如下：

权限点位	权限点位枚举值	点位含义	最低角色要求	角色枚举值
ManageCollaborator	2	邀请 / 删除文档协作者	owner	2
Copy	6	拷贝文档内容	reader	0
Print	3	打印	editor	1
Duplicate	4	复制文档	editor	1
Share	7	分享给他人	reader	0
Export	8	导出	editor	1
Comment	5	评论	reader	0
View	0	阅读	reader	0
MoveSheet	25	移动 worksheet	editor	1
DeleteSheet	26	删除 worksheet	editor	1
HideSheet	27	隐藏 worksheet	editor	1
CopySheet	28	复制 worksheet	editor	1
RenameSheet	29	重命名 worksheet	editor	1
CreateSheet	30	新增 worksheet	editor	1
SetCellStyle	33	设置单元格样式	editor	1
SetCellValue	34	设置单元格值	editor	1
InsertHyperlink	16	插入超链接	editor	1
Sort	17	排序	editor	1
Filter	18	过滤	editor	1
PivotTable	19	透视表	editor	1
RecoverHistory	43	恢复文档到历史版本	editor	1
ViewHistory	44	查看文档历史记录	reader	0
SelectProtectedCells	31	选择被保护区域单元格	editor	1
SelectUnProtectedCells	32	选择非保护区域单元格	editor	1
SetRowStyle	35	设置行样式	editor	1
SetColumnStyle	36	设置列样式	editor	1
InsertRow	37	插入行	editor	1
InsertColumn	38	插入列	editor	1
DeleteRow	39	删除行	editor	1
DeleteColumn	40	删除列	editor	1
Delete	42	删除文档	owner	2
CreatePermissionObject	45	创建保护区 / 保护子表	editor	1

若希望仅允许 owner 复制与打印：

.env.custom

AUTH_PERMISSION_CUSTOMER_STRATEGIES=[{"action": 3, "role": 2}, {"action": 6, "role": 2}]

K8s 配置：

values.yaml

universer:
  config:
    auth:
      permission:
        customerStrategies: '[ {"action": 3, "role": 2}, {"action": 6, "role": 2} ]'

对象权限继承

默认情况下，文档的 owner 并不自动拥有该文档内所有“保护区/子表”的 owner 权限。若需要开启继承：

.env.custom

AUTH_PERMISSION_ENABLE_OBJ_INHERIT=true

K8s 配置：

values.yaml

universer:
  config:
    auth:
      permission:
        enableObjInherit: true

客户系统集成 USIP 实现示例

参考我们的 USIP 示例源码

前端配置自定义请求头

当你需要在请求中添加自定义 header（如 Authorization token）时，可使用 HTTPService 拦截器：

import { HTTPService } from '@univerjs/preset-sheets-core'

// 通过 Univer 实例获取 injector
const injector = univer.__getInjector()
// 添加自定义请求头
const httpService = injector.get(HTTPService)
httpService.registerHTTPInterceptor({
  priority: 0,
  interceptor: (request, next) => {
    // 在这里添加你需要的请求头
    // 例如添加 Authorization token：
    // request.headers.set('Authorization', 'Bearer your-token-here')
    return next(request)
  },
})

import { HTTPService } from '@univerjs/network'

// 通过 Univer 实例获取 injector
const injector = univer.__getInjector()
// 添加自定义请求头
const httpService = injector.get(HTTPService)
httpService.registerHTTPInterceptor({
  priority: 0,
  interceptor: (request, next) => {
    // 在这里添加你需要的请求头
    // 例如添加 Authorization token：
    // request.headers.set('Authorization', 'Bearer your-token-here')
    return next(request)
  },
})

如果使用了历史记录，也需要为 HistoryUniver 追加同样的拦截器：

historyLoaderService.historyUniver$.subscribe((historyUniver) => {
  if (!historyUniver) return

  const injector = historyUniver.__getInjector()
  const httpService = injector.get(HTTPService)
  httpService.registerHTTPInterceptor({
    priority: 0,
    interceptor: (request, next) => {
      // 在这里添加你需要的请求头
      // 例如添加 Authorization token：
      // request.headers.set('Authorization', 'Bearer your-token-here')
      return next(request)
    },
  })
})

完整示例可参考 Univer Pro Sheet 启动套件。

目录