编辑文档内容 - 飞书 API

基本
HTTP URL	https://open.feishu.cn/open-apis/doc/v2/:docToken/batch_update
HTTP Method	POST
支持的应用类型	自建应用商店应用
权限要求开启任一权限即可	查看、评论、编辑和管理云空间中所有文件查看、评论、编辑和管理文档

请求头

名称	类型	必填	描述
Authorization	string	是	user_access_token 或 tenant_access_token值格式："Bearer `access_token`"示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560"了解更多：获取与使用access_token
Content-Type	string	是	固定值："application/json; charset=utf-8"

关于云文档接口的 AccessToken 调用说明详见云文档接口快速入门

请求体

参数	类型	必须	说明
docToken	string	是	文件的 token，获取方式见云文档接口快速入门
Revision	int	是	文档的指定版本，文档新创建后版本号是0，获取方式，要求>=0，post body json 字段
Requests	list	是	post body json， OperationRequest 类型序列化 string 数组

OperationRequest

{
    "requestType": string,
    "updateTitleRequest": {object(UpdateTitleRequest)},
    "deleteContentRangeRequest": {object(DeleteContentRangeRequest)},
    "insertBlocksRequest": {object(InsertBlocksRequest)},
    "insertParagraphElementsRequest": {object(InsertParagraphElementsRequest)},
    "insertTableRowRequest": {object(InsertTableRowRequest)},
    "insertTableColumnRequest": {object(InsertTableColumnRequest)},
    "deleteTableRowsRequest": {object(DeleteTableRowsRequest)},
    "deleteTableColumnsRequest": {object(DeleteTableColumnsRequest)},
    "updateTableColumnPropertiesRequest": {object(UpdateTableColumnPropertiesRequest)},
    "mergeTableCellsRequest": {object(MergeTableCellsRequest)},
    "unmergeTableCellsRequest": {object(UnmergeTableCellsRequest)}
    "replaceAllTextRequest": {object{ReplaceAllTextRequest}}
    "updateParagraphStyleRequest": {object{UpdateParagraphStyleRequest}}
}

字段说明

字段	类型	说明
requestType	string	OperationRequest: 传入下方的 request 字段（首字母需要大写） + 'Type'，例如 'UpdateTitleRequestType'。注意事项（未按照格式提供会报错）首字母需要大写添加 'Type'
updateTitleRequest	object	更新标题
deleteContentRangeRequest	object	范围删除
insertBlocksRequest	object	插入 blocks
insertParagraphElementsRequest	object	插入行内元素
insertTableRowRequest	object	格式化表格增加单行
insertTableColumnRequest	object	格式化表格增加单列
deleteTableRowsRequest	object	格式化表格删除多行
deleteTableColumnsRequest	object	格式化表格删除多列
updateTableColumnPropertiesRequest	object	格式化表格修改列宽度
mergeTableCellsRequest	object	格式化表格合并单元格
unmergeTableCellsRequest	object	格式化表格拆分单元格
ReplaceAllTextRequest	object	查找替换文本内容
UpdateParagraphStyleRequest	object	更新段落样式

InsertLocation

{
    "zoneId": string,
    "index": int,
    "startOfZone": bool,
    "endOfZone": bool
}

字段说明 :

字段	类型	说明
zoneId	string	编辑区域，包括两种，正文是 "0"，表格单元格 ID，例如 "xr1m4jw7egd9nefz1s0mdsetenl5fbe3lygxc1azupv81i5t2rjmosw5ta0esuwtn8ksya"
index	int	字符下标，标题占用索引，从 0 开始
startOfZone	bool	InsertBlocksRequestType支持便捷操作，插入zone开始位置，正文头部（不算标题）或单元格起始位置。true时index入参无效
endOfZone	bool	InsertBlocksRequestType支持便捷操作，插入zone尾部，正文尾部或单元格尾部。true时index入参无效

Range

范围删除结构，删除范围 [StartIndex, EndIndex)

