Googleカレンダーは予定を表示する道具なので、通常の画面だけで「今月の仕事は合計何時間」と常に一発表示されるわけではありません。目的によって、標準の分析機能を見る、データを表計算へ出す、Calendar APIや連携ツールで集計する、といった方法を選びます。
最初に「何を合計するか」を決める
| 知りたい数字 | 含めるもの | 注意点 |
|---|---|---|
| 予定時間 | カレンダーに登録した対象予定 | 予定と実績がずれている可能性 |
| 実績作業時間 | 終了後に実績へ修正した予定 | 修正運用が必要 |
| 請求対象時間 | 実績のうち契約上請求できる時間 | 契約判断が必要 |
| 会議時間 | 会議として扱われる予定 | Googleの「時間の分析情報」は対象条件がある |
単にカレンダー内の全予定を足すと、移動、休憩、私用、仮予定なども混ざります。請求に使うなら対象カレンダーや予定名を先に絞る必要があります。
方法1：予定を見ながら手動で集計する
件数が少ない場合は、週表示・月表示で対象予定を確認し、時間を表計算へ入力するだけでも十分です。最も柔軟ですが、月末に転記作業が集中します。
- 対象期間を固定する
- 対象取引先・案件だけを見る
- キャンセル済み・仮予定を除く
- 予定と実績の差を修正する
- 重複予定がないか確認する
方法2：標準機能の「時間の分析情報」を使う
Googleカレンダーには一部の仕事用・学校用アカウントで「時間の分析情報」があり、会議に使った時間などを確認できます。ただし、これはフリーランスの任意作業をすべて集計して請求時間へ変換するための機能とは目的が異なります。利用条件や集計対象はGoogle公式ヘルプで確認してください。
したがって、標準機能で見える「会議時間」と、開発・執筆・デザインなど自分だけで行った作業を含む「稼働時間」を混同しないことが大切です。
方法3：Calendar APIや連携処理で期間内予定を取得する
Google Calendar APIのEvents.listでは、指定カレンダーのイベントを取得でき、`timeMin` / `timeMax` で期間を絞り、`singleEvents=true` で繰り返し予定を個々のインスタンスとして扱う方法があります。レスポンスには複数ページがあり得るため、実装する場合は `nextPageToken` も考慮します。
Calvoが集計対象にする予定
現在のCalvoコードは、取得した予定のうち `start.dateTime` があるものだけを残し、開始・終了の差から分数・時間数を計算します。つまり、時刻を持つ予定は対象になり、終日予定は現在のWorkLog変換対象外です。
また、WorkLogには予定タイトル、説明、日付、開始・終了、カレンダーID・カレンダー名などを保持するコードがあります。複数カレンダーを使う場合の分け方は工数管理の記事で扱います。
集計値が合わないときの確認順
- 期間：終了日を含むか、タイムゾーンが期待通りか。
- 終日予定：時間付き予定として登録されているか。
- キャンセル・変更：実績へ更新されているか。
- 複数カレンダー：必要なカレンダーが対象に入っているか。
- 重複：同じ作業を複数カレンダーへ二重登録していないか。
- 大量イベント：API連携の場合、ページネーションを適切に処理しているか。
請求へ使うなら「合計」の次に分類が必要
月間100時間と分かっても、A社30時間、B社45時間、自社作業25時間のように分けられなければ請求には使えません。取引先や案件ごとの構造化はGoogleカレンダーで工数管理する方法、請求への接続はGoogleカレンダーから請求書を作る方法へ分けています。
期間指定で起きやすい境界のズレ
月間集計では、「8月1日0時から8月31日23時59分まで」のつもりでも、APIやタイムゾーンの扱いによって境界条件を間違えることがあります。Google Calendar APIの `timeMin` / `timeMax` はRFC3339形式の日時を使い、仕様上それぞれイベントの終了・開始に対する境界として説明されています。
自作ツールで集計する場合は、月末日の指定だけでなく、タイムゾーン、上限がexclusiveであること、日付をまたぐ予定をどう扱うかをテストします。UI上の「8月分」とAPIの日時範囲が同じ意味になっているか確認が必要です。
日付をまたぐ予定はどう数えるか
22時から翌2時までのような予定は4時間ですが、「どの日の稼働に入れるか」は用途次第です。請求の総時間だけなら4時間でよくても、日別稼働報告では開始日へまとめるのか、日付境界で2時間ずつ分けるのかを決める必要があります。
CalvoのWorkLog変換コードは開始日時から `date` を作り、開始・終了の差をdurationとして保持します。したがって、日付をまたぐ長時間予定の日別表示については、利用する請求明細形式で期待通りか確認する余地があります。
集計方法を選ぶ基準
| 予定数 / 頻度 | 方法 | 向く理由 |
|---|---|---|
| 月10〜20件程度 | 手動確認＋表計算 | 仕組みを作る方が重くなりにくい |
| 毎週同じ集計 | 連携ツール / スクリプト | 繰り返し転記を減らせる |
| 請求書までつなげたい | 取引先・単価まで持つ専用フロー | 集計後の再入力を減らしやすい |
- 合計の目的が「予定」「実績」「請求」のどれか
- 終日予定を含める必要があるか
- 複数カレンダーを横断するか
- 月またぎ予定の扱いを決めたか
- API利用ならページネーションを確認したか
集計結果を保存するか、毎回再計算するか
カレンダーは後から予定を編集できるため、過去月の請求根拠を毎回Calendar APIから再計算すると、請求時点の数字と後日の数字が変わる可能性があります。請求確定時の合計や明細を別データとして保存するか、変更履歴をどう扱うかも運用設計の一部です。
「現在のカレンダーを分析する」用途なら再計算でも構いませんが、「発行済み請求書の根拠を確認する」用途では、請求時点のスナップショットを追える方が説明しやすくなります。
時間付き予定を請求前のWorkLogとして確認する
Calvoは指定期間のGoogleカレンダー予定を取得し、時間付き予定からWorkLogを作るコードが確認できます。終日予定・大量イベント・外部APIの実機安定動作などは、現在の公開説明では保証していません。
よくある質問
Googleカレンダーに合計稼働時間を表示する標準機能はありますか？
「時間の分析情報」はありますが、対象アカウントやイベント条件があり、任意の全作業を請求用に集計する機能とは異なります。用途を確認してください。
終日予定を8時間として自動計算できますか？
終日予定には開始・終了時刻がないため、一律8時間とみなすのは危険です。現在のCalvoも終日予定をWorkLogへ変換しません。
予定が250件を超えるとGoogle Calendar APIでは取得できませんか？
250はデフォルトのページサイズに関する値です。公式仕様には次ページ取得の仕組みがあります。ただし、Calvo現行実装が大量イベントを完全取得できるかは現在の実装では未検証です。