カーソル API を使ってレコードを一括取得する
はじめに
2019 年 7 月版 kintone にカーソル API という新規 API が追加されます。
このカーソル API はレコード全件取得のための API です。
本記事では、次の内容を紹介します。
- カーソル(Cursor)API の説明
- 複数のレコードを取得する API(
records.json
)で offset を指定した場合の性能比較
カーソル API を使ったレコード取得のコーディング例は、 レコード一括取得の JavaScript コーディング例:カーソル API を利用する方法 を参照してください。
カーソル API が追加された理由
2020 年 7 月定期メンテナンスで、
複数のレコードを取得する API(records.json
) のパラメーター offset に上限値 1 万件を設定することを予定しています。
offset に上限値が設定されるため、offset を使ってレコードの一括取得を行っていて、かつ 1 万を超えるレコードを取得する可能性がある場合は、次の方法でレコードを取得してください。
- レコード ID によるソートのみでよい場合: 方法 1:レコード ID を利用する方法
- レコード ID 以外のソートが必要な場合:カーソル API によるレコード一括取得(この記事で紹介します)
記事の後半で紹介しますが、カーソル API を使う方法のメリットは、offset に比べ複雑なソート条件下でもレスポンスが劣化しないことです。
カーソル(Cursor)とは
DB における用語の 1 つで DB 内の位置を保持するデータです。
DB 上にカーソルを作成し、作成したカーソルの位置情報からレコードを取得するということが可能になります。
今回 kintone に追加されたカーソルに関する API は以下の 3 つです。
この API を使ってレコードを取得する一連の流れは以下のようになります。
-
カーソルを作成する API を使用し、カーソルを作成する。
-
カーソルからレコードを取得する API を使用し、レコードを取得する。
-
検索対象のレコードがなくなるまで 2 を繰り返し、レコードを取得する。
offset による一括取得との比較
API のリクエストパラメーターで、ソート条件とレコードの取得数を変更し、さまざまな条件でレコード取得までにかかる時間を計測することで、offset とカーソル API の比較をしていきます。
各条件ごとのグラフは、カーソルの作成から取得対象のレコードを取得してくるまでの累積時間です。
条件 1
- 10 万レコード
$id
のソート
グラフ
条件 2
- 10 万レコード
- 文字列 1 行のソート
グラフ
条件 3
- 50 万レコード
$id
のソート
グラフ
条件 4
- 50 万レコード
- 文字列 1 行のソート
グラフ
グラフを見ていただくと一目瞭然ですが、カーソルによる一括取得ではレコードの取得時間が短く、かつソート条件や取得する件数に左右されていません。
逆に offset による方法は、ソート条件やレコード件数が取得時間に影響していることがわかります。
まとめ
複数のレコードを取得する API(records.json
) のパラメーター offset に上限値が設定されます。
offset による方法でレコードの一括取得を行っている場合は、より高速で一括取得可能なカーソルによる方法に移行をしてください。
主な制限事項
- カーソルは 1 ドメインにつき同時に 10 個まで作成できます。
- カーソルの作成にかけられる時間は 5 分間です。それ以降はタイムアウトします。
- カーソルの有効期限は カーソルの作成 API、または カーソルからレコードを取得する API による最終リクエスト時刻から 10 分です。
その他の制限事項についてはカーソル API のドキュメントを参照してください。
この Tips は、2019 年 7 月版 kintone で動作を確認しています。