编辑文档内容

在使用此接口前，请仔细阅读文档概述和准备接入文档 API了解文档调用的规则和约束，确保你的文档数据不会丢失或出错。
文档数据结构定义可参考：文档数据结构概述

此接口只支持编辑旧版文档内容，如果需要编辑新版文档的内容，请调用新版文档相关接口：

• 创建块
• 更新块
• 批量更新块
• 删除块

该接口用于批量编辑更新文档内容，包括更新标题、范围删除、插入内容。

请求体

参数	类型	必须	说明
docToken	string	是	文件的 token，获取方式见如何获取云文档资源相关 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

支持返回段落文本中的lineId

{
    "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	string	合并单元格 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 操作，需要关注以下注意事项：

1. 请求时，必须带上正确的 revision 版本号，否则可能导致数据错乱。此外，对于一篇协作文档，revision 版本号是有时效性验证的，我们建议每次更新文档时，都使用最新的 revision 版本号，使用一个过旧的 revision 版本号会导致接口报错。
2. 单次请求中，部分元素有个数限制：
   • 请求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这几种子命令不可和其他命令共存
3. 插入、删除操作对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
4. 权限校验
   • docsLink链接如果没有权限，会降级为超链接; 如果文档未命名，降级为超链接
   • person如果没有权限（非同租户且非好友），返回错误；如果已离职，返回错误
   • 插入chatGroup如果编辑用户不在该群会话中，返回错误
5. 格式化表格和代码块
   • 一次batch_update单个table只允许一个表格结构修改操作（增删行列、列属性修改、合并单元格、拆分单元格）
   • 增加行列只能单个，删除行列支持范围删除
   • 删除行列会清空影响的单元格，删除全部行或列会导致删除整个表格；因此和插入block、插入行内元素、范围删除一起排序后进行，需要保证多个操作范围不冲突
   • 单元格内容编辑使用DeleteContentRangeRequestType、InsertBlocksRequestType和InsertParagraphElementsRequestType，只是zoneId使用单元格的zoneId，比如xr1m4jw7egd9nefz1s0mdsetenl5fbe3lygxc1azupv81i5t2rjmosw5ta0esuwtn8ksya
   • 表格中不能嵌套table、sheet、bitable
   • 相同单元格merge/unmerge操作和单元格编辑操作不可共存
   • 相同单元格 delete行列操作和单元格编辑操作不可共存
   • 删除表格和编辑单元格内容操作不可共存
   • 删除表格和修改表格结构操作不可共存
   • 删除code zone和编辑code zone内容操作不可共存

错误码

错误码	说明	排查建议
91401	PARAMERR	参数出现错误，检查参数有效性
91402	NOTEXIST	未找到，检查token是否有效
91403	FORBIDDEN	没有权限，检查是否有文档读权限
91404	LOGIN_REQUIRED	需要登录
95001	internal error	内部错误，请稍后重试
95003	internal error	内部错误，请稍后重试
95005	internal error	内部错误，请稍后重试
95006	Failed	文档未找到，检查token是否有效
95007	Failed	文档已删除，已删除文件无法获取文档meta信息
95008	FORBIDDEN	检查用户对文档、文件夹的权限
95009	Failed	没有权限，检查是否有文档读权限。添加文档权限
95010	internal error	内部错误，请稍后重试
95011	internal error	内部错误，请稍后重试
95017	具体错误信息	读取文档内容失败，检查revison是否正确
95018	具体错误信息	解析文档内容失败，详见具体错误信息
95020	具体错误信息	批量更新文档操作失败，详见具体错误信息
95023	revision too old	版本号太老，请使用最新版本号
95024	Failed	参数无效，检查参数有效性
95025	Failed	解析请求失败，检查请求是否合法json
95026	Failed	无效的batch_update 操作类型，检查batch_update接口request_type
95050	具体错误信息	保存文档内容失败，详见具体错误信息
95053	this API does not support the Upgraded Docs(docx), please refer to the https://bytedance.feishu.cn/docx/doxcna26SMxtcPDYMJGqfpNgRng using the correct API.	此 API 不支持新版文档（docx），请参考新版文档 OpenAPI 接入指引使用正确的 API。

具体可参考：服务端错误码说明