# 文档预览

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

## 获取文件信息

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

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

:::tip 提示
1. 遵循「文件ID一致性」原则：接口中文件「请求ID」 和 「返回ID」需保持一致

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

参数：

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

返回值：

| 字段        | 必须 | 类型    | 说明                                                                           |
| ----------- | ---- | ------- |------------------------------------------------------------------------------|
| id          | 是   | string  | 文档 ID，必须与传入的file_id一致，最大长度 47                                                |
| name        | 是   | string  | 文档名称，最大长度 240，不能包含下列特殊字符：\\/\|":\*?<>                                        |
| version     | 是   | integer | 文档版本号，无符号 int32 位，从 1 开始，每次[保存](/app-integration-dev/docs-center/online-preview-edit/callback/save.html)后递增，如果已经迭代了多个版本，这里您需要返回最新的版本号 |
| 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 指定该用户是否具有下载文档权限。
此接口用于标识用户具备哪些操作权限，具体的功能支持还需您的服务实现相关回调。

:::warning 注意


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

- 当 `update=1`时必须返回当前用户的 `user_id`，并且需要实现[用户信息](/app-integration-dev/docs-center/online-preview-edit/callback/user.html#用户信息)、[文档编辑](/app-integration-dev/docs-center/online-preview-edit/callback/save.html) 接口，[控制台](https://solution.wps.cn/console)中打开对应的回调接口开关

- 当 `print=1`时必须返回当前用户的 `user_id`，并且需要实现[用户信息](/app-integration-dev/docs-center/online-preview-edit/callback/user.html#用户信息)接口，[控制台](https://solution.wps.cn/console)中打开对应的回调接口开关

- 当 `rename=1` 时需要实现 [文档重命名](/app-integration-dev/docs-center/online-preview-edit/callback/extend.html#文档重命名) 接口

- 当 `history=1` 时需要实现 [历史版本相关接口](/app-integration-dev/docs-center/online-preview-edit/callback/extend.html#%E5%8E%86%E5%8F%B2%E7%89%88%E6%9C%AC%E7%9B%B8%E5%85%B3%E6%8E%A5%E5%8F%A3) 接口。

  请注意 history 是用来控制：是否可见预览历史版本入口。
  入口如下图：
  ![历史版本预览](https://cloudcdn.qwps.cn/open/kingsoft_open_docs/solutions_img/dd4c6dde9f.png)

   ----
 
  **如果要控制右上角 `历史版本`入口的显隐，或者禁用。**
  
  有2种方式供您参考：
  1. 到[控制台](https://solution.wps.cn/console)，应用管理-app-文档配置-历史版本-`只读模式下是否允许打开历史记录 和 协作记录` 打开开关
  2. JSSDK 代码纯前端控制（支持禁用和隐藏）。更多的类似的入口控制可参考[自定义配置项](https://solution.wps.cn/examples/run?id=9)
  ```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. 如若您的业务需要只读评论，请到 [控制台](https://solution.wps.cn/console)，应用管理-app-文档配置-筛选对应组件分类-评论功能-`是否只读权限下可评论` 打开开关
- 当`comment = 0`。需要注意:
  1. WebOffice默认评论也属于文档的一部分，所以当 update=1 的编辑模式下，comment=0 无法控制评论禁用。
  2. 如若您的业务需要禁用评论功能，请到 [控制台](https://solution.wps.cn/console)，应用管理-app-文档配置-筛选对应组件分类-评论功能-`是否禁用评论功能` 打开开关
:::

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

参数：

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

返回值：

| 字段     | 必须 | 类型    | 说明                                                                            |
| -------- | ---- | ------- | ------------------------------------------------------------------------------- |
| user_id  | 否   | string  | 当前用户 Id，当 `update=1`；`print=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权限

3. 格式刷功能失效 ?

    答：格式刷功能依赖剪切板，需要开启copy=1复制权限

:::