Index
はじめに
「kintone API レコード一括取得 API の OFFSET の上限値制限について（2019年8月2日）」でお知らせしていますが、
レコード一括取得 API のパラメータ offset の上限値 1 万件の設定を、2020 年 7 月の定期メンテナンスで実施しました。
それに伴い、レコード一括取得時にその結果が 1 万を超える可能性がある場合には、運用・適用中のプログラムのご確認ならびに修正対応の検討をお願いいたします。
レコードを一括で取得する方法については、現在大きく3つの選択肢が考えられます。今回はこれらの方法の使い分けについて紹介します。
基本的な考え方
レコードを一括取得する方法には、「レコード ID を利用する方法」「カーソル API を利用する方法」「offset を利用する方法」の 3つの選択肢があります。
レコードのソート条件を必要としない場合（レコード ID 順で問題ない場合）場合、方法1: レコード ID を利用する方法を利用できます。
レコードのソート条件を必要とする場合のうち、取得するレコードが 1 万件を超えると見込まれる場合、方法2: カーソル API を利用する方法を利用してください。
一方、将来的にも取得するレコードが 1 万件を超えないと見込まれる場合、方法3: offset を利用する方法も利用可能です。
方法 1 レコード ID を利用する方法
特徴
レコード一括取得 API で、レコード ID（レコード番号）の昇順でソートを行い、ID 順にレコードを取得する方法です。
ID を利用する方法のポイントは、次の2点です。
- 「レコード ID ＞ 前回取得したレコードの中で一番最後のレコードのレコード ID」となるように絞り込みを行うこと
- 「order by $id asc」というレコード ID 順に並び替えること
この方法は、kintone に限らず RDBMS 一般で知られており、「シーク法」とも呼ばれています。
高速になる理由は、こちらのページに詳しく紹介されています。
適しているシナリオ
この方法は、次のようなシナリオに適しています。
- レコードのソート条件を必要としない場合（レコード ID 順で問題ない場合）
- レコードID 順にレコードを取得した後、プログラムのロジックで別のソートができる場合
理由
- レコード ID を利用する方法では、レコード取得にかかる時間がレコード数に対して線形比例するため、高速にレコードを取得できます。
- ただし、複数のフィールドでソートした結果を利用したい場合には、複雑なクエリが必要となります。
※ 後述のコーディング例では、複数のフィールドでソートする場合も考慮しています。
実装に関連する情報
方法 2 カーソル API を利用する方法
特徴
カーソル API を使ってレコードを取得する方法です。
カーソル（cursor）とは、DBにおける用語で、データの検索結果に対する「いまどのデータを処理しているか？」という位置を保持するデータです。
DB 上にカーソルを作成し、作成したカーソルの位置情報からレコードを取得することが可能になります。
kintone のカーソル API を使ってレコードを一括で取得する流れは、次のとおりです。
- カーソルの作成 API を使って、カーソルを作成する。
- カーソルからレコードを取得する API を使って、レコードを取得します。
- カーソルの削除 を使って、作成したカーソルを削除します。
カーソルAPIを利用する方法と方法3：offsetを利用する方法とのデータ取得にかかる時間の比較は、こちらの記事をご参照ください。
適しているシナリオ
この方法は、次のようなシナリオに適しています。
- バッチ処理など、必要なカーソル数を見積りできる場合
理由
- 方法3 の offset を利用する方法に比べ、ソート条件やレコードの件数によらずレコード取得にかかる時間が安定しています。
- 「カーソル1ドメインにつき同時に作成できるカーソルは10個まで」という制約があります。
そのため、必要なカーソル数を見積もりできる、または制御できるような処理に向いています。
同時に複数のユーザーからのリクエストが想定される kintone JavaScript カスタマイズにはあまり向いていません。
実装に関連する情報
方法 3 offset を利用する方法
特徴
レコード一括取得 API を使い、リクエストパラメータの offset を指定して順次レコードを取得する方法です。
offset はレコードの先頭からの距離を表す情報です。
offset と 取得件数を表すリクエストパラメータ limit を指定してレコード一括取得 API を実行すると、「offset 番目のレコードから limit 件」のレコードを取得します。
offset を利用する方法では、offset を少しずつ大きくしていくことで、取得するレコードの位置を指定しながら順次レコードを取得します。
適しているシナリオ
この方法は、次のようなシナリオに適しています。
- 取得するレコード件数が 1 万件を超えない場合
- レコード取得で 1 万件の制限を設けることができる場合
理由
- offset と limit を指定するのみでレコードを順次取得できるため、実装がシンプルになります。
実装に関連する情報
kintone SDK／ツールの10,000件を超えるレコード取得の対応状況
こちらの記事を参照してください。
影響があると考えられる場合
プログラムの修正対応の検討をお願いいたします。
ただし、サイボウズからのお知らせ（2020/4/15更新） のとおり、2020年7月の定期メンテナンス以前からご利用いただいているお客様については、
kintone管理者および該当のアプリ管理者の画面上に「上限値を超過した旨」が警告表示され、リクエストは処理される仕様となっています。
警告表示について
-
2020年7月12日の定期メンテナンスより前に構築されたドメインで表示されます。
- 対象は、超過後に該当のアプリを開いたkintoneシステム管理者（cybozu.com共通管理者含む）、および該当のアプリ管理者です。
- 該当のアプリのレコード一覧画面の上部に、超過した日時とともに警告が表示されます。
- 超過は7月12日の定期メンテナンス以降から検知され、表示の頻度は30日に1度です。
-
前回の表示以降に超過した場合、前回の表示から30日後に再表示されます。
例）9月1日に表示 - 9月5日に制限超過 - 10月1日に再表示（9月30日までにプログラムを改修した場合も、9月5日分の超過として表示されます）
-
offset の指定に関して、以下のお知らせに 4/15 に追加された記述について教えてください。
（お知らせのほうにコメントができなかったので、もっとも関連が深いと思われるこちらの記事にコメントしました）
https://cs.cybozu.co.jp/2019/006924.html
ただし、2020年7月の定期メンテナンス以前からご利用いただいているお客様については、kintone管理者および該当のアプリ管理者の画面上に「上限値を超過した旨」が警告表示され、リクエストは処理される仕様となっています。
※警告が表示されたお客様は上記「3. 本件仕様変更にかかる対応方法」をご確認の上、対応のご検討をお願いします。
「2020年7月の定期メンテナンス以前からご利用いただいているお客様」に関して、管理者およびアプリ管理者の画面上に警告が表示されてリクエストは処理される、とのことですが、
API で取得できるレスポンスに関しては定期メンテナンス前と変わらず、管理者がログインした際にポータルの通知などに警告が表示されている、ということでしょうか。
API のレスポンスに相違が出る旨は記載されていないのでそのような問題はないと思いますが、万が一レスポンスが変わるとアプリケーション側での対応を検討する必要があるため、情報をいただけると助かります。
滝 正尊 様
お世話になっております。cybozu developer network 運営局です。
返信が遅くなってしまい、誠に申し訳ございません。
ご認識の通り、2020年7月の定期メンテナンス以前からご利用いただいているお客様環境では、2020年7月の定期メンテナンス前と変わらず、1万件以上のレコードを取得できます。
ただし、offset上限値1万を超えるレコード一括取得を行うと、サーバーに非常に高い負荷がかかる恐れがあるため、
本記事にて案内している offset を使わない方法にご対応いただきたく、よろしくお願いいたします。
また、警告メッセージについては、管理者およびアプリ管理者がログインした際の kintone 画面において、何らかの形で通知される予定となっております。
よろしくお願いいたします。
「上限値を超過した旨」の警告はどの段階で消えるのでしょう。
８月３１日に現象が出て、その後その事象には至ってないにも関わらず、３１日の表示が消えません。
Toshimichi Konno 様
お世話になっております。cybozu developer network 運営局です。
>「上限値を超過した旨」の警告はどの段階で消えるのでしょう。
警告の表示期間なのですが、
警告の右上に、「☓」マークがあると思いますが、
その「☓」マークを押すまでは、警告は表示されたままになります。
そのため、念のためのご確認なのですが、
（すでに試して頂いていましたら申し訳ありません）
そちらの「☓」マークで警告を消すことができるか、ご確認頂いてもよろしいでしょうか？
お世話になります。
☓マークを押して消しても、ブラウザを閉じて翌日開くと又復活して表示される状態です。
Toshimichi Konno 様
お世話になっております。cybozu developer network 運営局です。
＞☓マークを押して消しても、ブラウザを閉じて翌日開くと又復活して表示される状態です。
状況についてご教示くださりありがとうございます。
不具合の可能性があるので、
お手数ですが、弊社サポートにお問い合わせいただけないでしょうか。
サポートへの問い合わせ方法は こちら をご確認ください。
よろしくお願いいたします。