# 更新工作表属性

更新电子表格中的工作表。支持更新工作表的标题、位置，和隐藏、冻结、保护等属性。
该接口和 [操作工作表](https://open.feishu.cn/document/ukTMukTMukTM/uYTMzUjL2EzM14iNxMTN) 的请求地址相同，但参数不同，调用前请仔细阅读文档。

## 请求

基本 |  
---|---
HTTP URL | https://open.feishu.cn/open-apis/sheets/v2/spreadsheets/:spreadsheet_token/sheets_batch_update
HTTP Method | POST
接口频率限制 | [100 次/秒](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App、Store App
权限要求<br>**调用该 API 所需的权限。开启其中任意一项权限即可调用**<br>开启任一权限即可 | 查看、评论、编辑和管理云空间中所有文件(drive:drive)<br>查看、评论、编辑和管理电子表格(sheets:spreadsheet)

### 请求头

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

### 路径参数

名称 | 类型 | 描述
---|---|---
spreadsheet_token | string | 电子表格的 token。可通过以下两种方式获取。了解更多，参考[电子表格概述](https://open.feishu.cn/document/ukTMukTMukTM/uATMzUjLwEzM14CMxMTN/overview)。<br>-  电子表格的 URL：https://sample.feishu.cn/sheets/==Iow7sNNEphp3WbtnbCscPqabcef==<br>- 调用[获取文件夹中的文件清单](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/file/list)

### 查询参数

名称 | 类型 | 必填 | 描述
---|---|---|---
user_id_type | string | 否 | 用户 ID 类型。默认为 `lark_id`，建议选择 `open_id` 或 `union_id`。了解更多，参考[用户身份概述](https://open.feishu.cn/document/home/user-identity-introduction/introduction)。可选值：<br>- `open_id`：标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。了解更多：[如何获取 Open ID](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid)<br>- `union_id`：标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。了解更多：[如何获取 Union ID](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-union-id)

### 请求体 

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

### 请求体示例    
```json
{
  "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 请求示例
```bash
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 | 是否要保护该工作表。可选值：<br>- LOCK：保护<br>- UNLOCK：取消保护
lockInfo | string | 保护工作表的备注信息
userIDs | array<string> | 除了本人与所有者外，其他拥有保护范围编辑权限的人员 ID。ID 类型由查询参数 `user_id_type` 决定。

### 响应体示例   

```json
 {
  "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"
              ]
            }
          }
        }
      }
    ]
  }
}
```
### 错误码

具体可参考：[服务端错误码说明](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN)