どうも。つじけ（tsujikenzo）です。このシリーズでは 「会計freeeで100件以上の取引を取得しよう」 ということで全3回でお送りします。今日は2回目です。
前回のおさらい
前回は、「会計freeeで100件以上の取引を取得しよう」 の1回目として 「複雑な処理は関数を切り分けよう」 をお届けしました。
今回は、「レコードの開始値（オフセット値）を操作しよう」 をお届けします。
アジェンダ
- リファレンスとリクエストURL
- whileを使った可変offset
リファレンスとリクエストURL
会計freeeから取引を取得するさい、異なる目的ごとに都度サーバーへアクセスすると、その分サーバーに負担をかけることになります。
できれば、取得した取引をGASやスプレッド上で振り分けるなど、サーバーへのアクセスは1度だけにしたいものです。
その心構えは素晴らしいのですが、会計freeeのAPIリファレンスを確認すると、「一度に取得できる最大取引数は100件」とあります。
100件以上の取引を全件取得できるように、処理を自動化してみましょう。
開始日と終了日
リクエストURLのパラメータには、[開始日]と[終了日]プロパティがあります。日時の範囲を指定してレコードを取得できます。
limit
デフォルトでは、取得するレコードのlimitは20件ですが、最大[3000]を指定できます。
const requestUrl = `https://api.freee.co.jp/api/1/deals?company_id={事業所ID}&start_issue_date=${startIssueDate}&end_issue_date=${endIssueDate}&limit=200`;
offset
リクエストURLのパラメータには、[offset（オフセット）]という、 取得レコードの開始値プロパティ があります。
100件以上のレコードがある場合は、0～99、100～199、200～299のように、100件ずつ取得できそうです。※offsetは0（ゼロ）始まりに注意が必要です。
総レコード数の取得
取引（deals）のエンドポイントでは、最終取得レコードに到達すると、総レコード数を含む [meta]プロパティ を発行します。※1
[meta]プロパティには、[total_count]プロパティ が含まれており、整数で、総レコード数を格納しています。
（※1 個人的な憶測です。違っていたら公式さんごめんなさい。）
「期間範囲」「最大取得レコード数」「オフセット値」という3つの素材が揃いましたので、Loopを回してみましょう。
whileを使った可変offset
「期間範囲」は固定でいいと思います。全件取得なので、1年分でも構いませんし、1か月分でも構いません。
//リクエストURLに必要な開始日と終了日
const startIssueDate = '2021-01-01';
const endIssueDate = '2021-12-31';
「総レコード数」を取得するために、別途、1件のみレコードを取得して、総レコード数を変数に格納しておきます。
//総レコード数を確認するためのリクエストURL(limit=1がポイント)
const requestUrl = `https://api.freee.co.jp/api/1/deals?company_id=2606452&start_issue_date=${startIssueDate}&end_issue_date=${endIssueDate}&limit=1`;
//HTTPリクエストをリクエストURLに送信する
const response = UrlFetchApp.fetch(requestUrl, params);
//JSONオブジェクトに変換
const jsonObj = JSON.parse(response);
//総レコード数
const totalCount = jsonObj['meta']['total_count']; //例:2456
offset値を準備して、while文で回します。
先に完成したコードをお伝えします。
let offset = 0;
//全レコードを取得する
while (offset < totalCount) {
const requestUrl = `https://api.freee.co.jp/api/1/deals?company_id=2606452&start_issue_date=${startIssueDate}&end_issue_date=${endIssueDate}&limit=100&offset=${offset}`;
//HTTPリクエストをリクエストURLに送信する
const response = UrlFetchApp.fetch(requestUrl, params);
//スプレッドシートへ出力
setAllDeals_(response);
//一度に取得できるlimitが100件なのでoffsetも100ずつcountUpする
offset += 100;
//3秒待機
Utilities.sleep(3000);
}
console.log('レコードはこれ以上ありません');
while文は 条件式がtrueであり続ける限りLoop処理を行う 構文です。
offset値が総レコード数を越えるまで、Loopを行います。
const totalCount = 2456;
let offset = 0;
while(offset < totalCount){
//処理
offset += 100;
}
スプレッドシートへの出力は、次回お届けします。
setAllDeals_(response);
まとめ
以上で、「レコードの開始値（オフセット値）を操作しよう」 ということで「期間範囲」「最大取得レコード数」「オフセット値」をお届けしました。
特に、[limit]プロパティを1にして、総レコード数を含む [meta]プロパティ の [total_count]プロパティ を取得したのは、特徴的だったかと思います。
次回は、「スプレッドシートへ出力する関数」 をお届けします。
このシリーズの目次
[GAS][会計freee]100件以上の取引を取得しよう
1. [GAS][会計freee]複雑な処理は関数を切り分けよう
2. [GAS][会計freee]レコードの開始値（オフセット値）を操作しよう
3. [GAS][会計freee]スプレッドシートへ出力する関数
