【GAS入門#78】今週の予定を一括取得!Calendar.getEvents()で札幌オフィスの会議室予約状況を一覧化しよう

前回(第77回)は、Calendar.createEvent() や createAllDayEvent() を使って、Googleカレンダー上に「月次報告会」の通常予定や「オフィス創立記念日」の終日予定を自動作成する方法を学びましたね。プログラムからカレンダーにどんどん予定を追加できる感動を味わっていただけたかと思います!

カレンダーに予定を書き込めるようになったら、次にやりたくなるのは「すでに登録されている予定をプログラムで読み取って、一覧表示したり整理したりすること」ですよね!

  • 「今週、札幌オフィスの第1会議室はいつ空いているんだろう?」
  • 「今月開催されるミーティングの一覧をスプレッドシートに書き出して共有したい!」
  • 「重複している予定や無駄な空き時間を一括でチェックしたい!」

そんな時に大活躍するのが、今回マスターする Calendar.getEvents() です!

この命令を使えば、指定した期間(例:今週1週間、今月1ヶ月間など)の中に存在するカレンダーの予定を、プログラムでごっそりまとめて取得することができます。

今回は、「札幌オフィス第1会議室の予約状況一覧取得」をテーマに、getEvents() の基本文法から、取得した予定をループ処理で1件ずつ取り出す方法、さらにはスプレッドシートへ自動書き出しする実践テクニック、初心者が必ずハマる落とし穴まで、どこよりも分かりやすく徹底解説していきます!

1. そもそも Calendar.getEvents() とは?

Calendar.getEvents() は、取得したカレンダーオブジェクトに対して「指定した開始日時から終了日時までの間に存在するすべての予定(イベント)をまとめて持ってくる」ための命令(メソッド)です。

コードの構造を分解してみよう

プログラミングの世界では、対象と命令をドット(.)で繋いで記述します。

var events = calendar.getEvents(startTime, endTime);
  • calendar:第76回で学んだ CalendarApp.getCalendarById() や CalendarApp.getDefaultCalendar() で取得した「カレンダー(スケジュール帳)」オブジェクトです。
  • .getEvents(startTime, endTime):カレンダーに対して「指定した開始日時(startTime)から終了日時(endTime)までの予定をすべて集めてきて!」と指示を出しています。

「スケジュール帳」と「メモカードの箱」でイメージしよう!

本連載でおなじみの例えで整理してみましょう。

  • カレンダー(Calendar) = 1冊の「スケジュール帳」全体
  • getEvents(startTime, endTime) = スケジュール帳の中から「今週のページ」だけを開いて、そこに貼られている「予定メモカード」をすべて集めて箱に入れる操作
  • 返ってくる結果(events) = 予定メモカードが順番に入った「配列(リスト)」

第7回で学んだ「お弁当箱(配列)」を覚えていますか? getEvents() を実行すると、取得した予定(CalendarEvent オブジェクト)が、1つの配列の中にズラリと並んだ状態で手に入ります。

取得結果(配列 events)中身(イベントオブジェクト)主な取得メソッド
events[0](1件目の予定)10:00〜11:00「札幌チーム朝礼」.getTitle(), .getStartTime()
events[1](2件目の予定)14:00〜15:30「新商品企画ミーティング」.getTitle(), .getStartTime()
events[2](3件目の予定)16:00〜17:00「スープカレー巡り打ち合わせ」.getTitle(), .getStartTime()

つまり、「期間(開始と終了)を指定して一括取得し、それを配列として受け取る」のが Calendar.getEvents() の基本ルールです!

2. STEP1:準備!「札幌オフィス第1会議室」カレンダーとテスト予定を用意しよう

それでは、実際にGASで動かすための事前準備をしていきましょう。

