見出し画像

【GAS】でGoogleカレンダーの予定の作成や取得をする！Calendarクラス編

いがぐり

GoogleAppsScript で Google カレンダー内のカレンダーに予定を作成したり、既存の予定を取得したい場合、「Calendar クラス」を使って、分類されたカレンダー内の予定の操作などができます。

また、GoogleAppsScript で Google カレンダーを扱うにあたり事前に知っておくべき、Google カレンダーがどの様なものかをまとめた記事もありますので、よろしければご参照ください。


Calendar クラスの概要

カレンダー（Calendar）とは、Google カレンダー内に、同じカテゴリーでまとまった予定が収まっているものになります。
そのカレンダーを GoogleAppsScript のオブジェクトとして扱えるのが、「Calendar クラス」です。

Calendar クラスのオブジェクトの構造

カレンダーは大きな項目として、

  • カレンダーの属性情報（カレンダー名、説明など）

  • 予定（CalendarEvent）や繰り返しの予定（ CalendarEventSeries）

から構成されています。

それぞれ詳しく見ると

＜カレンダーの属性情報＞

変更不可能な属性情報

  1. カレンダー ID

  2. デフォルトのカレンダーかどうか

  3. 自分がそのカレンダーのオーナー（owned）かどうか

変更可能な属性情報

  1. カレンダー名

  2. カレンダーの説明

  3. カレンダーの色

  4. カレンダーに関わるタイムゾーン

  5. 予定が表示か非表示にされているかの設定

  6. マイカレンダーのリストへの掲載設定

＜カレンダーの予定＞

上記にもあるとおり、カレンダーには同じカテゴリーでまとまった予定が収められていますが、そんな予定には二種類あります。
一つは、「一回限りの予定」であり、もう一つは「繰り返される予定」です。

一回限りの予定（CalendarEvent クラスのオブジェクト）

「一回限りの予定」とは、予定が、ある日時に一度だけ作成さるものを指します。
同窓会の開催の予定を作成するなど、その日限り（一回限り）の予定を作成する場合です。
「一回限りの予定」は、その予定の時間や内容が収まった「CalendarEvent クラス」のオブジェクトとしてカレンダーに収まっています。

繰り返される予定（CalendarEventSeries クラスのオブジェクト）

繰り返される予定は、先ほどの一回限りの予定の対比にあたり、内容が同じ予定を複数の異なる日時に指定できるもので、「CalendarEventSeries クラスのオブジェクトとしてカレンダーに収まっています。

Calendar クラス のオブジェクトの取得

「Calendar クラス」のオブジェクトを使う前に、そのオブジェクトを取得しなければなりませんが、ここでは、それぞれ他のクラスから「Calendar クラス」のオブジェクトの取得の仕方を紹介したいと思います。
それぞれのクラスからと書きましたが、「Calendar クラス」のオブジェクトは「CalendarApp クラス」からしか取得できませんので、それだけからの説明になります。

CalendarApp クラスから

以下に紹介する CalendarApp クラスのメソッドのより詳しい説明は、こちらの記事にあります。

戻り値が全て「Calendar クラス」のオブジェクトのメソッド

新規のカレンダーを作成し、そのカレンダーのオブジェクトの取得
CalendarApp.createCalendar(新規カレンダー名、（オプション）);

カレンダーの ID からそれに対応するカレンダーのオブジェクトの取得
CalendarApp.getCalendarById(カレンダーの ID);

自分がオーナーであるカレンダーの ID に対応するカレンダーのオブジェクトの取得
CalendarApp.getOwnedCalendarById(カレンダーの ID);

戻り値が全て「Calendar クラス」のオブジェクトのリストのメソッド

既存の全てのカレンダーのオブジェクトの取得
CalendarApp.getAllCalendars();

カレンダー名から対応するカレンダーのオブジェクトの取得
CalendarApp.getCalendarsByName(カレンダー名);

自分がオーナーである全てのカレンダーのオブジェクトの取得
CalendarApp.getOwnedCalendars();

自分がオーナーであるカレンダーの名前から対応するカレンダーのオブジェクトの取得
CalendarApp.getOwnedCalendarByName(カレンダー名);

Calendar クラスのメソッド

取得した「Calendar クラス（カレンダー）」のオブジェクトでできる事（メソッド）を紹介していきます。

カレンダーの属性情報の取得または設定

変更不可能な属性情報の取得

カレンダー ID の取得
.getId()
引数：無し
戻り値：カレンダーの ID（文字列）

自分がオーナーのカレンダーかどうか
.isOwnedByMe()
引数：無し
戻り値：オーナーなら true、出ないなら false（ブール値）

カレンダーがデフォルトのカレンダーかどうか
.isMyPrimaryCalendar()
引数：無し
戻り値：デフォルトなら true、でないなら false（ブール値）

