服务端 API/云文档/云空间/事件/订阅云文档事件
# 订阅云文档事件
订阅云文档的各类通知事件。调用该接口并在开发者后台添加事件后，当云文档发生指定事件时，系统会向配置的地址发送事件。
**注意事项**：了解事件订阅的整体流程，参考[事件概述](https://open.larksuite.com/document/ukTMukTMukTM/uUTNz4SN1MjL1UzM)。了解云文档支持的事件类型，参考[事件列表](https://open.larksuite.com/document/ukTMukTMukTM/uYDNxYjL2QTM24iN0EjN/event-list)。
## 注意事项
- 文档管理者仅能接收到[文件编辑](https://open.larksuite.com/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/event/file-edited)、[多维表格字段变更](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/file/events/bitable_field_changed)、[多维表格记录变更](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/file/events/bitable_record_changed)事件。
- 若应用是以应用身份（`tenant_access_token`） 订阅的事件，在接收事件时需要同时申请应用和用户两个身份接收事件的权限。例如，要订阅 [文件夹下文件创建](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/file/events/created_in_folder) 事件，你需要在开发者后台，为应用同时开通两个身份的 `space:document.event:read` 权限。
## 前提条件
- 调用该接口之前，请确保在开发者后台配置了订阅方式并添加了具体事件。详情参考[配置订阅方式](https://open.larksuite.com/document/ukTMukTMukTM/uYDNxYjL2QTM24iN0EjN/event-subscription-configure-/request-url-configuration-case)和[添加事件](https://open.larksuite.com/document/ukTMukTMukTM/uYDNxYjL2QTM24iN0EjN/event-subscription-configure-/subscription-event-case)。
- 文档的通知事件仅支持文档拥有者和文档管理者订阅。调用接口前请确保应用或用户具有文档可管理权限。
## 请求
基本 |
---|---
HTTP URL | https://open.larksuite.com/open-apis/drive/v1/files/:file_token/subscribe
HTTP Method | POST
接口频率限制 | [1000 次/分钟、50 次/秒](https://open.larksuite.com/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App、Store App
权限要求
**调用该 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](https://open.larksuite.com/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)
### 路径参数
名称 | 类型 | 描述
---|---|---
file_token | string | 云文档的 token。了解如何获取各类云文档的 token，参考[云空间常见问题](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/faq)。
**示例值**："doccnfYZzTlvXqZIGTdAHKabcef"
### 查询参数
名称 | 类型 | 必填 | 描述
---|---|---|---
file_type | string | 是 | 云文档类型
**示例值**：docx
**可选值有**：
- doc：旧版文档。已不推荐使用
- docx：新版文档
- sheet：电子表格
- bitable：多维表格
- file：文件
- folder：文件夹
- slides：幻灯片
event_type | string | 否 | 事件类型。
- 若 `file_type` 为 `folder`，需要填写该字段，且字段必须填写为 `file.created_in_folder_v1`，表示订阅[文件夹下文件创建](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/file/events/created_in_folder)事件
- 若 `file_type` 不为 `folder`，请勿填写该字段。对于文档、电子表格、多维表格等云文档类型，目前仅支持订阅所有相关的云文档事件，暂不支持只订阅该云文档类型下的某个或某些事件
**示例值**：file.created_in_folder_v1
## 响应
### 响应体
名称 | 类型 | 描述
---|---|---
code | int | 错误码，非 0 表示失败
msg | string | 错误描述
data | \- | \-
### 响应体示例
```json
{
"code": 0,
"msg": "success",
"data": {}
}
```
### 错误码
HTTP状态码 | 错误码 | 描述 | 排查建议
---|---|---|---
500 | 1069601 | fail | 重试，若稳定失败请联系[技术支持](https://applink.larksuite.com/client/helpdesk)
400 | 1069602 | param error | 检查参数有效性
403 | 1069603 | forbidden | 无权限操作，可能是如下原因：
* 调用身份无文档管理权限
* 当前租户未开启文档访问记录功能
请参考以下方式为调用身份开通文档管理权限：
- 如果你使用的是 `tenant_access_token`，意味着当前应用没有云文档权限。你需通过云文档网页页面右上方 **「...」** -> **「...更多」** ->**「添加文档应用」** 入口为应用添加管理权限。
**注意**：在 **添加文档应用** 前，你需确保目标应用至少开通了一个云文档或多维表格的 [API 权限](https://open.larksuite.com/document/ukTMukTMukTM/uYTM5UjL2ETO14iNxkTN/scope-list)。否则你将无法在文档应用窗口搜索到目标应用。
- 如果你使用的是 `user_access_token`，意味着当前用户没有云文档权限。你需通过云文档网页页面右上方 **分享** 入口为当前用户添加管理权限。
了解具体操作步骤或其它添加权限方式，参考[云文档常见问题 3](https://open.larksuite.com/document/ukTMukTMukTM/uczNzUjL3czM14yN3MTN#16c6475a)。
400 | 1069604 | document not found | 检查文件是否存在