手順

  1. Googleカレンダーを開くブラウザで Googleカレンダー を開きます。
  2. テスト用の予定をいくつか登録する今日から数日間の間に、以下のようなテスト予定を3〜4件ほど手動(または前回のGAS)で追加しておきます。
    • 例1:札幌オフィス第1会議室:週次進捗会議
    • 例2:札幌チーム:スープカレー試食ミーティング
    • 例3:役員月次報告会
  3. Googleスプレッドシートを新規作成するGoogleドライブから新しいスプレッドシートを作成し、ファイル名を 「札幌オフィス会議室予約管理」 に変更します。
  4. GASのエディタ画面を開く上部メニューの 「拡張機能」 > 「Apps Script」 をクリックします。

エディタが開いたら準備完了です!

3. STEP2:【実践】今週の「札幌オフィス会議室予約状況」を取得してログに出力してみよう!

準備ができたら、さっそく「今日から7日後までの予定」を取得して、実行ログに一覧表示するプログラムを書いていきましょう。

1. コードを入力する

エディタ画面に元々書かれているコードを消して、以下のコードをそのままコピー&ペーストしてください。

function getSapporoRoomSchedule() {
  // ① 自分のデフォルトカレンダー(または指定のカレンダー)を取得する(第76回の復習)
  var calendar = CalendarApp.getDefaultCalendar();
  
  // ② 検索の開始日時(今日)と終了日時(7日後)を設定する
  var now = new Date();
  var startTime = new Date(now.getFullYear(), now.getMonth(), now.getDate(), 0, 0, 0);
  var endTime = new Date(now.getFullYear(), now.getMonth(), now.getDate() + 7, 23, 59, 59);
  
  // ③ 指定した期間内のイベント(予定)を一覧取得する
  var events = calendar.getEvents(startTime, endTime);
  
  // ④ 取得できた予定の件数をログに表示する
  Logger.log("■ 取得した予定の合計件数: " + events.length + "件");
  Logger.log("----------------------------------------------");
  
  // ⑤ ループ処理(for文)で1件ずつ予定のタイトルと開始・終了時間を表示する
  for (var i = 0; i < events.length; i++) {
    var event = events[i]; // 配列からi番目の予定を取り出す
    
    var title = event.getTitle(); // 予定の件名を取得
    var start = Utilities.formatDate(event.getStartTime(), "JST", "yyyy/MM/dd HH:mm"); // 開始時刻(第29回の復習!)
    var end = Utilities.formatDate(event.getEndTime(), "JST", "HH:mm"); // 終了時刻
    
    // ログに出力
    Logger.log("【予定 " + (i + 1) + "】" + title);
    Logger.log("  日時: " + start + " 〜 " + end);
  }
}

2. コードを1行ずつ徹底分解解説!

プログラミング初心者の方のために、重要ポイントを細かく解説しますね!

  • var now = new Date();
    JavaScriptで「現在の日時」を扱うための日付オブジェクトを作成しています。
  • new Date(年, 月, 日, 時, 分, 秒)
    指定した日時の Date オブジェクトを作ります。ここでは「今日の0時0分0秒(startTime)」から「7日後の23時59分59秒(endTime)」までを検索範囲として組み立てています。
  • var events = calendar.getEvents(startTime, endTime);
    本日の主役です!指定した7日間のすべての予定を取得し、配列変数 events に格納します。
  • events.length
    取得した配列の中に「何件の予定が入っているか」の個数を返します。
  • for (var i = 0; i < events.length; i++) { ... }
    配列に入っている予定の数だけ処理を繰り返す定番のループ構文です。
    • events[i] で「i番目の予定カード」を取り出します。
    • event.getTitle() で予定の件名を取得します。
    • event.getStartTime() と event.getEndTime() で開始時刻・終了時刻を取得します。
  • Utilities.formatDate(...)
    第29回で学んだ日付整形命令ですね!カレンダーから取れた日時データ(Dateオブジェクト)を、「2026/09/27 10:00」のような読みやすい文字列に変身させています。

