今回はライブラリの話ではなく、GAS x freeeAPI で実務で使うコードを書く上で、初学者が最初につまづくポイントのひとつであるoffsetに関しての記事です。
一度に取得できる最大のレコード数には制限がある
- 勘定科目
- 取引先
- メモタグ
- 取引
などなど、 様々なマスタ項目やトランザクションデータをスプレッドシート等に取得したいと言うニーズはあると思います。 ところが、freee APIで一度に取得できる最大のレコード数には制限があります。
早速リファレンスを確認してみましょう。
画像はメモタグの例ですが、一度に取得できるメモタグの最大件数は3000件となっています。
3000件以上を取得したい場合は、offsetというパラメータを使用して3001件目以降のレコードを取得できます。
このoffsetを駆使して最大数以上のレコードを取得する方法については、私のGASの先生であるつじけ（@TsujiKenzo）さんがブログですでに考察されています。
[GAS][会計freee]レコードの開始値（オフセット値）を操作しよう
offset とは「ずらし」のことである
聞き慣れないoffsetの意味を調べると「〔～を〕相殺する、埋め合わせる」というような意味が出てきます。これがなぜ「ずらし」につながるのかは、英語堪能な識者の意見を待ちたいと思います。
ともかくも、offsetは「ずらし」のことで、今回のように取得したいレコードの範囲をずらすパラメータとしてoffsetが用意されています。ちなみに、エクセルにもOFFSET関数というものがあり、これも「ずらす」のが機能の関数です。
ExcelでOFFSET関数の使い方｜指定した位置のセル範囲を参照する
今回のメモタグの例で言うと仮に3000件以上のレコードがあった場合、3001件目以降のレコードを取得するために取得範囲をずらすのが、このパラメータの機能です。
彼にレコードが6001件あった場合、それを最小のAPIリクエストで取得しようとした場合は…
- 1回目のリクエストで1-3000件目のメモタグを取得（この時のoffsetのパラメータは0）
- 2回目のリクエストで3001-6000件目のメモタグを取得（この時のoffsetのパラメータは3000）
- 3回目のリクエストで6001件目のメモタグを取得（この時のoffsetのパラメータは6000）
となります。6001件分のメモタグを一度のAPIリクエストで取得できなくても、こうして対象範囲をずらすことですべてのレコードを取得することができます。
offsetで取得範囲をずらしていくコードの一例
このoffsetを使ってレコード全件を取得する方法はいくつかのアプローチが考えられますが、私は以下のロジックを採用しました。
- 前提：取得したいデータの総数はわからない
- 最初 offset = 0 で設定最大数（limit = 3000）取得のリクエストを送った結果、最大件数（3000）のレコード取得ができた => まだ未取得のレコードがあるかも
- 設定最大数 = 取得できたレコード数 の場合は offset に取得できたレコード数を加えて、ループして再度リクエストを送る（offset = offset + limit）
- 設定最大数 > 取得できたレコード数 になったらループを終了
以下はライブラリに実装しているコードの一部ですが、メモタグを全数取得するために上記のロジックでループ処理をさせています。
function offsetLoop_() {
// メモタグオブジェクト一覧を格納する空の配列
let aryTags = [];
// メモタグ取得件数の上限以上のメモタグの登録がある場合にオフセット（ずらし）を行い全件を取得
for (let offset = 0; offset === aryTags.length; offset += limit) {
const ary = APIリクエストでメモタグを取得して配列に格納する処理をここに書く;
aryTags = aryTags.concat(ary); // 取得したメモタグ一覧の配列をaryTagsに結合
}
return aryTags;
}シンプルなfor文によるループですが、offset === aryTags.length が成立している、つまりずらしの数と取得できたレコード数が一致している間はこのループ処理が継続します。
offsetのずらしの数は、ループの都度 offset += limit でlimit（指定した取得数）の分だけずれていきます。
