更新工作表属性

更新电子表格中的工作表。支持更新工作表的标题、位置，和隐藏、冻结、保护等属性。

Note 该接口和 操作工作表 的请求地址相同，但参数不同，调用前请仔细阅读文档。

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/sheets/v2/spreadsheets/:spreadsheet_token/sheets_batch_update
HTTP Method	POST
接口频率限制	100 次/秒
支持的应用类型	custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可	drive:drive 查看、评论、编辑和管理云空间中所有文件 sheets:spreadsheet 查看、评论、编辑和管理电子表格

请求头

名称	类型	必填	描述
Authorization	string	是	通过访问凭证（access_token）对调用者身份进行鉴权。可选值： - tenant_access_token： 租户授权凭证。应用代表租户（即企业或团队）执行对应操作。示例值："Bearer t-7f1bcd13fc57d46bac21793aabcef" - user_access_token：用户授权凭证。应用代表用户执行对应操作。示例值："Bearer u-7f1bcd13fc57d46bac21793aabcef" 了解更多，参考获取访问凭证。
Content-Type	string	是	固定值："application/json; charset=utf-8"

路径参数

名称	类型	描述
spreadsheet_token	string	电子表格的 token。可通过以下两种方式获取。了解更多，参考电子表格概述。 - 电子表格的 URL：https://sample.feishu.cn/sheets/==Iow7sNNEphp3WbtnbCscPqabcef== - 调用获取文件夹中的文件清单

查询参数

名称	类型	必填	描述
user_id_type	string	否	用户 ID 类型。默认为 lark_id，建议选择 open_id 或 union_id。了解更多，参考用户身份概述。可选值： - open_id：标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。了解更多：如何获取 Open ID - union_id：标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。了解更多：如何获取 Union ID

请求体

名称	类型	必填	描述
requests	/	是	更新工作表属性的请求。一次请求可以进行多次更新操作。
└ updateSheet	/	否	更新工作表。
└ properties	/	是	工作表属性
└ sheetId	string	是	要更新的工作表的 ID。调用获取工作表获取 ID。
└ title	string	否	工作表的标题。更新的标题需符合以下规则： - 长度不超过 100 个字符 - 不包含这些特殊字符：/ \ ? * [ ] :
└ index	int	否	工作表的位置。从 0 开始计数。
└ hidden	bool	否	是否要隐藏表格。默认值为 false。
└ frozenRowCount	int	否	要冻结至指定行的行索引。若填 3，表示从第一行冻结至第三行。小于或等于工作表的最大行数，0 表示取消冻结行。
└ frozenColCount	int	否	要冻结至指定列的列索引。若填 3，表示从第一列冻结至第三列。小于等于工作表的最大列数，0 表示取消冻结列。
└ protect	/	否	是否要保护该工作表。
└ lock	string	是	是否要保护该工作表。可选值： - LOCK：保护 - UNLOCK：取消保护
└ lockInfo	string	否	保护工作表的备注信息
└ userIDs	array	否	添加除操作用户与所有者外其他用户的 ID，为其开通保护范围的编辑权限。ID 类型由查询参数 user_id_type 决定。user_id_type 不为空时，该字段生效。

请求体示例

{
  "requests": [
    {
      "updateSheet": {
        "properties": {
          "sheetId": "1SW8ik",
          "title": "Sales sheet",
          "index": 3,
          "hidden": true,
          "frozenColCount": 8,
          "frozenRowCount": 2,
          "protect": {
            "lock": "LOCK",
            "lockInfo": "privacy info",
            "userIDs": [
              "ou_48d0958ee4b2ab3eaf0b5f6c968abcef"
            ]
          }
        }
      }
    }
  ]
}

cURL 请求示例

curl --location --request POST 'https://open.feishu.cn/open-apis/sheets/v2/spreadsheets/shtcngNygNfuqhxTBf588jwgWbJ/sheets_batch_update?user_id_type=open_id' \
--header 'Authorization: Bearer t-e346617a4acfc3a11d4ed24dca0d0c0fc8e0067e' \
--header 'Content-Type: application/json' \
--data-raw '{
  "requests": [
    {
      "updateSheet": {
        "properties": {
          "sheetId": "zajIJ",
          "title": "Sales sheet",
          "index": 3,
          "hidden": true,
          "frozenColCount": 8,
          "frozenRowCount": 2,
          "protect": {
            "lock": "LOCK",
            "lockInfo": "privacy info"
            "userIDs": [
               "ou_48d0958ee4b2ab3eaf0b5f6c968abcef"
            ]
          }
        }
      }
    }
  ]
}'

响应

响应体

名称	类型	描述
replies	/	本次操作工作表的结果
└ updateSheet	/	更新工作表的结果
└ properties	/	工作表属性
└ sheetId	string	更新的工作表的 ID
└ title	string	更新的工作表的标题
└ index	int	移动的工作表的位置
└ hidden	bool	是否隐藏表格
└ frozen RowCount	int	冻结至指定行的行索引
└ frozen ColCount	int	冻结至指定列的列索引
└ protect	/	保护工作表的属性
└ lock	string	是否要保护该工作表。可选值： - LOCK：保护 - UNLOCK：取消保护
└ lockInfo	string	保护工作表的备注信息
└ userIDs	array	除了本人与所有者外，其他拥有保护范围编辑权限的人员 ID。ID 类型由查询参数 user_id_type 决定。

响应体示例

 {
  "code": 0,
  "msg": "Success",
  "data": {
    "replies": [
      {
        "updateSheet": {
          "properties": {
            "sheetId": "1SW8ik",
            "title": "Sales sheet",
            "index": 3,
            "hidden": true,
            "frozenColCount": 2,
            "frozenRowCount": 8,
            "protect": {
              "lock": "LOCK",
              "lockInfo": "privacy info",
              "userIDs": [
                "ou_48d0958ee4b2ab3eaf0b5f6c968abcef"
              ]
            }
          }
        }
      }
    ]
  }
}

错误码

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