文档预览

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

获取文件信息

接口：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"
  }
}

TIP

下载地址设置了Referer防盗链时，需要在返回值headers返回自定义Referer请求头。

文档用户权限

说明：任何需要用户鉴权的行为都会触发该接口的调用，并且 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接口相关的问题。

JSSDK调用 ExportAsFixedFormat 导出的时候，提示类似"permission denied"，或者network中看到/export 接口提示"permission denied" ?
答：导出图片，至少需要 read=1 和download=1 ，permission需要返回user_id, 并且通过 /v3/3rd/users 能查到该用户
JSSDK调用 GetHtmlData 获取文档html数据，控制台提示 Cannot create property 'message’ on string 'permission denied' ?
答：获取文档内的数据，需要开启copy=1权限

文档预览 #

获取文件信息 #

获取文件下载地址 #

文档用户权限 #

文档预览

获取文件信息

获取文件下载地址

文档用户权限