変更可能な属性情報の取得と設定

  • カレンダー名

＜取得＞
.getName()
引数：無し
戻り値：カレンダー名（文字列）
＜設定＞
.setName(カレンダー名)
引数：新しいカレンダー名（文字列）
戻り値：Calendar クラスのオブジェクト

  • カレンダーの説明

＜取得＞
.getDescription()
引数：無し
戻り値：カレンダーの説明（文字列）
＜設定＞
.setDescription(カレンダーの説明)
引数：カレンダーの説明（文字列）
戻り値：Calendar クラスのオブジェクト

  • カレンダーの色

＜取得＞
.getColor()
引数：無し
戻り値：色の１６進表記（文字列）
＜設定＞
.setColor(カレンダーの色)
引数：色の１６進表記（文字列）または「CalendarApp.Colors のプロパティ」
戻り値：Calendar クラスのオブジェクト

  • カレンダーに関連するタイムゾーン（timeZone）

＜取得＞
.getTimeZone()
引数：無し
戻り値：カレンダーに関連するタイムゾーン（文字列）
＜設定＞
.setTimeZone(タイムゾーン)
引数：カレンダーに関連するタイムゾーン（文字列）
戻り値：Calendar クラスのオブジェクト

  • カレンダーの予定の表示、非表示

＜取得＞
.isSelected()
引数：無し
戻り値：表示されていれば true、非表示なら false（ブール値）
＜設定＞
.setSelected(表示するか非表示か)
引数：表示するなら true、非表示なら false（ブール値）
戻り値：Calendar クラスのオブジェクト

  • カレンダーがマイカレンダーのリストにあるか、ないか

＜取得＞
.isHidden()
引数：無し
戻り値：マイカレンダーのリストにあれば false、なければ true（ブール値）
＜設定＞
.setHidden(マイカレンダーのリストに入れるか否か)
引数：マイカレンダーのリストに入れるなら false、入れないなら true（ブール値）
戻り値：Calendar クラスのオブジェクト

カレンダーの予定の作成と取得

カレンダーに予定の作成や取得ができるメソッドを、予定の作成と取得で分けて紹介していきます。

＜予定の作成＞

予定を作成する際に指定できる「オプション」という引数がありますが、これは任意の引数であり、予定に追加情報を指定したい場合に、辞書型として設定します。
以下に、指定できる項目を紹介します。

キー :　 内容
descirption : 予定の説明（文字列）
location : 予定の場所（文字列）
guests : 予定に参加させたい人のメールアドレス（文字列）
sendInvites : 参加させたい人に招待のメールを送るかどうか（ブール値）

設定例

options = {
    description: '予定を作ってみた',
    location: '東京駅',
    guests: 'sample_A@e_mail.com, sample_B@e_mail.com',
    sendInvites: true
}

caledar.createEvent('テスト', start, end, options);

一回限りの予定の作成

  • 終日の予定でない予定

.createEvent(予定のタイトル、開始日時、終了日時、（オプション（任意））)

引数：
　予定のタイトル（文字列）
　開始日時（Date クラスのオブジェクト）
　終了日時（Date クラスのオブジェクト）
　（任意）オプション（辞書型：この章頭に説明あり）

戻り値：作成された予定（CalendarEvent クラスのオブジェクト）

// 開始日時（2024/4/1 10:00）
let startTime = new Date('April 1, 2024 10:00:00');
// 終了日時（2024/4/1 12:00）
let endTime = new Date('April 1, 2024 12:00:00');

let newEvent = calendar.createEvent('テスト', startTime, endTime);

  • 終日の予定（1 日のみの予定）

.createAllDayEvent(予定のタイトル, 日付,（オプション（任意）)

引数：
　予定のタイトル（文字列）
　日付（Date クラスのオブジェクト）
　（任意）オプション（辞書型：この章頭に説明あり）

戻り値：作成された終日の予定（CalendarEvent クラスのオブジェクト）

let newAllDayEvent = calendar.createAllDayEvent('エイプリルフールの次の日',new Date('April 2, 2024'));

  • 終日の予定（複数日にわたる予定）

.createAllDayEvent(予定のタイトル, 開始日, 終了日,（オプション（任意）)

引数：
　予定のタイトル（文字列）
　開始日（Date クラスのオブジェクト）
　終了日（Date クラスのオブジェクト）
　（任意）オプション（辞書型：この章頭に説明あり）

戻り値：作成された複数日にわたる終日の予定（CalendarEvent クラスのオブジェクト）

// 開始日
let startDay = new Date('March 3, 2024');
// 終了日
let endDay = new Date('March 6, 2024');

let newAllDayEvent = calendar.createAllDayEvent('５月の４連休', startDay, endDay);

繰り返される予定の作成

  • 終日の予定でない予定

