金山文档开放平台

主题

回到顶部
本页内容

遍历记录(复杂查询条件)

遍历数据表内的记录（复杂查询条件）

基本信息

请求方法：POST

请求路径：/api/v1/openapi/ksheet/:file_token/sheets/:sheet_id/records/complex_query

请求主机：developer.kdocs.cn

限流频次

应用类型限额
测试应用
10,000 次/天
正式应用
10,000,000 次/天

权限

要调用此 API，需要以下权限

权限值显示名称权限说明
edit_personal_files
编辑文档内容
编辑文档内容

Path 参数

参数必须类型说明
file_token
是
string
文档 ID
sheet_id
是
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
否
object
筛选条件，用来对行记录进行筛选，由两部分构成：mode 为筛选条件关系；creteria 为具体筛选条件（fileds op values）
pageNum
否
integer
页码, 与offset互斥，如果 offset 和 pageNum 同时出现时，优先处理 pageNum 忽略 offset。与pageSize共同决定所查询的记录范围。当pageNum*pageSize超出最大记录数时，将返回空的结果。 例如: pageNum=3,pageSize=100, 即将总记录数分为每页为100条的记录范围, 3表示查询这个记录范围的第3页(第301条-第400条)

filter 对象说明

参数必须类型说明
mode
否
string
各筛选条件之间的逻辑关系，只能是 AND 或 OR，缺省值为 AND
+
creteria
是
creteria[]
filter 结构体，包含筛选条件的数组，每个字段上只能有一个筛选条件

筛选规则

筛选条件参数说明
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 填写过多参数及其他可能导致筛选规则失效等情形，整个请求将直接失败。

目前还支持对日期进行动态筛选，此时 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只能是昨天、今天或明天。

返回参数

参数类型说明
code
integer
错误码
+
data
data {}
响应数据

示例

请求示例 

curl --request POST \
	--url 'https://developer.kdocs.cn/api/v1/openapi/ksheet/123/sheets/2/records/complex_query?access_token=xxxx' \
	--header 'Content-Type: application/json' \
	--data '{"preferId":"false","pageSize":50,"viewId":111,"maxRecords":10,"fields":"xxxx","offset":2,"filter":{"mode":"AND"}}'

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"preferId\":\"false\",\"pageSize\":50,\"viewId\":111,\"maxRecords\":10,\"fields\":\"xxxx\",\"offset\":2,\"filter\":{\"mode\":\"AND\"}}");
Request request = new Request.Builder()
	.url("https://developer.kdocs.cn/api/v1/openapi/ksheet/123/sheets/2/records/complex_query?access_token=xxxx")
	.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/ksheet/123/sheets/2/records/complex_query?access_token=xxxx"

	payload := strings.NewReader("{\"preferId\":\"false\",\"pageSize\":50,\"viewId\":111,\"maxRecords\":10,\"fields\":\"xxxx\",\"offset\":2,\"filter\":{\"mode\":\"AND\"}}")

	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\":50,\"viewId\":111,\"maxRecords\":10,\"fields\":\"xxxx\",\"offset\":2,\"filter\":{\"mode\":\"AND\"}}"

headers = { 'Content-Type': "application/json" }

conn.request("POST", "/api/v1/openapi/ksheet/123/sheets/2/records/complex_query?access_token=xxxx", 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/ksheet/123/sheets/2/records/complex_query?access_token=xxxx",
	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\":50,\"viewId\":111,\"maxRecords\":10,\"fields\":\"xxxx\",\"offset\":2,\"filter\":{\"mode\":\"AND\"}}",
	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": 50,
	"viewId": 111,
	"maxRecords": 10,
	"fields": "xxxx",
	"offset": 2,
	"filter": {
		"mode": "AND"
	}
});

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/ksheet/123/sheets/2/records/complex_query?access_token=xxxx");
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/ksheet/123/sheets/2/records/complex_query?access_token=xxxx",
	"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: 50,
  viewId: 111,
  maxRecords: 10,
  fields: 'xxxx',
  offset: 2,
  filter: {mode: 'AND'}
}));
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/ksheet/123/sheets/2/records/complex_query?access_token=xxxx");

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\":50,\"viewId\":111,\"maxRecords\":10,\"fields\":\"xxxx\",\"offset\":2,\"filter\":{\"mode\":\"AND\"}}");

CURLcode ret = curl_easy_perform(hnd);

var client = new RestClient("https://developer.kdocs.cn/api/v1/openapi/ksheet/123/sheets/2/records/complex_query?access_token=xxxx");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\"preferId\":\"false\",\"pageSize\":50,\"viewId\":111,\"maxRecords\":10,\"fields\":\"xxxx\",\"offset\":2,\"filter\":{\"mode\":\"AND\"}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

返回示例 

{
  "code": 0,
  "data": {
    "detail": {
      "offset": "D",
      "records": [
        {
          "fields": {},
          "id": "E"
        },
        {
          "fields": {},
          "id": "F"
        },
        {
          "fields": {
            "num": 2
          },
          "id": "C"
        }
      ]
    }
  }
}

错误码

请参考错误码说明