订阅云文档事件

订阅云文档的各类通知事件。调用该接口并在开发者后台添加事件后，当云文档发生指定事件时，系统会向配置的地址发送事件。

Tip: 了解事件订阅的整体流程，参考事件概述。了解云文档支持的事件类型，参考事件列表。

注意事项

• 文档管理者仅能接收到文件编辑、多维表格字段变更、多维表格记录变更事件。
• 若应用是以应用身份（tenant_access_token） 订阅的事件，在接收事件时需要同时申请应用和用户两个身份接收事件的权限。例如，要订阅 文件夹下文件创建 事件，你需要在开发者后台，为应用同时开通两个身份的 space:document.event:read 权限。

前提条件

• 调用该接口之前，请确保在开发者后台配置了订阅方式并添加了具体事件。详情参考配置订阅方式和添加事件。
• 文档的通知事件仅支持文档拥有者和文档管理者订阅。调用接口前请确保应用或用户具有文档可管理权限。

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/drive/v1/files/:file_token/subscribe
HTTP Method	POST
接口频率限制	1000 次/分钟、50 次/秒
支持的应用类型	custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可	docs:doc 查看、评论、编辑和管理文档 docs:event:subscribe 订阅云文档事件 drive:drive 查看、评论、编辑和管理云空间中所有文件 sheets:spreadsheet 查看、评论、编辑和管理电子表格

请求头

名称	类型	必填	描述
Authorization	string	是	tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token

路径参数

名称	类型	描述
file_token	string	云文档的 token。了解如何获取各类云文档的 token，参考云空间常见问题。 示例值："doccnfYZzTlvXqZIGTdAHKabcef"

查询参数

名称	类型	必填	描述
file_type	string	是	云文档类型 示例值：docx 可选值有： - doc: 旧版文档。已不推荐使用 - docx: 新版文档 - sheet: 电子表格 - bitable: 多维表格 - file: 文件 - folder: 文件夹 - slides: 幻灯片
event_type	string	否	事件类型。 - 若 file_type 为 folder，需要填写该字段，且字段必须填写为 file.created_in_folder_v1，表示订阅文件夹下文件创建事件 - 若 file_type 不为 folder，请勿填写该字段。对于文档、电子表格、多维表格等云文档类型，目前仅支持订阅所有相关的云文档事件，暂不支持只订阅该云文档类型下的某个或某些事件 示例值：file.created_in_folder_v1

响应

响应体

名称	类型	描述
code	int	错误码，非 0 表示失败
msg	string	错误描述
data	\-	-

响应体示例

{
    "code": 0,
    "msg": "success",
    "data": {}
}

错误码

HTTP状态码	错误码	描述	排查建议
500	1069601	fail	重试，若稳定失败请联系技术支持
400	1069602	param error	检查参数有效性
403	1069603	forbidden	无权限操作，可能是如下原因： * 调用身份无文档管理权限 * 当前租户未开启文档访问记录功能 请参考以下方式为调用身份开通文档管理权限： - 如果你使用的是 tenant_access_token，意味着当前应用没有云文档权限。你需通过云文档网页页面右上方 「...」 -> 「...更多」 ->「添加文档应用」 入口为应用添加管理权限。 注意：在 添加文档应用 前，你需确保目标应用至少开通了一个云文档或多维表格的 API 权限。否则你将无法在文档应用窗口搜索到目标应用。 - 如果你使用的是 user_access_token，意味着当前用户没有云文档权限。你需通过云文档网页页面右上方 分享 入口为当前用户添加管理权限。 了解具体操作步骤或其它添加权限方式，参考云文档常见问题 3。
400	1069604	document not found	检查文件是否存在