Skip to content
本页内容

文档预览

本节介绍文档预览相关的接口,接入方必须全部实现才能正常打开并预览文档。

获取文件信息

接口:GET /v3/3rd/files/:file_id

说明:该接口用于获取文件的基本信息,在文档打开以及编辑过程中,都需要这些基本信息作为文件的标识与展示,如文档 ID 需要在接入方系统中能唯一标识一份文档。

提示

🔔 遵循「文件ID一致性」原则:接口中文件「请求ID」 和 「返回ID」需保持一致

📝 文件ID不一致有可能影响某些功能的正常使用

参数:

字段位置必须类型说明
file_id
Path
string
文档 ID

返回值:

字段必须类型说明
id
string
文档 ID,必须与传入的file_id一致,最大长度 47
name
string
文档名称,最大长度 240,不能包含下列特殊字符:\/|":*?<>
version
integer
文档版本号,无符号 int32 位,从 1 开始,每次保存后递增,如果已经迭代了多个版本,这里您需要返回最新的版本号
size
integer
文档大小,单位 byte
create_time
integer
文档创建时间戳,单位纪元秒
modify_time
integer
文档最后修改时间戳,单位纪元秒
creator_id
string
文档创建者 Id
modifier_id
string
文档最后修改者 Id

返回值示例:

json
{
  "code": 0,
  "data": {
    "create_time": 1670218748,
    "creator_id": "404",
    "id": "9",
    "modifier_id": "404",
    "modify_time": 1670328304,
    "name": "统计月报.xlsx",
    "size": 18961,
    "version": 180
  }
}

获取文件下载地址

说明:在线协同系统需要下载文件原件以提供协同服务,该接口需要返回指定文件 ID 所对应的下载地址

接口: GET /v3/3rd/files/:file_id/download

参数:

字段位置必须类型说明
file_id
Path
string
文档 Id

返回值:

字段必须类型说明
url
string
文档下载地址,该地址需确保外网可访问且排除访问时防火墙的限制
digest
string
文档校验和 (checksum)
digest_type
string
文档校验和算法 md5 或者 sha1
headers
map<string, string>
请求文档下载地址所需要的额外请求头,例如某些云存储商会要求额外的签名头等

返回值示例:

json
{
  "code": 0,
  "data": {
    "url": "https://foo.bar.com/files/9/180"
  }
}

文档用户权限

说明:任何需要用户鉴权的行为都会触发该接口的调用,并且 WebOffice 会根据指定的权限位来限定特定的操作,如 download 指定该用户是否具有下载文档权限。 此接口用于标识用户具备哪些操作权限,具体的功能支持还需您的服务实现相关回调。

注意

开发者务必了解下列描述中的规则,减少您在开发过程中的疑问。

  • update=1时必须返回当前用户的 user_id,并且需要实现 文档编辑 接口,控制台中打开对应的回调接口开关

  • rename=1 时需要实现 文档重命名 接口

  • history=1 时需要实现 历史版本相关接口 接口。

    请注意 history 是用来控制:是否可见预览历史版本入口。 入口如下图: 历史版本预览


    如果要控制右上角 历史版本入口的显隐,或者禁用。

    有2种方式供您参考:

    1. 控制台,应用管理-app-文档配置-历史版本-只读模式下是否允许打开历史记录 和 协作记录 打开开关
    2. JSSDK 代码纯前端控制(支持禁用和隐藏)。更多的类似的入口控制可参考自定义配置项
    js
    WebOfficeSDK.init({
      fileId: 'xxx',
      officeType: 'w',
      appId: 'xxx',
      commandBars: [
        {
          cmbId: 'HeaderHistoryMenuBtn',
          attributes: {
            visible: false,
            enable: false
          }
        }
      ]
    })
    
  • comment = 1。 需要注意:

    1. WebOffice默认评论也属于文档的一部分,所以当 read=1 , update=0 的只读模式下,comment=1 无法控制评论可用。
    2. 如若您的业务需要只读评论,请到 控制台,应用管理-app-文档配置-筛选对应组件分类-评论功能-是否只读权限下可评论 打开开关
  • comment = 0。需要注意:

    1. WebOffice默认评论也属于文档的一部分,所以当 update=1 的编辑模式下,comment=0 无法控制评论禁用。
    2. 如若您的业务需要禁用评论功能,请到 控制台,应用管理-app-文档配置-筛选对应组件分类-评论功能-是否禁用评论功能 打开开关

接口: GET /v3/3rd/files/:file_id/permission

参数:

字段位置必须类型说明
file_id
Path
string
文档 Id

返回值:

字段必须类型说明
user_id
string
当前用户 Id,当 update=1时必须返回当前用户的 user_id
read
integer
是否具有预览权限,0-无 1-有
update
integer
是否具有编辑权限,0-无 1-有
download
integer
是否具有下载文档权限,0-无 1-有
rename
integer
是否具有重命名文档权限,0-无 1-有
history
integer
是否具有查看文档历史记录权限,0-无 1-有
copy
integer
是否具有拷贝文档内容权限,0-无 1-有
print
integer
是否具有打印文档权限,0-无 1-有
saveas
integer
是否具有另存当前文档权限,0-无 1-有。该属性现阶段暂无相关入口,开发者可不用关注
comment
integer
是否具有评论文档权限,0-无 1-有。

返回值示例:

json
{
  "code": 0,
  "data": {
    "comment": 1,
    "copy": 1,
    "download": 1,
    "history": 1,
    "print": 1,
    "read": 1,
    "rename": 1,
    "saveas": 1,
    "update": 1,
    "user_id": "404"
  }
}

TIP

关于权限接口,还有几个常见JSSDK调用失败,和permission接口相关的问题。

  1. JSSDK调用 ExportAsFixedFormat 导出的时候,提示类似"permission denied",或者network中看到/export 接口提示"permission denied" ?

    答:导出图片,至少需要 read=1 和download=1 ,permission需要返回user_id, 并且通过 /v3/3rd/users 能查到该用户

  2. JSSDK调用 GetHtmlData 获取文档html数据,控制台提示 Cannot create property 'message’ on string 'permission denied' ?

    答:获取文档内的数据,需要开启copy=1权限