{
   "zoneId": string,
   "startIndex": int,
   "endIndex": int
}

字段说明 :

字段	类型	说明
zoneId	string	编辑区域，包括两种，正文是 "0"，表格单元格 ID，例如 "xr1m4jw7egd9nefz1s0mdsetenl5fbe3lygxc1azupv81i5t2rjmosw5ta0esuwtn8ksya"
startIndex	int	删除起始位置
endIndex	int	删除结束位置

UpdateTitleRequest

{
    "payLoad": string
}

字段说明 :

字段	类型	说明
payLoad	string	文档数据结构概述 Title结构体序列化 string

请求示例

本示例将会把文档的标题修改为 Updated Document Title

{
  "Revision": 1,
  "Requests": [
      "{\"requestType\":\"UpdateTitleRequestType\",\"updateTitleRequest\":{\"payload\":\"{\\\"elements\\\":[{\\\"type\\\":\\\"textRun\\\",\\\"textRun\\\":{\\\"text\\\":\\\"Updated Document Title\\\",\\\"style\\\":{}}}],\\\"style\\\":{}}\"}}"
  ]
}

DeleteContentRangeRequest

{
    "deleteRange": {object(Range)}
}

字段说明 :

字段	类型	说明
deleteRange	object	删除范围

请求示例

本示例将会在文档中删除选定范围的内容

{
  "Revision": 1,
  "Requests": [
      "{\"requestType\":\"DeleteContentRangeRequestType\",\"deleteContentRangeRequest\":{\"deleteRange\":{\"zoneId\":\"0\",\"startIndex\":625,\"endIndex\":631}}}"
  ]
}

InsertBlocksRequest

{
    "payload": string,
    "location": {object(InsertLocation)}
}

字段说明 :

字段	类型	说明
payload	string	文档数据结构概述 Body结构体序列化string
location	object	插入位置

请求示例

本示例将会在文档中插入一行文本、一个 3x3 的普通表格和一个 3x3 的电子表格

{
  "Revision": 1,
  "Requests": [
      "{\"requestType\":\"InsertBlocksRequestType\",\"insertBlocksRequest\":{\"payload\":\"{\\\"blocks\\\":[{\\\"type\\\":\\\"paragraph\\\",\\\"paragraph\\\":{\\\"elements\\\":[{\\\"type\\\":\\\"textRun\\\",\\\"textRun\\\":{\\\"text\\\":\\\"Docs API Sample Content\\\",\\\"style\\\":{}}}],\\\"style\\\":{}}},{\\\"type\\\":\\\"table\\\",\\\"table\\\":{\\\"rowSize\\\":3, \\\"columnSize\\\":3}},{\\\"type\\\":\\\"sheet\\\",\\\"sheet\\\":{\\\"rowSize\\\":3, \\\"columnSize\\\":3}}]}\",\"location\":{\"zoneId\":\"0\",\"index\":0, \"endOfZone\": true}}}"
  ]
}

InsertParagraphElementsRequest

{
    "payload": string,
    "location": {object(InsertLocation)}
}

字段说明 :

字段	类型	说明
payload	string	传入符合文档数据结构的字符串
location	object	插入位置

请求示例

本示例将会在一段文本中插入一段行内代码 Docs API Sample Content

{
  "Revision": 1,
  "Requests": [
      "{\"requestType\":\"InsertParagraphElementsRequestType\",\"insertParagraphElementsRequest\":{\"payload\":\"{\\\"elements\\\":[{\\\"type\\\":\\\"textRun\\\",\\\"textRun\\\":{\\\"text\\\":\\\"Docs API Sample Content\\\",\\\"style\\\":{\\\"codeInline\\\":true}}}],\\\"style\\\":{}}\",\"location\":{\"zoneId\":\"0\",\"index\":653}}}"
  ]
}

InsertTableRowRequest

{
    "tableId": string,
    "rowIndex": int
}