.createEventSeries(予定のタイトル,開始日時,終了日時,繰り返しルール,（オプション（任意））)

引数：
　予定のタイトル（文字列）
　開始日時（Date クラスのオブジェクト）
　終了日時（Date クラスのオブジェクト）
　繰り返しのルール（EventRecurrence クラスのオブジェクト）→ 詳しくはこちら

戻り値：作成された繰り返しの予定（CalendarEventSeries クラスのオブジェクト）

// 毎週火曜日の７時半から８時にゴミ出しの予定を作成

// 火曜日の７時半から８時の日時を設定（2024/4/2は火曜日）
let startDate = new Date('April 2, 2024 07:30:00');
let endDate = new Date('April 2, 2024 08:00:00');

// 毎週繰り返すルールを作成
let recurrenceRule = CalendarApp.newRecurrence().addWeeklyRule();

let newEventSeries = calendar.createEventSeries('ゴミ出し', startDate, endDate, recurrenceRule);

  • 終日の予定

.createAllDayEventSeries(予定のタイトル, 日付, 繰り返しルール,（オプション（任意））)

引数：
　予定のタイトル（文字列）
　日付（Date クラスのオブジェクト）
　繰り返しのルール（EventRecurrence クラスのオブジェクト）→ 詳しくはこちら

戻り値：作成された終日の繰り返し予定（CalendarEventSeries クラスのオブジェクト）

// 毎週水曜日に買い出しの予定を作成

// 水曜曜日の日付を設定（2024/4/3は水曜日）
let startDate = new Date('April 3, 2024');

// 毎週繰り返すルールを作成
let recurrenceRule = CalendarApp.newRecurrence().addWeeklyRule();

let newEventSeries = calendar.createEventSeries('買い出し', startDate, recurrenceRule);

＜既存の予定の取得＞

一回限りの予定の取得

  • 予定の ID から予定を取得

.getEventById(予定の ID)

引数：予定の ID（文字列）
戻り値：ID に対応する予定（CalendarEvent クラスのオブジェクト）

let event = calendar.getEventById('/*予定のID*/');

  • 指定日にある予定を取得

.getEventsForDay(日付, （オプション（任意）)

引数：
　日付（Date クラスのオブジェクト）
　（任意）オプション（辞書型）

戻り値：その日の予定たち（CalendarEvent クラスのオブジェクトのリスト）

オプションには、

キー：内容
start: 取得開始する位置の指定（整数）
max: 取得する限界数を指定（整数）
author: 取得条件に予定の作成に関わった人のメールアドレスを指定（文字列）
search: 取得条件に予定のタイトルにキーワードが含まれるものを指定（文字列）
statusFilters: 取得条件に予定に対する自分の参加状況を指定（CalendarApp.GuestStatusのプロパティのリスト）

が指定できます。

let events = calendar.getEventsForDay(new Date('April 3, 2024'));

  • 指定の日時の範囲内にある予定を取得

.getEvents(範囲開始日時, 範囲終了日時,（オプション（任意））)

引数：
　範囲開始日時（Date クラスのオブジェクト）
　範囲終了日時（Date クラスのオブジェクト）
（任意）オプション（辞書型）

戻り値：指定期間内の予定たち（CalendarEvent クラスのオブジェクトのリスト）

オプションには、

キー：内容
start: 取得開始する位置の指定（整数）
max: 取得する限界数を指定（整数）
author: 取得条件に予定の作成に関わった人のメールアドレスを指定（文字列）
search: 取得条件に予定のタイトルにキーワードが含まれるものを指定（文字列）
statusFilters: 取得条件に予定に対する自分の参加状況を指定（CalendarApp.GuestStatusのプロパティのリスト）

が指定できます。

// 予定の取得範囲の期間の設置（2024/4/1 6:00 から　2024/4/30 18:00までの期間）
let startDate = new Date('April 1, 2024 06:00:00');
let endDate = new Date('April 30, 2024 18:00:00');

let events = calendar.getEvents(startDate, endDate)

繰り返される予定の取得

  • 繰り返し予定の ID から繰り返し予定を取得

.getEventSeriesById(繰り返し予定の ID)

引数：繰り返し予定の ID（文字列）
戻り値：ID に対応する繰り返し予定（CalendarEventSeries クラスのオブジェクト）

let event = calendar.getEventSeriesById('/*繰り返し予定のID*/');

カレンダー自体の削除

カレンダー自体を削除します。

.deleteCalendar()

引数：無し
戻り値：無し

calendarObject.deleteCalendar();

外部から取り込んだカレンダーを削除する

以前に自分の Google カレンダーに取り入れた、他のユーザーなどが作成した外部のカレンダーを削除する。

.unsubscribeFromCalendar()

引数：無し
戻り値：無し

calendarObject.unsubscribeFromCalendar();

この記事が気に入ったらサポートをしてみませんか？