查找单元格

在指定范围内查找符合查找条件的单元格。

注意事项

请求参数 range 所指定的范围不可大于实际数据区域，否则将报错。例如，当工作表只有 200 行、而 range 参数的范围为 1 到 201 行时，接口将返回 1310202 错误码。

请求

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

请求头

名称	类型	必填	描述
Authorization	string	是	tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Type	string	是	固定值："application/json; charset=utf-8"

路径参数

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

请求体

名称	类型	必填	描述
find_condition	find_condition	是	指定查找单元格的条件。
└ range	string	是	查找范围。格式为 !<开始位置>:<结束位置>。其中： - sheetId 为工作表 ID，通过获取工作表 获取 - <开始位置>:<结束位置> 为工作表中单元格的范围，数字表示行索引，字母表示列索引。如 A2:B2 表示该工作表第 2 行的 A 列到 B 列。range支持四种写法，详情参考电子表格概述 示例值："PNIfrm!A1:C5"
└ match_case	boolean	否	是否忽略查找字符串的大小写，默认为 false。 - true：忽略字符串中字母大小写差异 - false：区分字符串中字母大小写 示例值：true
└ match_entire_cell	boolean	否	字符串是否需要完全匹配整个单元格，默认值为 false。 - true：完全匹配单元格，比如 find 参数 取值为 "hello"，则单元格中的内容必须为 "hello" 才会匹配替换 - false：允许部分匹配单元格，比如 find 取值为 "hello"，则单元格中的内容包含 "hello" 即可匹配替换 示例值：false
└ search_by_regex	boolean	否	是否使用正则表达式查找，默认值为 false。 - true：使用正则表达式 - false：不使用正则表达式 示例值：false
└ include_formulas	boolean	否	是否仅搜索单元格公式，默认值为 false。 - true：仅搜索单元格公式 - false：仅搜索单元格内容 示例值：false
find	string	是	查找的字符串。当search_by_regex 字段为 true 时，你需填入正则表达式 示例值："如下所示： - 字符串查找示例： "hello" - 正则表达式查找示例："[A-Z]\w+"

请求体示例

{
    "find_condition": {
        "range": "PNIfrm!A1:C5",
        "match_case": true,
        "match_entire_cell": false,
        "search_by_regex": false,
        "include_formulas": false
    },
    "find": "hello"
}

请求示例

curl --location --request POST 'https://open.feishu.cn/open-apis/sheets/v3/spreadsheets/shtcnmBA*****yGehy8/sheets/PNIfrm/find' \
--header 'Authorization: Bearer u-3iqkd6KWzRLzNeXfeuCMEb' \
--header 'Content-Type: application/json' \
--data-raw '{
    "find_condition": {
        "range": "PNIfrm!A1:C5",
        "match_case": true,
        "match_entire_cell": false,
        "search_by_regex": false,
        "include_formulas": false
    },
    "find": "hello"
}'

响应

响应体

名称	类型	描述
code	int	错误码，非 0 表示失败
msg	string	错误描述
data	\-	-
└ find_result	find_replace_result	符合条件的信息
└ matched_cells	string\[\]	符合查找条件的单元格数组，不包含公式
└ matched_formula_cells	string\[\]	符合查找条件的含有公式的单元格数组
└ rows_count	int	符合查找条件的总行数

响应体示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "find_result": {
            "matched_cells": [
                "A1"
            ],
            "matched_formula_cells": [
                "B3"
            ],
            "rows_count": 2
        }
    }
}

错误码

HTTP状态码	错误码	描述	排查建议
400	1310242	In Mix state	当前表格数据位于用户机房，正在将数据恢复到 SaaS 环境中，请稍后重试
400	1310211	Wrong Sheet Id	检查工作表的 ID 是否正确。获取方式见获取工作表
400	1310248	Wrong Regular Expression	检查正则表达式是否正确
400	1310202	Wrong Range	区域范围错误
400	1310229	Wrong URL Param	检查 URL 参数
400	1310204	Wrong Request Body	参考响应体中的错误提示检查请求体参数
400	1310213	Permission Fail	没有文档相应权限。参考云文档常见问题问题 2 和问题 3 开通应用权限和文档权限
400	1310218	Locked Cell	检查操作的是否为保护范围
400	1310214	SpreadSheet Not Found	检查表格 token 是否正确。可通过以下两种方式获取。了解更多，参考电子表格概述。 - 电子表格的 URL：https://sample.feishu.cn/sheets/==Iow7sNNEphp3WbtnbCscPqabcef== - 调用获取文件夹中的文件清单
400	1310215	Sheet Id Not Found	检查工作表的 ID 是否正确。获取方式见获取工作表
400	1310226	Excess Limit	超出限制，参考响应体中的错误提示
400	1310217	Too Many Request	检查请求是否发送过于频繁
400	1310235	Retry Later	稍后重试
500	1315201	Server Error	服务内部错误，详询客服
500	1315203	Server Error	服务内部错误，详询客服
400	1310249	Spreadsheet Deleted	表格已被删除，请恢复表格后重试