金山文档开放平台主题
遍历记录(复杂查询条件)
遍历数据表内的记录（复杂查询条件）
基本信息
请求方法：POST
请求路径：/api/v1/openapi/dbt/:file_token/sheets/:sheet_id/records/complex_query
请求主机：developer.kdocs.cn
限流频次
| 应用类型 | 限额 |
|---|---|
测试应用 | 10,000 次/天 |
正式应用 | 10,000,000 次/天 |
权限范围
要调用此 API，需要以下权限
| 权限值 | 显示名称 | 权限说明 |
|---|---|---|
edit_personal_files | 编辑文档内容 | 编辑文档内容 |
Path 参数
| 参数 | 位置 | 必须 | 类型 | 说明 |
|---|---|---|---|---|
file_token | path | 是 | string | 文档 ID |
sheet_id | path | 是 | integer | Sheet ID |
Query 参数
| 参数 | 必须 | 类型 | 说明 |
|---|---|---|---|
access_token | 是 | string |
Body 参数
| 参数 | 必须 | 类型 | 说明 |
|---|---|---|---|
preferId | 否 | boolean | 使用 id 来标识字段和选项。为 true 时，fields 参数也按照 id 做解析 |
pageSize | 否 | integer | 用于分页获取记录，避免记录过多时一次性返回大量内容。缺省值为 100 |
viewId | 否 | string | 填写后将从被指定的视图获取该用户所见到的记录；若不填写，则从工作表获取记录 |
maxRecords | 否 | integer | 指定要获取的“前 maxRecords 条记录”，若不填写，则默认返回全部记录 |
fields | 否 | string[] | 指定所返回记录中的字段信息，若不填写，则默认返回全部字段内的信息。依据 preferId 的值，需要输入字段名或字段 id |
offset | 否 | string | 存在分页时，指定本次查询的起始记录。若不填写或填写为空字符串，则从第一条记录开始获取。查询到最后一页或第 maxRecords 条记录时，返回数据将不再包含 offset 值 |
filter | 否 | filter {} | 筛选条件，用来对行记录进行筛选，由两部分构成：mode 为筛选条件关系；creteria 为具体筛选条件（fileds op values） |
pageNum | 否 | integer | 页码, 与offset互斥，如果 offset 和 pageNum 同时出现时，优先处理 pageNum 忽略 offset。与pageSize共同决定所查询的记录范围。当pageNum*pageSize超出最大记录数时，将返回空的结果。 例如: pageNum=3,pageSize=100, 即将总记录数分为每页为100条的记录范围, 3表示查询这个记录范围的第3页(第301条-第400条) |
筛选规则
| 筛选条件 | 参数说明 |
|---|---|
Equals | 等于 |
NotEqu | 不等于 |
Greater | 大于 |
GreaterEqu | 大等于 |
Less | 小于 |
LessEqu | 小等于 |
GreaterEquAndLessEqu | 介于（取等） |
LessOrGreater | 介于（不取等） |
BeginWith | 开头是 |
EndWith | 结尾是 |
Contains | 包含 |
NotContains | 不包含 |
Intersected | 指定值 |
Empty | 为空 |
NotEmpty | 不为空 |
各筛选规则独立地限制了 values 数组内最多允许填写的元素数，当 values 内元素数超过阈值时，该筛选规则将失效。
为空、不为空不允许填写元素；介于允许最多填写 2 个元素；指定值允许填写 65535 个元素；其他规则允许最多填写 1 个元素。
注意
filter 不是结构体，当 criteria 未指定 field、op、values 参数填写不合法、values 填写过多参数及其他可能导致筛选规则失效等情形，整个请求将直接失败。
注意
filters 属性和 criteria 属性是互斥的，只能出现一个，否则会导致查询失败。
目前还支持对日期进行动态筛选，此时 values[]内的元素需以结构体的形式给出：
{
"mode": "AND",
"criteria": [
{
"field": "日期",
"op": "Equals",
"values": [
{
"dynamicType": "lastMonth",
"type": "DynamicSimple"
}
]
}
]
}
提示
上述示例对应的筛选条件为等于上一个月。
要使用日期动态筛选，values[]内的结构体需要指定 type: DynamicSimple，当op为Equals时，dynamicType可以为如下的值（大小写不敏感）。
| 字段 | 说明 |
|---|---|
today | 今天 |
yesterday | 昨天 |
tomorrow | 明天 |
last7Days | 最近 7 天 |
last30Days | 最近 30 天 |
thisWeek | 本周 |
lastWeek | 上周 |
nextWeek | 下周 |
thisMonth | 本月 |
lastMonth | 上月 |
nextMonth | 次月 |
提示
当op为greater或less时，dynamicType只能是昨天、今天或明天。
复杂查询条件示例（filters）
注意
当使用了 filters 参数后，就不能使用同级中的 criteria 参数了，这两个参数是互斥的。
{
"filter": {
"mode": "OR",
"filters": [
{
"mode": "AND",
"criteria": [
{
"field": "名称",
"op": "Equals",
"values": ["a"]
},
{
"field": "数量",
"op": "Equals",
"values": ["1"]
}
]
},
{
"mode": "AND",
"criteria": [
{
"field": "名称",
"op": "Equals",
"values": ["b"]
},
{
"field": "数量",
"op": "Equals",
"values": ["2"]
}
]
}
]
}
}
返回参数
| 参数 | 类型 | 说明 |
|---|---|---|
code | integer | 错误码 |
data | data {} | 响应数据 |
示例
请求示例
curl --request POST \
--url 'https://developer.kdocs.cn/api/v1/openapi/dbt/wfoKKYzWR2jyxMHCFVuBxa42RSf8tpndOUeHQQzryfI/sheets/583/records/complex_query?access_token=kvqxrspxjctdojjqdildjhonzwusaquc1' \
--header 'Content-Type: application/json' \
--data '{"preferId":false,"pageSize\t":10,"viewId":"Tx","maxRecords":10,"fields":["字段名1","修改字段名"],"filter":{"mode":"AND","criteria":[{"field":"字段名1","op":"equals","values":["item2"]},{"field":"修改字段名","op":"empty","values":[]}]}}'
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"preferId\":false,\"pageSize\\t\":10,\"viewId\":\"Tx\",\"maxRecords\":10,\"fields\":[\"字段名1\",\"修改字段名\"],\"filter\":{\"mode\":\"AND\",\"criteria\":[{\"field\":\"字段名1\",\"op\":\"equals\",\"values\":[\"item2\"]},{\"field\":\"修改字段名\",\"op\":\"empty\",\"values\":[]}]}}");
Request request = new Request.Builder()
.url("https://developer.kdocs.cn/api/v1/openapi/dbt/wfoKKYzWR2jyxMHCFVuBxa42RSf8tpndOUeHQQzryfI/sheets/583/records/complex_query?access_token=kvqxrspxjctdojjqdildjhonzwusaquc1")
.post(body)
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
package main
import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)
func main() {
url := "https://developer.kdocs.cn/api/v1/openapi/dbt/wfoKKYzWR2jyxMHCFVuBxa42RSf8tpndOUeHQQzryfI/sheets/583/records/complex_query?access_token=kvqxrspxjctdojjqdildjhonzwusaquc1"
payload := strings.NewReader("{\"preferId\":false,\"pageSize\\t\":10,\"viewId\":\"Tx\",\"maxRecords\":10,\"fields\":[\"字段名1\",\"修改字段名\"],\"filter\":{\"mode\":\"AND\",\"criteria\":[{\"field\":\"字段名1\",\"op\":\"equals\",\"values\":[\"item2\"]},{\"field\":\"修改字段名\",\"op\":\"empty\",\"values\":[]}]}}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
import http.client
conn = http.client.HTTPSConnection("developer.kdocs.cn")
payload = "{\"preferId\":false,\"pageSize\\t\":10,\"viewId\":\"Tx\",\"maxRecords\":10,\"fields\":[\"字段名1\",\"修改字段名\"],\"filter\":{\"mode\":\"AND\",\"criteria\":[{\"field\":\"字段名1\",\"op\":\"equals\",\"values\":[\"item2\"]},{\"field\":\"修改字段名\",\"op\":\"empty\",\"values\":[]}]}}"
headers = { 'Content-Type': "application/json" }
conn.request("POST", "/api/v1/openapi/dbt/wfoKKYzWR2jyxMHCFVuBxa42RSf8tpndOUeHQQzryfI/sheets/583/records/complex_query?access_token=kvqxrspxjctdojjqdildjhonzwusaquc1", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://developer.kdocs.cn/api/v1/openapi/dbt/wfoKKYzWR2jyxMHCFVuBxa42RSf8tpndOUeHQQzryfI/sheets/583/records/complex_query?access_token=kvqxrspxjctdojjqdildjhonzwusaquc1",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "{\"preferId\":false,\"pageSize\\t\":10,\"viewId\":\"Tx\",\"maxRecords\":10,\"fields\":[\"字段名1\",\"修改字段名\"],\"filter\":{\"mode\":\"AND\",\"criteria\":[{\"field\":\"字段名1\",\"op\":\"equals\",\"values\":[\"item2\"]},{\"field\":\"修改字段名\",\"op\":\"empty\",\"values\":[]}]}}",
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
const data = JSON.stringify({
"preferId": false,
"pageSize\t": 10,
"viewId": "Tx",
"maxRecords": 10,
"fields": [
"字段名1",
"修改字段名"
],
"filter": {
"mode": "AND",
"criteria": [
{
"field": "字段名1",
"op": "equals",
"values": [
"item2"
]
},
{
"field": "修改字段名",
"op": "empty",
"values": []
}
]
}
});
const xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://developer.kdocs.cn/api/v1/openapi/dbt/wfoKKYzWR2jyxMHCFVuBxa42RSf8tpndOUeHQQzryfI/sheets/583/records/complex_query?access_token=kvqxrspxjctdojjqdildjhonzwusaquc1");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.send(data);
const http = require("https");
const options = {
"method": "POST",
"hostname": "developer.kdocs.cn",
"port": null,
"path": "/api/v1/openapi/dbt/wfoKKYzWR2jyxMHCFVuBxa42RSf8tpndOUeHQQzryfI/sheets/583/records/complex_query?access_token=kvqxrspxjctdojjqdildjhonzwusaquc1",
"headers": {
"Content-Type": "application/json"
}
};
const req = http.request(options, function (res) {
const chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
const body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({
preferId: false,
'pageSize ': 10,
viewId: 'Tx',
maxRecords: 10,
fields: ['字段名1', '修改字段名'],
filter: {
mode: 'AND',
criteria: [
{field: '字段名1', op: 'equals', values: ['item2']},
{field: '修改字段名', op: 'empty', values: []}
]
}
}));
req.end();
CURL *hnd = curl_easy_init();
curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://developer.kdocs.cn/api/v1/openapi/dbt/wfoKKYzWR2jyxMHCFVuBxa42RSf8tpndOUeHQQzryfI/sheets/583/records/complex_query?access_token=kvqxrspxjctdojjqdildjhonzwusaquc1");
struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);
curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "{\"preferId\":false,\"pageSize\\t\":10,\"viewId\":\"Tx\",\"maxRecords\":10,\"fields\":[\"字段名1\",\"修改字段名\"],\"filter\":{\"mode\":\"AND\",\"criteria\":[{\"field\":\"字段名1\",\"op\":\"equals\",\"values\":[\"item2\"]},{\"field\":\"修改字段名\",\"op\":\"empty\",\"values\":[]}]}}");
CURLcode ret = curl_easy_perform(hnd);
var client = new RestClient("https://developer.kdocs.cn/api/v1/openapi/dbt/wfoKKYzWR2jyxMHCFVuBxa42RSf8tpndOUeHQQzryfI/sheets/583/records/complex_query?access_token=kvqxrspxjctdojjqdildjhonzwusaquc1");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\"preferId\":false,\"pageSize\\t\":10,\"viewId\":\"Tx\",\"maxRecords\":10,\"fields\":[\"字段名1\",\"修改字段名\"],\"filter\":{\"mode\":\"AND\",\"criteria\":[{\"field\":\"字段名1\",\"op\":\"equals\",\"values\":[\"item2\"]},{\"field\":\"修改字段名\",\"op\":\"empty\",\"values\":[]}]}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
返回示例
{
"code": 0,
"data": {
"detail": {
"records": [
{ "fields": { "字段名1": "item2" }, "id": "PP" },
{ "fields": { "字段名1": "item2" }, "id": "PQ" }
]
},
"result": "ok"
}
}
错误码
请参考错误码说明