# 获取文件访问记录
获取文档、电子表格、多维表格等文件的历史访问记录，包括访问者的 ID、姓名、头像和最近访问时间。
## 请求
基本 |
---|---
HTTP URL | https://open.feishu.cn/open-apis/drive/v1/files/:file_token/view_records
HTTP Method | GET
接口频率限制 | [1000 次/分钟、50 次/秒](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App、Store App
权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用**
开启任一权限即可 | 获取用户基本信息(contact:user.base:readonly)
获取文档访问记录(drive:file:view_record:readonly)
### 请求头
名称 | 类型 | 必填 | 描述
---|---|---|---
Authorization | string | 是 | `tenant_access_token`
或
`user_access_token`
**值格式**："Bearer `access_token`"
**示例值**："Bearer u-7f1bcd13fc57d46bac21793a18e560"
[了解更多：如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)
### 路径参数
名称 | 类型 | 描述
---|---|---
file_token | string | 文件 token。获取方式参考[文件概述](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/file/file-overview)。
**示例值**："XIHSdYSI7oMEU1xrsnxc8fabcef"
### 查询参数
名称 | 类型 | 必填 | 描述
---|---|---|---
page_size | int | 是 | 分页大小
**示例值**：10
**数据校验规则**：
- 取值范围：`1` ～ `50`
page_token | string | 否 | 分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果
**示例值**：1674037112--7189934631754563585
file_type | string | 是 | 文件类型
**示例值**：docx
**可选值有**：
- doc：旧版文档
- docx：新版文档
- sheet：电子表格
- bitable：多维表格
- mindnote：思维笔记
- wiki：知识库文档
- file：文件
viewer_id_type | string | 否 | 返回的访问者 ID 的类型。
**当值为`user_id`时，字段权限要求**：
获取用户 user ID(contact:user.employee_id:readonly)
**示例值**：open_id
**可选值有**：
- user_id：标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。[了解更多：如何获取 User ID？](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-user-id)
- union_id：标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。[了解更多：如何获取 Union ID？](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-union-id)
- open_id：标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。[了解更多：如何获取 Open ID](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid)
**默认值**：`open_id`
## 响应
### 响应体
名称 | 类型 | 描述
---|---|---
code | int | 错误码，非 0 表示失败
msg | string | 错误描述
data | \- | \-
items | file.view_record\[\] | 访问记录列表
viewer_id | string | 访问者 ID
name | string | 访问者姓名
avatar_url | string | 访问者头像的 URL
last_view_time | string | 最近访问时间。Unix 时间戳，单位为秒。
page_token | string | 分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token
has_more | boolean | 是否还有更多项
### 响应体示例
```json
{
"code": 0,
"msg": "success",
"data": {
"items": [
{
"viewer_id": "ou_cc19b2bfb93f8a44db4b4d6eababcef",
"name": "zhangsan",
"avatar_url": "https://foo.icon.com/xxxx",
"last_view_time": "1679284285"
}
],
"page_token": "1674037112--7189934631754563585",
"has_more": true
}
}
```
### 错误码
HTTP状态码 | 错误码 | 描述 | 排查建议
---|---|---|---
500 | 1069601 | server internal error | 服务内部错误，包括服务端内部超时、错误码没处理等。
400 | 1069602 | invalid param | 参数异常，可能原因如下：
* 参数类型不匹配，如：文档的 token 和 type 不匹配。
* 参数填写异常，如 page_size 小于等于 0
403 | 1069603 | forbidden | 无权限操作，可能是如下原因：
* 调用身份无文档管理权限
* 当前租户未开启文档访问记录功能
请参考以下方式为调用身份开通文档管理权限：
- 如果你使用的是 `tenant_access_token`，意味着当前应用没有云文档权限。你需通过云文档网页页面右上方 **「...」** -> **「...更多」** ->**「添加文档应用」** 入口为应用添加管理权限。
**注意**：在 **添加文档应用** 前，你需确保目标应用至少开通了一个云文档或多维表格的 [API 权限](https://open.feishu.cn/document/ukTMukTMukTM/uYTM5UjL2ETO14iNxkTN/scope-list)。否则你将无法在文档应用窗口搜索到目标应用。
- 如果你使用的是 `user_access_token`，意味着当前用户没有云文档权限。你需通过云文档网页页面右上方 **分享** 入口为当前用户添加管理权限。
了解具体操作步骤或其它添加权限方式，参考[云文档常见问题 3](https://open.feishu.cn/document/ukTMukTMukTM/uczNzUjL3czM14yN3MTN#16c6475a)。
404 | 1069604 | not found | `file_token` 对应的文件在云空间中不存在。可能原因与解决方案如下所示：
- 文件不存在或 token 填写错误：请检查是否正确填写了 `file_token`。放置在云空间文件夹中的文件和知识库中的文件，其 token 获取方式不同。详情参考[文件概述-文件 token 获取方式](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/file/file-overview)。
- 文件类型不匹配：请求中提供的 `file_type` 与 `file_token` 对应的实际文件的类型不匹配。请检查 `file_type` 的类型是否与文件的实际类型一致。