# 读取单个范围

读取电子表格中单个指定范围的数据。

## 使用限制

- 该接口返回数据的最大限制为 10 MB。
- 该接口不支持获取跨表引用和数组公式的计算结果。

## 前提条件

调用此接口前，请确保当前调用身份（tenant_access_token 或 user_access_token）已有电子表格的阅读、编辑等文档权限，否则接口将返回 HTTP 403 或 400 状态码。了解更多，参考[如何为应用或用户开通文档权限](https://open.feishu.cn/document/ukTMukTMukTM/uczNzUjL3czM14yN3MTN#16c6475a)。

## 请求

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

### 请求头

名称 | 类型 | 必填 | 描述
---|---|---|---
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"

### 路径参数

名称 | 类型 | 必填 | 描述
---|---|---|---
spreadsheetToken | 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)<br>**示例值**："Iow7sNNEphp3WbtnbCscPqabcef"
range | string | 是 | 查询范围。格式为 `<sheetId>!<开始位置>:<结束位置>`。其中：<br>- `sheetId` 为工作表 ID，通过[获取工作表](https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/sheets-v3/spreadsheet-sheet/query) 获取<br>- `<开始位置>:<结束位置>` 为工作表中单元格的范围，数字表示行索引，字母表示列索引。如 `A2:B2` 表示该工作表第 2 行的 A 列到 B 列。`range`支持四种写法，详情参考[电子表格概述](https://open.feishu.cn/document/ukTMukTMukTM/uATMzUjLwEzM14CMxMTN/overview)<br>**注意**：若使用 `<sheetId>!<开始单元格>:<结束列>` 和 `<sheetId>!<开始列>:<结束列>` 的写法时，仅支持获取 100 列数据。<br>**示例值**："Q7PlXT!A1:B2"

### 查询参数 

名称 | 类型 | 必填 | 描述
---|---|---|---
valueRenderOption | string | 否 | 指定单元格数据的格式。可选值如下所示。当参数缺省时，默认不进行公式计算，返回公式本身，且单元格为数值格式。<br>- ToString：返回纯文本的值（数值类型除外）<br>- Formula：单元格中含有公式时，返回公式本身<br>- FormattedValue：计算并格式化单元格<br>- UnformattedValue：计算但不对单元格进行格式化
dateTimeRenderOption | string | 否 | 指定数据类型为日期、时间、或时间日期的单元格数据的格式。<br>- 若不传值，默认返回浮点数值，整数部分为自 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。<br>- 可选值为 FormattedString，此时接口将计算并对日期、时间、或时间日期类型的数据格式化并返回格式化后的字符串，但不会对数字进行格式化。
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)

###  cURL 请求示例
```bash
curl --location --request GET 'https://open.feishu.cn/open-apis/sheets/v2/spreadsheets/XUMasQlMYhOnMbt5htXc96h0nOg/values/Q7PlXT!A1:B2?valueRenderOption=ToString&dateTimeRenderOption=FormattedString' \
--header 'Authorization: Bearer t-ce3540c5f02ac074535f1f14d64fa90fa49621c0'
```
## 响应
### 响应体

名称 | 类型 | 描述
---|---|---
code | int | 错误码，非 0 表示失败
msg | string | 错误描述
data | - | -
revision | int | 工作表的版本号。从 0 开始计数，更新一次版本号加一。
spreadsheetToken | string | 表格的 token
valueRange | - | 读取的值与范围
majorDimension | string | 返回的 values 数组中数据的呈现维度。固定取值 ROWS，即数据为从左到右、从上到下的读取顺序。
range | <md-text type="field-type">string | 读取的范围。为空时表示查询范围没有数据。
<md-text type="field-name">revision | <md-text type="field-type">int | 工作表的版本号。从 0 开始计数，更新一次版本号加一。
<md-text type="field-name">values | <md-text type="field-type">array<array<Object>> | 指定范围中的数据

### 响应体示例  
```json
{
    "code": 0,
    "data": {
        "revision": 7,
        "spreadsheetToken": "XUMasQlMYhOnMbt5htXc96h0nOg",
        "valueRange": {
            "majorDimension": "ROWS",
            "range": "Q7PlXT!A1:B2",
            "revision": 7,
            "values": [
                [
                    "单元格A1",
                    "单元格B1"
                ],
                [
                    "单元格A2",
                    "单元格B2"
                ]
            ]
        }
    },
    "msg": "success"
}
```
### 错误码

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