字段说明 :

字段	类型	说明
tableId	string	表格 id, 详见文档数据结构概述 Table 结构体定义
rowIndex	object	插入行索引，从 0 开始，往第一行前插入使用 0

请求示例

本示例将会在一个表格的第一行上方再插入一行

{
      "Revision": 167,
      "Requests": [
      "{\"requestType\":\"InsertTableRowRequestType\",\"insertTableRowRequest\":{\"tableId\":\"rslqdc8170vgu2vsjj2544fwz54ybb3hz7-csc9cbethbmi129ukq31cko24r28wziaa6\", \"rowIndex\": 0}}"
      ]
}

InsertTableColumnRequest

{
    "tableId": string,
    "columnIndex": int
}

字段说明 :

字段	类型	说明
tableId	string	表格id, 详见文档数据结构概述 Table 结构体定义
columnIndex	object	插入列索引，从 0 开始，往第一列前插入使用 0

请求示例

本示例将会在一个表格的第二列左侧再插入一列

{
      "Revision": 178,
      "Requests": [
      "{\"requestType\":\"InsertTableColumnRequestType\",\"insertTableColumnRequest\":{\"tableId\":\"rslqdc8170vgu2vsjj2544fwz54ybb3hz7-csc9cbethbmi129ukq31cko24r28wziaa6\", \"columnIndex\": 1}}"
      ]
}

DeleteTableRowsRequest

删除多行，删除范围 [RowStartIndex,RowEndIndex)

{
    "tableId": string,
    "rowStartIndex": int,
    "rowEndIndex": int
}

字段说明 :

字段	类型	说明
tableId	string	表格id, 详见文档数据结构概述 Table结构体定义
rowStartIndex	int	删除行起始索引，从 0 开始
rowEndIndex	int	删除行结束索引

请求示例

本示例将会删除选定表格的第一行

{
      "Revision": 197,
      "Requests": [
      "{\"requestType\":\"DeleteTableRowsRequestType\",\"deleteTableRowsRequest\":{\"tableId\":\"rslqdc8170vgu2vsjj2544fwz54ybb3hz7-csc9cbethbmi129ukq31cko24r28wziaa6\", \"rowStartIndex\": 0, \"rowEndIndex\": 1}}"
      ]
}

DeleteTableColumnsRequest

删除多列，删除范围 [ColumnStartIndex,ColumnEndIndex)

{
    "tableId": string,
    "columnStartIndex": int,
    "columnEndIndex": int
}

字段说明 :

字段	类型	说明
tableId	string	表格id, 详见文档数据结构概述 Table结构体定义
columnStartIndex	int	删除列起始索引，从 0 开始
columnEndIndex	int	删除列结束索引

请求示例

本示例将会删除选定表格的第二列和第三列

{
      "Revision": 197,
      "Requests": [
      "{\"requestType\":\"DeleteTableColumnsRequestType\",\"deleteTableColumnsRequest\":{\"tableId\":\"rslqdc8170vgu2vsjj2544fwz54ybb3hz7-csc9cbethbmi129ukq31cko24r28wziaa6\", \"columnStartIndex\": 1, \"columnEndIndex\": 3}}"
      ]
}

UpdateTableColumnPropertiesRequest

{
  "tableId": string,
  "columnIndex": int,
  "columnWidth": int
}

字段说明 :

字段	类型	说明
tableId	string	表格id, 详见文档数据结构概述 Table结构体定义
columnIndex	int	列索引，从 0 开始
columnWidth	int	列宽度，单位 px

请求示例

本示例将会把选定表格的第二列列宽调整为 200

{
      "Revision": 212,
      "Requests": [
      "{\"requestType\":\"UpdateTableColumnPropertiesRequestType\",\"updateTableColumnPropertiesRequest\":{\"tableId\":\"rslqdc8170vgu2vsjj2544fwz54ybb3hz7-csc9cbethbmi129ukq31cko24r28wziaa6\", \"columnIndex\": 1, \"columnWidth\": 200}}"
      ]
}

