飞书开放平台 Server API 文档

主题

获取文档基本信息 ​

获取文档标题和最新版本 ID。

Tip: 应用频率限制：单个应用调用频率上限为每秒 5 次，超过该频率限制，接口将返回 HTTP 状态码 400 及错误码 99991400。当请求被限频，应用需要处理限频状态码，并使用指数退避算法或其它一些频控策略降低对 API 的调用速率。

前提条件 ​

调用此接口前，请确保当前调用身份（tenant_access_token 或 user_access_token）已有云文档的阅读、编辑等文档权限，否则接口将返回 HTTP 403 或 400 状态码。了解更多，参考如何为应用或用户开通文档权限。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/docx/v1/documents/:document_id
HTTP MethodGET
接口频率限制特殊频控
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可docx:document 创建及编辑新版文档 docx:document:readonly 查看新版文档

请求头 ​

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

路径参数 ​

名称类型描述
document_idstring文档的唯一标识。你可通过以下方式获取文档的 document_id。了解更多，参考文档概述。
- 若文档存储在云盘中，你可通过 URL 地址或通过获取文件夹下文件清单 获取其中文档资源的 document_id。
- 若文档挂载在知识库中，你需通过知识库相关接口获取知识空间节点信息获取该节点下挂载的云资源的 obj_token 和 obj_type。在该情况下，obj_type 为 docx 时，其对应的 obj_token 即为文档的 document_id。
注意：
对于知识库（wiki）中的文档，其 URL 地址中的 token 并不是该文档的 document_id。使用时请注意区分。
示例值："doxcnePuYufKa49ISjhD8Iabcef"
数据校验规则：
- 长度范围：27 ～ 27 字符

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ documentdocument文档信息
    └ document_idstring文档的唯一标识。点击这里了解如何获取文档的 document_id
    └ revision_idint文档版本 ID。起始值为 1
    └ titlestring文档标题
    └ display_settingdocument_display_setting文档展示设置
      └ show_authorsboolean文档信息中是否展示文档作者
      └ show_create_timeboolean文档信息中是否展示文档创建时间
      └ show_pvboolean文档信息中是否展示文档访问次数
      └ show_uvboolean文档信息中是否展示文档访问人数
      └ show_like_countboolean文档信息中是否展示点赞总数
      └ show_comment_countboolean文档信息中是否展示评论总数
      └ show_related_mattersboolean文档信息中是否展示关联事项。暂未支持
    └ coverdocument_cover文档封面
      └ tokenstring图片 token
      └ offset_ratio_xnumber(float)视图在水平方向的偏移比例。其值为距离原图中心的水平方向偏移值 px / 原图宽度 px。 视图在原图中心时，该值为 0； 视图在原图右部分时，该值为正数； 视图在原图左部分时，该值为负数。
      └ offset_ratio_ynumber(float)视图在垂直方向的偏移比例。其值为距离原图中心的垂直方向偏移值 px / 原图高度 px。 视图在原图中心时，该值为 0； 视图在原图上部分时，该值为正数； 视图在原图下部分时，该值为负数。

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "document": {
            "document_id": "doxcni6mOy7jLRWbEylaKKabcef",
            "revision_id": 1,
            "title": "title",
            "cover": {
                "token": "D6d9bkdH7onNylxKyvucm8abcef",
                "offset_ratio_x": 0,
                "offset_ratio_y": 0
            },
            "display_setting": {
                "show_authors": true,
                "show_comment_count": false,
                "show_create_time": true,
                "show_like_count": false,
                "show_pv": false,
                "show_uv": false
            }
        }
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
4001770001invalid param确认传入的参数是否合法
4041770002not found文档的 document_id 不存在。请确认文档是否已被删除或 document_id 是否填写正确。 - 若文档存储在云盘中，你可通过 URL 地址或通过获取文件夹下文件清单 获取其中文档资源的 document_id。 - 若文档挂载在知识库中，你需通过知识库相关接口获取知识空间节点信息获取该节点下挂载的云资源的 obj_token 和 obj_type。在该情况下，obj_type 为 docx 时，其对应的 obj_token 即为文档的 document_id。 注意： 对于知识库（wiki）中的文档，其 URL 地址中的 token 并不是该文档的 document_id。使用时请注意区分。了解更多，参考文档概述。
4001770003resource deleted确认资源是否已被删除
4001770004too many blocks in document确认文档 Block 数量是否超上限
4001770005too deep level in document确认文档 Block 层级是否超上限
4001770006schema mismatch确认文档结构是否合法
4001770007too many children in block确认指定 Block 的 Children 数量是否超上限
4001770008too big file size确认上传的文件尺寸是否超上限
4001770010too many table column确认表格列数是否超上限
4001770011too many table cell确认表格单元格数量是否超上限
4001770012too many grid column确认 Grid 列数量是否超上限
4001770013relation mismatch图片、文件等资源的关联关系不正确。请确保在创建图片、文件块时，同时上传了相关图片或文件素材至对应的文档块中。详情参考文档常见问题 3 和 4
4001770014parent children relation mismatch确认 Block 父子关系是否正确
4001770015single edit with multi document确认 Block 所属文档与指定的 Document 是否相同
4001770019repeated blockID in document确认 Document 中的 BlockID 是否有重复
4001770020operation denied on copying document确认 Document 是否正在创建副本中
4001770021too old document确认指定的 Document 的版本（revision_id）是否过旧
4001770022invalid page token确认查询参数中的 page_token 是否合法
4001770024invalid operation确认操作是否合法
4001770025operation and block not match确认指定 Block 应用对应操作是否合法
4001770026row operation over range确认行操作下标是否越界
4001770027column operation over range确认列操作下标是否越界
4001770028block not support create children确认指定 Block 添加 Children 是否合法
4001770029block not support to create确认指定 Block 是否支持创建
4001770030invalid parent children relation确认指定操作其父子关系是否合法
4001770031block not support to delete children确认指定 Block 是否支持删除 Children
4001770033raw content size exceed limited纯文本内容大小超过限制
4001770034operation count exceed limited当前请求中涉及单元格个数过多，请拆分成多次请求
4031770032forbidden确认当前调用身份是否有文档阅读（获取相关接口）或编辑（更新、删除、创建相关接口）权限。请参考以下方式解决： - 如果你使用的是 tenant_access_token，意味着当前应用没有文档权限。你需通过云文档网页页面右上方 「...」 -> 「...更多」 ->「添加文档应用」 入口为应用添加文档权限。 说明：在 添加文档应用 前，你需确保目标应用至少开通了一个云文档或多维表格的 API 权限。否则你将无法在文档应用窗口搜索到目标应用。 - 如果你使用的是 user_access_token，意味着当前用户没有文档权限。你需通过云文档网页页面右上方 分享 入口为当前用户添加文档权限。 image.png 了解具体操作步骤或其它添加权限方式，参考云文档常见问题 3。 对于创建和更新相关接口，你还需要确认： - 当前调用身份是否有 MentionDoc 即 @文档 中文档的阅读权限 - MentionUser 即 @用户 中的用户是否在职且与当前调用身份互为联系人 - 当前调用身份是否具有群卡片的查看和分享权限 - 当前调用身份是否具有访问指定 Wiki 即知识库子目录的权限 - 当前调用身份是否具有 OKR、ISV、Add-Ons 等文档块的查看权限
5001771001server internal error服务器内部错误
5001771006mount folder failed挂载文档到云空间文件夹失败
5001771002gateway server internal error网关服务内部错误
5001771003gateway marshal error网关服务解析错误
5001771004gateway unmarshal error网关服务反解析错误
5031771005system under maintenance系统服务正在维护中

内容来源：飞书开放平台 · 自动爬取整理

本镜像仅供学习与查阅，文档版权归飞书所有