批量获取记录

aki • 发表于：2019年08月05日 09:05:08 • 更新于：2024年03月06日 13:12:57

Index

创建游标

给应用创建用于获取记录的游标。

HTTP 方法

POST

URI

https://(子域名).cybozu.cn/k/v1/records/cursor.json

来宾空间内的应用

https://(子域名).cybozu.cn/k/guest/(空间的ID)/v1/records/cursor.json

必要的访问权限

  • 应用的记录查看权限

  • 要获取值的记录的查看权限

  • 要获取值的字段的查看权限

请求参数

参数名称要指定的值必须说明
app数值或字符串必须应用的ID。
fields字符串的数组可省略指定应答中需要返回的字段代码。
省略时，将返回所有具有访问权限的字段。
query字符串可省略查询字符串。用于指定应答中需要返回的记录条件。
查询字符串内，可以使用批量获取记录（在查询中指定条件）中的运算符和选项。
※省略时，将返回所有具有访问权限的字段。
※不可以指定limit或者offset。
size数值或字符串可省略指定一次GET请求中可以从游标获取的记录数。
省略时的初始值为100、上限值为500。

请求的范例

请求头部

POST /k/v1/records/cursor.json HTTP/1.1
Host: example.cybozu.cn:443
X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU=
Authorization: Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=
Content-Type: application/json

  • 请在Content-Type 中指定application/json。 如不指定，JSON 无法解析，执行时会报错。

正文

{    
    "app": 1,    
    "fields": ["记录编号", "创建人", "创建时间"],    
    "query": "创建人 in (LOGINUSER()) and 创建时间 = TODAY() order by 记录编号 asc",    
    "size": 500    
}

应答的范例

{
    "id": "9a9716fe-1394-4677-a1c7-2199a5d28215",
    "totalCount": "123456"
}

JavaScript范例

使用API请求发送 kintone REST API 请求

var body = {    
    'app': 1,    
    'fields': ['记录编号', '创建人', '创建时间'],    
    'query': '创建人 in (LOGINUSER()) and 创建时间 = TODAY() order by 记录编号 asc',    
    'size': 500    
};

kintone.api(kintone.api.url('/k/v1/records/cursor', true), 'POST', body, function(resp) {    
    // success    
    console.log(resp);    
}, function(error) {    
    // error    
    console.log(error);    
});

使用 XMLHttpRequest 请求

var body = {    
    'app': 1,    
    'fields': ['记录编号', '创建人', '创建时间'],    
    'query': '创建人 in (LOGINUSER()) and 创建时间 = TODAY() order by 记录编号 asc',    
    'size': 500,    
    // CSRF TOKEN: 从kintone里执行API(POST, PUT, DELETE)时需要设置    
    '__REQUEST_TOKEN__': kintone.getRequestToken()    
};

var url = 'https://{subdomain}.cybozu.cn/k/v1/records/cursor.json';    
var xhr = new XMLHttpRequest();    
xhr.open('POST', url);    
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');    
xhr.setRequestHeader('Content-Type', 'application/json');    
xhr.onload = function() {    
    if (xhr.status === 200) {    
        // success    
        console.log(JSON.parse(xhr.responseText));    
    } else {    
        // error    
        console.log(JSON.parse(xhr.responseText));    
    }    
};    
xhr.send(JSON.stringify(body));

从游标获取记录

可从游标中获取记录。

HTTP 方法

GET

URI

https://(子域名).cybozu.cn/k/v1/records/cursor.json

来宾空间内的应用

https://(子域名).cybozu.cn/k/guest/(空间的ID)/v1/records/cursor.json

必要的访问权限

  • 应用的记录查看权限

  • 要获取值的记录的查看权限

  • 要获取值的字段的查看权限

请求参数

参数名称要指定的值必须说明
id字符串必须游标的ID。

请求的范例

请求头部

GET /k/v1/records/cursor.json HTTP/1.1
Host: example.cybozu.cn:443
X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU=
Authorization: Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=

正文

{    
  "id": "9a9716fe-1394-4677-a1c7-2199a5d28215"    
}

应答的范例

处理成功后，记录的内容以JSON格式返回。 ※关于各字段的格式，请参考字段格式。

{
  "records": [
    {
      "记录编号": {
        "type": "RECORD_NUMBER",
        "value": "1"
      },
      "创建人": {
        "type": "CREATOR",
        "value": {
          "code": "Administrator",
          "name": "Administrator"
        }
      },
      "创建时间": {
        "type": "CREATED_TIME",
        "value": "2019-05-23T04:50:00Z"
      }
    }
  ],
  "next": false
}

JavaScript样本

使用API请求发送 kintone REST API 请求

var body = {    
    'id': '9a9716fe-1394-4677-a1c7-2199a5d28215'    
};

kintone.api(kintone.api.url('/k/v1/records/cursor', true), 'GET', body, function(resp) {    
    // success    
    console.log(resp);    
}, function(error) {    
    // error    
    console.log(error);    
});

使用 XMLHttpRequest 请求

var param = '?id=9a9716fe-1394-4677-a1c7-2199a5d28215';

var url = 'https://{subdomain}.cybozu.cn/k/v1/records/cursor.json' + param;    
var xhr = new XMLHttpRequest();    
xhr.open('GET', url);    
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');    
xhr.onload = function() {    
    if (xhr.status === 200) {    
        // success    
        console.log(JSON.parse(xhr.responseText));    
    } else {    
        // error    
        console.log(JSON.parse(xhr.responseText));    
    }    
};    
xhr.send(JSON.stringify(body));