MergeTableCellsRequest

{
  "tableId": string,
  "rowStartIndex": int,
  "rowEndIndex": int,
  "columnStartIndex": int,
  "columnEndIndex": int,
}

字段说明 :

字段	类型	说明
tableId	string	表格 id, 详见文档数据结构概述 Table 结构体定义
rowStartIndex	int	合并行起始索引，从 0 开始
rowEndIndex	int	合并行结束索引
columnStartIndex	int	合并列起始索引，从 0 开始
columnEndIndex	int	合并列结束索引

请求示例

本示例将会合并选定表格左上方的 4 个单元格

{
      "Revision": 237,
      "Requests": [
      "{\"requestType\":\"MergeTableCellsRequestType\",\"mergeTableCellsRequest\":{\"tableId\":\"rslqdc8170vgu2vsjj2544fwz54ybb3hz7-csc9cbethbmi129ukq31cko24r28wziaa6\", \"rowStartIndex\": 0, \"rowEndIndex\": 2,\"columnStartIndex\": 0, \"columnEndIndex\": 2}}"
      ]
}

UnmergeTableCellsRequest

{
  "tableId": string,
  "mergedCellId": string
}

字段说明 :

字段	类型	说明
tableId	string	表格 id, 详见文档数据结构概述 Table结构体定义
mergedCellId	int	合并单元格 id

请求示例

本示例将会拆分表格左上方合并的 4 个单元格

{
      "Revision": 253,
      "Requests": [
      "{\"requestType\":\"UnmergeTableCellsRequestType\",\"unmergeTableCellsRequest\":{\"tableId\":\"rslqdc8170vgu2vsjj2544fwz54ybb3hz7-csc9cbethbmi129ukq31cko24r28wziaa6\", \"mergedCellId\": \"iskfju5o\"}}"
      ]
}

ReplaceAllTextRequest

字段	类型	必须	说明
replaceText	string	是	替换文字，可为空，不可包含换行符、tab，最多1000个字
containsText	SubstringMatchCriteria	是	查找文字

SubstringMatchCriteria

字段	类型	必须	说明
text	string	是	查找内容，不可为空，不可包含换行、tab，最多1000个字
matchCase	bool	否	是否匹配大小写，默认false，忽略大小写

请求示例

本示例将会把文档中的“API”字段替换为“Test”

{
      "Revision": 269,
      "Requests": [
      "{\"requestType\":\"ReplaceAllTextRequestType\",\"replaceAllTextRequest\":{\"containsText\":{\"text\":\"API\",\"matchCase\":false},\"replaceText\": \"Test\"}}"
      ]
}

UpdateParagraphStyleRequest

字段	类型	必须	说明
payload	string	是	详见文档数据结构参考 UpdateParagraphStyleRequest 子命令使用 ParagraphStyle 结构体序列化 string
range	Range	是	修改范围
fields	FieldMask	是	修改字段

FieldMask

字段	类型	必须	说明
masks	[]string	是	修改字段，包括"list"、"headingLevel"、"align"、"quote"

请求示例

本示例将会把文档中 TODO 变为完成状态

{
      "Revision": 312,
      "Requests": ["{\"RequestType\":\"UpdateParagraphStyleRequestType\",\"updateParagraphStyleRequest\":{\"payload\":\"{\\\"list\\\":{\\\"type\\\":\\\"checkedBox\\\",\\\"indentLevel\\\":1}}\",\"range\":{\"zoneID\":\"0\",\"startIndex\":667,\"endIndex\":678},\"fields\":{\"masks\":[\"list\"]}}}"]
}

返回 Body：

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

batch_update 操作帮助

对于 batch_update 操作，需要关注以下注意事项：

