获取文件访问记录

获取文档、电子表格、多维表格等文件的历史访问记录，包括访问者的 ID、姓名、头像和最近访问时间。

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/drive/v1/files/:file_token/view_records
HTTP Method	GET
接口频率限制	1000 次/分钟、50 次/秒
支持的应用类型	custom,isv
权限要求 调用该 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

路径参数

名称	类型	描述
file_token	string	文件 token。获取方式参考文件概述。 示例值："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时，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID 示例值：open_id 可选值有： - user_id: 标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。了解更多：如何获取 User ID？ - union_id: 标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。了解更多：如何获取 Union ID？ - open_id: 标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。了解更多：如何获取 Open ID 默认值：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	是否还有更多项

响应体示例

{
    "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 权限。否则你将无法在文档应用窗口搜索到目标应用。 - 如果你使用的是 user_access_token，意味着当前用户没有云文档权限。你需通过云文档网页页面右上方 分享 入口为当前用户添加管理权限。 了解具体操作步骤或其它添加权限方式，参考云文档常见问题 3。
404	1069604	not found	file_token 对应的文件在云空间中不存在。可能原因与解决方案如下所示： - 文件不存在或 token 填写错误：请检查是否正确填写了 file_token。放置在云空间文件夹中的文件和知识库中的文件，其 token 获取方式不同。详情参考文件概述-文件 token 获取方式。 - 文件类型不匹配：请求中提供的 file_type 与 file_token 对应的实际文件的类型不匹配。请检查 file_type 的类型是否与文件的实际类型一致。