存在offset限制值的前提下批量获取记录

aki发表于:2019年08月27日 09:43:32更新于:2021年01月19日 16:04:05

Index

概要

正如“使用kintone API的批量获取记录API 时的OFFSET上限(2019年8月2日)”(日文)的通知,2020年7月的定期维护时批量获取记录API的参数offset的上限值设置为1万条。
因此,烦请对您正式环境中或正要应用到正式环境的程序进行检查,如果存在批量获取记录时获取结果可能超过1万条的处理,请做相应的修改

对于批量获取记录的方法,现在大体可以分为3种,本次就对这三个方法在使用上的区别进行介绍。

基本逻辑

对于批量获取记录的方法,有“使用记录ID的方法”、“使用游标API的方法”以及“使用offset的方法”这3个选择。 

如果无需记录的排序条件(可以按照记录ID的顺序排序),可以使用方法1: 使用记录ID的方法

需要记录的排序条件,且要获取的记录可能超过1万条,可以使用方法2: 使用游标API的方法

另外,要获取的记录在将来也不会超过1万条时,可使用方法3: 使用offset的方法

0015d688101cb3e4c227c584a2410a4

方法 1 使用记录ID的方法

特征 

此方法是使用批量获取记录的API ,按照记录 ID(记录编号)的升序排列记录,根据ID顺序来获取记录。

使用ID的要点有以下2点。

  • 筛选出“记录ID > 上次获取的记录中最后一条记录的ID”

  • 使用“order by $id asc”对记录按照记录ID顺序进行重新排序

0015d68826f9fe2a4cd394168c08c6b

此方法不仅限kintone,在RDBMS上也被广泛知晓,其称为“SEEK方法”。
关于速度快的理由,可以参考此页的SEEK方法章节。

适用场景

此方法主要适用于以下场景。

  • 不需要记录的排序条件(可以按照记录ID的顺序排列)

  • 按照记录ID顺序获取记录之后,根据程序的逻辑还可按照其他顺序排列

理由

  • 使用记录ID的方法,获取记录所花的时间和记录条数形成线性比例关系,因此可以高速获取记录。 

  • 但是,要根据多个字段进行排序,并根据此排序来获取记录时,需要复杂的查询。
    ※ 在下述的编程范例中,也考虑了用多个字段进行排序的场景。

与此方法相关的信息

方法 2 使用游标API的方法

特征

使用游标API获取记录的方法。

游标(cursor)是DB用语,在数据的检索结果中,游标可以保存“当前正在处理哪个数据?”的位置。
在DB上创建游标,可从所创建的游标的位置信息中获取记录。

使用kintone的游标API来批量获取记录的流程如下。 

  1. 使用创建游标 API 创建游标。

  2. 使用从游标中获取记录的API,获取记录。

  3. 使用删除游标,删除所创建的游标。

关于使用游标API的方法和方法3“使用offset的方法”,其在获取记录时所需的时间的对比,请参考此文档

适用场景

此方法适用于以下场景。

  • 批量处理等,可以预计需要多少游标的场景

理由

  • 和方法1“使用offset的方法”相比,获取记录所需的时间较为稳定,不被排序条件和记录条数影响

  • 但是,每个域名最多只能同时生成10个游标。
    因此该方法适用于可以预计需要多少游标,或者可控制游标数的处理。
    对于可能存在多个用户同时发送请求的kintone JavaScript 自定义来说,就不适合了。

与此方法相关的信息

方法 3 使用offset的方法

特征

是指使用批量获取记录API,指定请求参数offset,依次获取记录的方法。

offset表示离记录起始位置的距离。
指定offset以及表示获取条数的请求参数limit,然后执行批量获取记录API,即可获取“第offset条记录开始的limit条记录”。

offset的使用方法是:通过逐渐加大offset来变换要获取记录的开始位置,批次获取记录。 

适用场景

此方法适用于以下场景。

  • 要获取的记录不超过1万条

  • 在获取记录时可以设置获取上限为1万条

理由

  • 只要指定offset和limit就可以按顺序批次获取记录,简化开发。

与此方法相关的信息

kintone SDK/工具可否获取超过1万条记录的对照表

请参考此文档

可能受影响时

推荐修改程序。
但是,正如才望子的通知(日语)(2020/4/15更新)中所述,在2020年7月的定期维护之前就开始在使用的用户,即使超过上限值,请求也会被处理,但会在kintone管理员以及相应应用的管理员的页面上显示“超过上限值”的警告。

关于警告

  • 仅在2020年7月12日的定期维护之前搭建的环境里显示。

  • 显示条件是:当超过了1万条上限时,kintone系统管理员(包含cybozu.cn共通管理员)以及应用的管理员在打开超过上限的应用时显示。

  • 在相应应用的记录列表页面的顶部会显示超过的日期以及相应的警告信息。

  • 是否超过的检测在7月12日的定期维护之后开始实施,显示频率为每30天1次。

    • 显示警告之后再次超过时,会在上次显示日期起的30天后再次显示警告。
      例)在9月1日显示警告 - 9月5日超过限制 - 10月1日再次显示警告(即使在9月30日之前修改了程序时,也会显示9月5日超过的警告。