Univer Server 集成协议

USIP 介绍

USIP: Univer Server Integration Protocol (Univer 服务集成协议) ，

术语表

• USIP Client: 发起 USIP 请求的一端，一般是 Univer Server
• USIP Server: 实现了 USIP 并提供服务的一端，一般是 Third-party Server

USIP 指的是第三方系统集成 Univer Server 时所要遵循的协议，具体来说，即需要实现 USIP 约定的一系列接口。

Univer Server 基于这一系列协议可以访问第三方系统，以获得客户所需要的结果。

这样一来，在保证数据依然保留在第三方客户系统内部的同时，Univer Server 也可以成功集成进客户系统。

前提

1. 集成方需要自己维护 用户 - 文档 之间的关系，univer server 作为客户端通过接口获取文档下的用户权限
2. 实现：调用 univer server 创建文档成功后，会返回一个 unitID 文档 id，集成方需要对其进行存储，以实现自己的文件管理业务。接口可从这里获取。

需要实现的接口

！！！ 重要

1. 只有 Credential verify 接口会转发鉴权头信息用于鉴权外部浏览器 web 调用，其他接口用于业务内部接口，不会转发。
   
2. userID 是字符串类型。
   
3. 确保 USIP server 端网络能通，能被 univer 服务调用到。
   
4. 验证过程遇到问题时，可以在 USIP server 端打印查看日志，同时排查 univer 服务日志，以及对比文档和自己代码的实现是否有差异（比如返回值结构不匹配、返回值类型不匹配等）
   

1. Credential verify：验证用户身份合法性 (AuthN)

• Univer server 接口会验证用户身份，当被调用时会将请求的 http header 都转发到 USIP server 的 credential verify 接口进行身份验证
• credential verify 接口如果校验成功，需要返回 User 结构数据，后续 Univer server 业务会使用到用户唯一标识符 userID

curl -X GET \
  -H "authorization: xx" \
  -H "cookie: xx" \
  -H "YOUR-CUSTOM-HEADER: xx" \
  "http://localhost:8080/credential"
    
# response
{
  "user": {
    "userID": "xxx",
    "name": "xxx",
    "avatar": "xxx",
  }
}

2. UserInfo 批量获取

• UserInfo 批量获取接口需要接收一个 userIDs 字符串数组参数，数组元素是用户标识符 userID
• 接口返回值是一个 User 数组
• userIDs 数组长度最大为 100
• 0.2.9 版本之后（不包括 0.2.9），该接口的 GET 请求会被废弃

curl -X POST "http://localhost:8080/userinfo" \
  -H 'content-type: application/json' \
  --data-raw '{"userIDs":["1","2"]}'
 
# response
{
  "users": [
    {"userID": "1", "name":"xxx", "avatar":"https://xxxx"},
    {"userID": "2", "name":"xxx", "avatar":"https://xxxx"},
  ]
}

3. Permission role：获取特定用户对特定文档的权限 (AuthZ)

• USIP server 需要自己维护用户对文档的管理权限，目前 Univer server 预定义了几个角色：

• Permission role 接口接收一个 unitID 参数标识文档 id 和一个 userID 参数标识用户

curl -X GET "http://localhost:8080/role?unitID=xxx&userID=xxx"
 
# response
{
  "userID": "xxx",
  "role": "owner"
}

4. Get Collaborator List：获取文档的协作者列表

• Get Collaborator List 需要接收一个 unitIDs 字符串数组，表示可以同时获取多个文档的协作者
• unitIDs 数组长度最大为 100
• 0.2.9 版本之后（不包括 0.2.9），该接口的 GET 请求会被废弃

curl -X POST "http://localhost:8080/collaborators" \
  -H 'content-type: application/json' \
  --data-raw '{"unitIDs":["AA","BB"]}'
 
# response
{
  "collaborators": [
    {
      "unitID":"AA",
      "subjects":[
        {
          "subject": {
            "id": "1",
            "name": "xx",
            "avatar": "xxx",
            "type": "user"
          },
          "role":"owner"
        },
        {
          "subject": {
            "id": "2",
            "name": "xx",
            "avatar": "xxx",
            "type": "user"
          },
          "role":"editor"
        },
      ]
    },
  ]
}

Univer server 服务配置

需要将上述接口地址配置到 docker-compose 目录下的 .env 文件，开启 USIP 功能，重启服务

# usip about
USIP_ENBALED=true
USIP_URI_CREDENTIAL=http://localhost:8080/credential
USIP_URI_USERINFO=http://localhost:8080/userinfo
USIP_URI_ROLE=http://localhost:8080/role
USIP_URI_COLLABORATORS=http://localhost:8080/collaborators

常见问题

1. 如果你想让 unit 默认能被所有人编辑或查看，可以在 .env 文件中设置：

AUTH_PERMISSION_ENABLED=true
AUTH_PERMISSION_DEFAULT_SHARE_SCOPE=public
AUTH_PERMISSION_DEFAULT_SHARE_ROLE=editor

• AUTH_PERMISSION_DEFAULT_SHARE_ROLE：支持的配置有 editor， reader。

2. AUTH_PERMISSION_ENABLE_OBJ_INHERIT 控制文档管理员是否具有所有权限，true开启，false关闭。

代码例子

可查看 usip-example (opens in a new tab)