删除游标

可删除已创建的游标。

HTTP 方法

DELETE

URI

https://(子域名).cybozu.cn/k/v1/records/cursor.json

来宾空间内的应用

https://(子域名).cybozu.cn/k/guest/(空间内的ID)/v1/records/cursor.json

必要的访问权限

无

请求参数

参数名称要指定的值必须说明
id字符串必须指定游标的ID。

请求的范例

请求头部

DELETE /k/v1/records/cursor.json HTTP/1.1
Host: example.cybozu.cn:443
X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU=
Authorization: Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=
Content-Type: application/json

  • 请在Content-Type 中指定application/json。 如不指定，JSON 无法解析，执行时会报错。

正文

{    
    "id": "9a9716fe-1394-4677-a1c7-2199a5d28215"    
}

应答的范例

{}

JavaScript范例

使用API请求发送 kintone REST API 请求

var body = {    
    'id': '9a9716fe-1394-4677-a1c7-2199a5d28215'    
};

kintone.api(kintone.api.url('/k/v1/records/cursor', true), 'DELETE', body, function(resp) {    
    // success    
    console.log(resp);    
}, function(error) {    
    // error    
    console.log(error);    
});

使用 XMLHttpRequest 请求

var body = {    
    'id': '9a9716fe-1394-4677-a1c7-2199a5d28215',    
    // CSRF TOKEN: 从kintone里执行API(POST, PUT, DELETE)时需要设置    
    '__REQUEST_TOKEN__': kintone.getRequestToken()    
};

var url = 'https://{subdomain}.cybozu.cn/k/v1/records/cursor.json';    
var xhr = new XMLHttpRequest();    
xhr.open('DELETE', url);    
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');    
xhr.setRequestHeader('Content-Type', 'application/json');    
xhr.onload = function() {    
    if (xhr.status === 200) {    
        // success    
        console.log(JSON.parse(xhr.responseText));    
    } else {    
        // error    
        console.log(JSON.parse(xhr.responseText));    
    }    
};    
xhr.send(JSON.stringify(body));

限制事项

创建游标API

  • 创建游标时，一个域名同时仅可执行一个请求。如有请求正在执行，则需要等待请求。

  • 1个域名的有效游标数为10个。
    当达到上限时，需要发生以下其中一种情况才可以打开新的游标。

    • 从现有的其中一个游标中获取所有记录

    • 在现有游标自动删除之前，明确关闭现有游标

    • 现有游标的已过有效期

  • 游标的有效期限为：从游标创建好开始或从使用游标获取记录时发送的最后一个请求开始后的10分钟。

  • 如筛选条件中包含关键字 (like, not like) ，当符合条件的记录超过10万条时，kintone就会停止搜索。
    这种情况，会在应答的头部添加 "x-cybozu-warning : Filter aborted because of too many search results."。

  • 创建游标的时间为5分钟。超过这个时间就会超时。
    超时的情况下，需要在客户端进行修改，简化query，减少搜索记录数，然后再执行。 

从游标获取记录 API

  • 可从游标中获取的记录为在创建游标时作为获取对象的记录。
    但是，各字段的值为获取记录时的值。

  • 如在游标创建之后，更改了访问权限，根据更改后的设置，不再符合搜索条件的记录也有可能会被获取到。
    但是，即使是这种情况，没有查看权限的字段的值还是看不到。

  • 因各字段的值是获取记录时的值，当登录用户设置的语言发生变更时，对应了多语言的字段将受到影响。

  • 从游标获取记录的 API中，返回next: true 的下一条请求的records有可能为空。

  • 获取了可从游标中获取的所有记录时，该游标将自动删除。

补充

从游标获取记录 API

  • 记录数据的语言由认证方式决定。

    • 使用 API 令牌验证：为“Administrator”的显示语言

    • 其他的验证方式：为执行 API 的用户的显示语言

  • 如果语言设置为“与 Web 浏览器的设置相同”，则根据 请求头部 的“Accept-Language”里否指定值，获取到的数据的语言将发生变化。

    • 有指定值：为“Accept-Language”中指定的语言

    • 无指定值：为 cybozu.com 共同管理的 区域设置中设置的语言


回复(2)

  • cybozu •

    for循环是指js语言吗？

    如果是js的话，因为用游标获取数据是异步的，你循环的话请通过同步的方式来处理这个数据。

    通过async await的方式。可以参考下kintone js sdk的源代码：

    https://cybozudev.kf5.com/hc/kb/article/1301794/

    https://github.com/kintone/kintone-js-sdk/blob/c9e756223cca5aca2f30886638c568425f3bd4b7/src/base/module/cursor/RecordCursor.js#L91-L113


    引用 123456 的回复：

    我在for循环中用游标获取所有的数据，虽然【获取了可从游标中获取的所有记录时，该游标将自动删除。】，但是还是报了【创建游标数已达上限】的错误，请问这个问题可能是什么原因导致的以及有可供参考的解决办法吗？

  • 123456 •

    我在for循环中用游标获取所有的数据，虽然【获取了可从游标中获取的所有记录时，该游标将自动删除。】，但是还是报了【创建游标数已达上限】的错误，请问这个问题可能是什么原因导致的以及有可供参考的解决办法吗？


最多浏览的文档