3. 保存して実行する

  1. 画面上部の 「保存アイコン(フロッピーディスク)」 を押します。
  2. 関数が getSapporoRoomSchedule になっていることを確認し、「実行」 ボタンをクリックします。
  3. (※初回実行時はGoogleカレンダーへのアクセス許可を求める「承認プロセス」が出ますので、画面の指示に従って許可してください。第2回の承認手順と同様です!)

4. 実行ログを確認してみよう!

画面下部の「実行ログ」に以下のように表示されれば大成功です!

情報    ■ 取得した予定の合計件数: 3件
情報    ----------------------------------------------
情報    【予定 1】札幌オフィス第1会議室:週次進捗会議
情報    日時: 2026/09/28 10:00 〜 11:30
情報    【予定 2】札幌チーム:スープカレー試食ミーティング
情報    日時: 2026/09/29 12:00 〜 13:00
情報    【予定 3】役員月次報告会
情報    日時: 2026/10/01 15:00 〜 16:30

カレンダーに登録されていた予定が、見事にプログラミングで一括取得できました!

4. STEP3:実務で差がつく!getEvents() の応用パターン3選

ただログに出すだけでなく、実務で使える発展的なテクニックを3つ紹介します。

応用①:取得した予定状況をスプレッドシートへ一覧出力する(appendRow連携)

業務で最もよく使われるのが、カレンダーの予定を取得してスプレッドシートへ自動書き出し(バックアップや共有用)するパターンです。

第7回で学んだ Sheet.appendRow() と組み合わせることで、驚くほど簡単に自動転記ツールが作れます!

function exportScheduleToSpreadsheet() {
  var calendar = CalendarApp.getDefaultCalendar();
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  
  // 今日の0時から7日後までの範囲
  var now = new Date();
  var startTime = new Date(now.getFullYear(), now.getMonth(), now.getDate(), 0, 0, 0);
  var endTime = new Date(now.getFullYear(), now.getMonth(), now.getDate() + 7, 23, 59, 59);
  
  // 予定を取得
  var events = calendar.getEvents(startTime, endTime);
  
  // スプレッドシートに1件ずつ追記(第7回 appendRow の活用!)
  for (var i = 0; i < events.length; i++) {
    var event = events[i];
    
    var title = event.getTitle();
    var start = Utilities.formatDate(event.getStartTime(), "JST", "yyyy/MM/dd HH:mm");
    var end = Utilities.formatDate(event.getEndTime(), "JST", "yyyy/MM/dd HH:mm");
    var description = event.getDescription(); // 予定の詳細・メモを取得
    
    // 1行分のお弁当箱(配列)にしてスプレッドシートの末尾に自動追記!
    sheet.appendRow([title, start, end, description]);
  }
  
  Logger.log("スプレッドシートへの書き出しが完了しました!");
}

これをトリガー(定時自動実行)に仕込んでおけば、「毎週月曜日の朝に今週の会議室予約状況をスプレッドシートへ自動出力する」といった完全自動化が実現できます!

応用②:特定のキーワードが含まれる予定だけに絞り込む(条件分岐 if)

大量にある予定の中から、「スープカレー」という単語が入った打ち合わせだけを抽出したい場合は、JavaScriptの indexOf() や includes() を使って条件分岐します。

for (var i = 0; i < events.length; i++) {
  var event = events[i];
  var title = event.getTitle();
  
  // タイトルに「スープカレー」が含まれている場合のみ処理する
  if (title.indexOf("スープカレー") !== -1) {
    Logger.log("★ピックアップ: " + title);
  }
}

応用③:options パラメータを使って特定の文字で検索取得する

実は getEvents() には、第3引数にオプションオブジェクトを渡してカレンダー検索を行う高機能な書き方も用意されています。

// 「スープカレー」というキーワードが含まれる予定のみをカレンダーから直接取得する
var events = calendar.getEvents(startTime, endTime, {search: 'スープカレー'});

このように {search: '検索ワード'} を指定すると、Googleカレンダー側でフィルタリングされた結果だけを受け取ることができるため、コードがスッキリします。

5. 初心者が絶対につまずく!5大トラップと完全対処法