请求时，必须带上正确的 revision 版本号，否则可能导致数据错乱。此外，对于一篇协作文档，revision 版本号是有时效性验证的，我们建议每次更新文档时，都使用最新的 revision 版本号，使用一个过旧的 revision 版本号会导致接口报错。
单次请求中，部分元素有个数限制：
- 请求requests size最大10个
- 单个insert操作中person 数最大100
- 单个insert操作中docsLink数最大100
- 单个insert操作中chatGroup数最大5
- 单个insert操作中block数量（含jira，投票、绘图、sheet、bitable）最大50
- 单个insert操作单行图片最多6个
- 单个insert操作图片和附件数量最多50个
- UpdateTitleRequestType最多出现一次
- UpdateParagraphStyleRequest、ReplaceAllTextRequestType、DeleteTableRowsRequestType、DeleteTableColumnsRequestType这几种子命令不可和其他命令共存
插入、删除操作对Index要求
- DeleteContentRangeRequestType子命令
  1. 支持两种操作：（1）删除连续blocks（删除换行符，最后一个block的换行符可选）（2）连续行内元素（不删除换行符）。
  2. block和element删除必须完整
  3. 实际删除区间左闭右开[startIndex, endIndex)
  4. endIndex可以使用文档最后一个换行符位置，但是会保留
  5. 对于删除block，endIndex可以包括最后一个block的换行符（+1）也可以不包含，包含的话会删除改换行符
- InsertBlocksRequestType子命令
  1. 要求只能在新行插入，即插入位置前一个字符为换行符。实际插入位置从Index开始。Index可以等于最后一个换行符（docLengh-1），不可以大于或等于docLengh
- InsertParagraphElementsRequestType子命令
  1. 要求插入位置不可在行内元素中间，可以插入行内某元素之前或者之后。支持空行或者仅有一个行属性的行，实际插入位置从Index开始，Index不可等于最后一个换行符，否则文档末尾只有一个换行符
  2. 若行首存在占位符（style），InsertParagraphElementsRequestType子命令的startIndex不可以等于该占位符（paragraphStyle如果存在行首会有一个占位符）
- 批量操作范围不可重复
  1. 两个DeleteContentRangeRequestType操作 d1和d2，范围不可重复，假设d2.StartIndex>=d1.StartIndex，要求d2.StartIndex>=d1.EndIndex
  2. 一个DeleteContentRangeRequestType d和一个Insert操作i（两种任一）范围不可重复，假设 i.Index >= d.StartIndex，要求i.Index >=d.StartIndex或i.Index == d.StartIndex
- UpdateParagraphStyleRequest子命令
  1. range的startIndex必须等于某个block的startIndex，range的endIndex必须等于某个block的endIndex
权限校验
- docsLink链接如果没有权限，会降级为超链接; 如果文档未命名，降级为超链接
- person如果没有权限（非同租户且非好友），返回错误；如果已离职，返回错误
- 插入chatGroup如果编辑用户不在该群会话中，返回错误
格式化表格和代码块
- 一次batch_update单个table只允许一个表格结构修改操作（增删行列、列属性修改、合并单元格、拆分单元格）
- 增加行列只能单个，删除行列支持范围删除
- 删除行列会清空影响的单元格，删除全部行或列会导致删除整个表格；因此和插入block、插入行内元素、范围删除一起排序后进行，需要保证多个操作范围不冲突
- 单元格内容编辑使用DeleteContentRangeRequestType、InsertBlocksRequestType和InsertParagraphElementsRequestType，只是zoneId使用单元格的zoneId，比如xr1m4jw7egd9nefz1s0mdsetenl5fbe3lygxc1azupv81i5t2rjmosw5ta0esuwtn8ksya
- 表格中不能嵌套table、sheet、bitable
- 相同单元格merge/unmerge操作和单元格编辑操作不可共存
- 相同单元格 delete行列操作和单元格编辑操作不可共存
- 删除表格和编辑单元格内容操作不可共存
- 删除表格和修改表格结构操作不可共存
- 删除code zone和编辑code zone内容操作不可共存