读取多个范围
读取电子表格中多个指定范围的数据。
使用限制
- 该接口返回数据的最大限制为 10 MB。
- 该接口不支持获取跨表引用和数组公式的计算结果。
前提条件
调用此接口前，请确保当前调用身份（tenant_access_token 或 user_access_token）已有电子表格的阅读、编辑等文档权限，否则接口将返回 HTTP 403 或 400 状态码。了解更多，参考如何为应用或用户开通文档权限。
请求
| 项目 | 值 |
|---|---|
| HTTP URL | https://open.feishu.cn/open-apis/sheets/v2/spreadsheets/:spreadsheetToken/values_batch_get |
| HTTP Method | GET |
| 接口频率限制 | 100 次/秒 |
| 支持的应用类型 | custom,isv |
| 权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可 | drive:drive 查看、评论、编辑和管理云空间中所有文件 drive:drive:readonly 查看、评论和下载云空间中所有文件 sheets:spreadsheet 查看、评论、编辑和管理电子表格 sheets:spreadsheet:readonly 查看、评论和导出电子表格 |
请求头
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| Authorization | string | 是 | 通过访问凭证（access_token）对调用者身份进行鉴权。可选值： - tenant_access_token： 租户授权凭证。应用代表租户（即企业或团队）执行对应操作。示例值："Bearer t-7f1bcd13fc57d46bac21793aabcef" - user_access_token：用户授权凭证。应用代表用户执行对应操作。示例值："Bearer u-7f1bcd13fc57d46bac21793aabcef" 了解更多，参考获取访问凭证。 |
| Content-Type | string | 是 | 固定值："application/json; charset=utf-8" |
路径参数
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| spreadsheetToken | string | 是 | 电子表格的 token。可通过以下两种方式获取。了解更多，参考电子表格概述。 - 电子表格的 URL：https://sample.feishu.cn/sheets/==Iow7sNNEphp3WbtnbCscPqabcef== - 调用获取文件夹中的文件清单 示例值："Iow7sNNEphp3WbtnbCscPqabcef" |
查询参数
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| ranges | string | 是 | 多个查询范围，范围之间使用逗号分隔，如 Q7PlXT!A2:B6,0b6377!B1:C8。range 的格式为 !<开始位置>:<结束位置>。其中： - sheetId 为工作表 ID，通过获取工作表 获取 - <开始位置>:<结束位置> 为工作表中单元格的范围，数字表示行索引，字母表示列索引。如 A2:B2 表示该工作表第 2 行的 A 列到 B 列。range支持四种写法，详情参考电子表格概述 注意：若使用 !<开始单元格>:<结束列> 的写法时，仅支持获取 100 列数据。 |
| valueRenderOption | string | 否 | 指定单元格数据的格式。可选值如下所示。当参数缺省时，默认不进行公式计算，返回公式本身，且单元格为数值格式。 - ToString：返回纯文本的值（数值类型除外） - Formula：单元格中含有公式时，返回公式本身 - FormattedValue：计算并格式化单元格 - UnformattedValue：计算但不对单元格进行格式化 |
| dateTimeRenderOption | string | 否 | 指定数据类型为日期、时间、或时间日期的单元格数据的格式。 - 若不传值，默认返回浮点数值，整数部分为自 1899 年 12 月 30 日以来的天数；小数部分为该时间占 24 小时的份额。例如：若时间为 1900 年 1 月 1 日中午 12 点，则默认返回 2.5。其中，2 表示 1900 年 1 月 1 日为 1899 年12 月 30 日之后的 2 天；0.5 表示 12 点占 24 小时的二分之一，即 12/24=0.5。 - 可选值为 FormattedString，此时接口将计算并对日期、时间、或时间日期类型的数据格式化并返回格式化后的字符串，但不会对数字进行格式化。 |
| 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 |
cURL 请求示例
bash
curl --location --request GET 'https://open.feishu.cn/open-apis/sheets/v2/spreadsheets/shtcngNygNfuqhxTBf588jabcef/values_batch_get?ranges=Q7PlXT!A2:B6,0b6377!B1:C8&valueRenderOption=ToString&dateTimeRenderOption=FormattedString' \
--header 'Authorization: Bearer t-e346617a4acfc3a11d4ed24dca0d0c0fc8e0067e' \响应
响应体
| 名称 | 类型 | 描述 |
|---|---|---|
code | int | 错误码，非 0 表示失败 |
msg | string | 错误描述 |
data | - | - |
└ revision | int | 工作表的版本号。从 0 开始计数，更新一次版本号加一。 |
└ spreadsheetToken | string | 表格的 token |
└ totalCells | int | 读取的单元格总数 |
└ valueRanges | - | 读取的值与范围 |
└ majorDimension | string | 返回的 values 数组中数据的呈现维度。固定取值 ROWS，即数据为从左到右、从上到下的读取顺序。 |
└ range | string | 读取的范围。为空时表示查询范围没有数据。 |
└ revision | int | 工作表的版本号。从 0 开始计数，更新一次版本号加一。 |
└ values | array> | 指定范围中的数据 |
响应体示例
json
{
"code": 0,
"data": {
"revision": 87,
"spreadsheetToken": "shtcngNygNfuqhxTBf588jabcef",
"totalCells": 6,
"valueRanges": [
{
"majorDimension": "ROWS",
"range": "6e5ed3!A2:B3",
"revision": 87,
"values": [
[
"World",
1
],
[
5,
6
]
]
},
{
"majorDimension": "ROWS",
"range": "4FRjKE!B1:B2",
"revision": 87,
"values": [
[
"test"
],
[
"test"
]
]
}
]
},
"msg": "success"
}错误码
具体可参考：服务端错误码说明