Calendar.getEvents() を使う際に、初心者が非常によく遭遇するエラーやトラブルを5つ厳選しました。ここで予習しておけば、ハマって悩む心配はありません!

トラップ1:events.getTitle() と書いて TypeError になる!

超・頻出のミスです!

// ✕ エラーになる書き方(eventsは「配列」なので直接メソッドは呼べない!)
var events = calendar.getEvents(startTime, endTime);
var title = events.getTitle(); 
// エラー: TypeError: events.getTitle is not a function

【解説と解決策】

getEvents() が返すのは、予定が入った「箱(配列)」です。箱に対して「タイトルは何?」と聞いても答えてくれません。

必ず events[0] や for ループの中の events[i] のように、箱から1件ずつ予定オブジェクトを取り出してから .getTitle() を呼び出すようにしましょう!

トラップ2:開始日時と終了日時が逆(または同じ)になっていて0件になる

// ✕ NGな例(開始が終了より未来になっている)
var startTime = new Date("2026/10/01");
var endTime = new Date("2026/09/01");

var events = calendar.getEvents(startTime, endTime); // 0件になる!

getEvents(startTime, endTime) は、第1引数が「過去(開始)」、第2引数が「未来(終了)」 である必要があります。順番が逆になっているとエラーにはならず、ただ「0件(空の配列)」が返ってきて原因に気づきにくいため注意しましょう。

トラップ3:Dateオブジェクトの「月」が0始まり(0=1月、11=12月)なのを見落とす

JavaScriptの new Date(year, month, day) では、「月(month)」が0からスタートするルールになっています。

  • new Date(2026, 8, 1) ➡ 9月1日(8は9月を意味する)
  • new Date(2026, 9, 1) ➡ 10月1日(9は10月を意味する)

「10月の予定を取ろうとして month に 10 を指定したら、11月の予定が取れてしまった!」という現象は、この「0始まりルール」が原因です。

トラップ4:指定したカレンダーが存在せず Cannot read properties of null と叱られる

第76回で学んだ CalendarApp.getCalendarById("ID") を使う際、IDの打ち間違いや権限がないカレンダーIDを指定すると、戻り値が null になります。

その null に対して .getEvents() を呼び出すと、以下のエラーが発生します。

TypeError: Cannot read properties of null (reading 'getEvents')

必ずカレンダーIDが正しいか確認するか、テスト時は CalendarApp.getDefaultCalendar()(自分自身のメインカレンダー)を使って動作確認を行いましょう。

トラップ5:終日イベント(全日予定)の終了時刻が「翌日の0:00」になる

「オフィス創立記念日」などの終日イベントを取得した場合、Googleカレンダーの仕様上、終了時刻は「その日の23:59」ではなく「翌日の00:00:00」として保持されます。

日付の判定処理や表示処理を作成する際は、終日イベントかどうかを判定する event.isAllDayEvent() というメソッドを組み合わせて活用するのがベストです!

6. 今回のまとめと次回予告

今回は、指定した期間の予定を一括取得する Calendar.getEvents() について詳しく解説しました。

今日の重要ポイントおさらい

  1. Calendar.getEvents(startTime, endTime) は指定期間の予定を「配列」で取得する命令
  2. 取得結果は配列なので、for ループ等で1件ずつ取り出して操作する
  3. getTitle(), getStartTime(), getEndTime() で予定の詳細情報を引き出せる
  4. Sheet.appendRow() と組み合わせれば、カレンダーの予定をスプレッドシートへ自動書き出しできる

カレンダーから予定を自由自在に読み取れるようになると、会議室の空き状況チェックや業務レポートの自動作成など、自動化のアイデアがどんどん広がりますね!

さて、カレンダーの予定を取得できるようになったら、次は「その予定にミーティング参加者を自動で招待・追加したい!」と思いませんか?

次回(第79回)は、CalendarEvent.addGuest() を使って、「月次報告会」などの予定へ札幌チームのメンバーをプログラムから自動招待する方法を解説します!