見出し画像

【GAS】でGoogleカレンダーの予定を繰り返させる！Recurrence編

いがぐり

GoogleAppsScript で Google カレンダーに同じ内容の予定を繰り返すために、その繰り返すためのルール（もしくはパターン）の作り方をこの記事では紹介していきます。
同じ内容の予定を繰り返すとは、例えば毎週火曜と金曜に６時から７時までランニングをする予定を作成したい場合では、「６時から７時までランニング」する内容を「毎週火曜と金曜」に繰り返すといったかんじです。
ここでは、この「毎週火曜と金曜」という様な「繰り返すルール」を作成する説明をしていきます。

なお、上で言う「６時から７時までランニング」と言うような、予定の内容自体の作成の方法の説明は、

「Calendar クラス編」の記事の中の「カレンダーに属する予定の作成と取得」の項目の「繰り返される予定の作成」
「CalendarEventSeries クラス編」の記事の中の「繰り返し予定のルールと日時の再設定」

をご覧ください。


「繰り返しのルール」の作成する際の概要

冒頭にも書いたようにここでは繰り返される予定の「繰り返し方」を定義する方法を説明していきます。

ここで、この記事で説明する解釈は主に私の主観によるものに概ねなることをご了承ください。

まずは、この「繰り返しのルール」を作成する際に扱うクラス（class）が「EventRecurrence クラス」と「RecurrenceRule クラス」があるのですが、説明するにあたり２つのクラスに分けてあることがややこしくなるため、まとめて「RecurrenceRule クラス」と勝手ながらさせていただきます。

そして、繰り返しルールの作成の仕方も独自の解釈のもと説明していくことをご了承ください。

どのような「繰り返しルール」が設定できるのか

＜繰り返しルールの作成に伴う大枠の考え＞

まず繰り返しのルールの作成の仕方には大きくわけて、

  • 繰り返す日にちのパターンの追加(add rule)

これは、冒頭のような「毎週火曜と金曜」に予定を繰り返す様に、「週単位」で火曜と金曜の日にちをパターンとして繰り返しルールに追加することを指します。

  • 繰り返される中で繰り返しに該当させない日にちのパターンの設定(add exclusion)

反対にこちらは、「毎週火曜と金曜」に予定を入れますが、もしどちらかの曜日が元旦（1 月 1 日）だった場合は予定を設定しないとするように、予定を繰り返す中で除外するパターンを設定する際に使います。

＜繰り返しルールの繰り返しの頻度＞

繰り返される頻度には、

  • 日単位（Daily）

  • 週ごと（Weekly）

  • 月ごと（Montly）

  • 年ごと（Yearly）

があります。

＜繰り返し日のパターンの設定＞

繰り返し日のパターンとは、先ほどの「毎週火曜と金曜」で説明すると、繰り返される頻度は「毎週」で、
繰り返し日のパターンを「火曜と金曜」と指定することを指します。

また逆に、先ほど「繰り返しルールの大枠の考え」の中で「繰り返す中で繰り返しに該当させない日にちのパターンの設定」にあるように、「毎週火曜と金曜」の中でどちらかが元旦（1 月 1 日）である場合は予定として設定しないとする様に、繰り返す頻度を「毎年」で、繰り返しのパターンを「一番最初の日（1 月 1 日）」を予定としないという、繰り返しのルールから排除するパターンの設定としても使えます。

それでは、設定できる繰り返し日のパターンを繰り返す頻度ごとに紹介していきます。

週ごと（毎週）

毎週の中での繰り返したい（または繰り返しから排除したい）曜日を指定します。
内容：月曜日、火曜日、水曜日、木曜日、金曜日、土曜日、日曜日

月ごと（毎月）

毎月の中で繰り返したい（または繰り返しから排除したい）日にちを指定します。
内容：１〜３１日

年ごと（毎年）

毎年の中で繰り返したい（または繰り返しから排除したい）期間を指定します。
期間には、日にち、週そして月があります。
それぞれでみてみましょう。

  • 日にち

毎年の元旦を 1 として、大晦日を３６５（３６６）日目とした中で指定します。
内容：１〜３６５（３６６）日

  • 週

毎年の最初の週を１週目として、年末最後の週を５３週目とした中で指定します。
内容：１〜５３週目

  • 月

１月から１２月の中で、予定を設定したい月を指定します。
内容：１〜１２月

＜繰り返しルールの制御＞

繰り返しルールの制御とは、繰り返す回数を指定したり、繰り返す期限を設定したり、または繰り返す間隔をあけたりすることができます。
それぞれ簡単に説明していきます。

繰り返す回数の指定（times）

「毎週火曜と金曜の６時から７時までランニングする」予定を１０週間だけ設定したい場合に、繰り返しの回数制限を設けれるのです。
ですので、この場合は「毎週火曜と金曜」の予定を１０回繰り返す指定をするのです。

繰り返す期限の指定（until）

「毎週火曜と金曜の６時から７時までランニングする」予定を、例えばマラソン大会がある３月１日まで続けたい場合などに使えるでしょう。
こちらの場合は「毎週火曜と金曜」の予定を 3 月 1 日まで繰り返す指定ができます。

繰り返す間隔の指定（interval）

「毎週火曜と金曜の６時から７時までランニングする」予定を隔週（２週間の内の最初の一週間ごと）にしたい場合に毎週ではない週の間隔をあけれるのです。
こちらの場合は、「毎週火曜と金曜」の予定を２週間に１週ごとに繰り返す指定ができます。

また、３週間ごとと指定した場合は、３週間の内の初めの１週間に予定が入り、２週目、３週目は予定が入らず、次の３週間の初めの週である４週目に予定が入るのです。
なお、一周ごとに繰り返すことを指定した場合は、毎週と同じことになります。

どのように「繰り返しルール」を作成していくのか

「繰り返しルール」を作成する手順の流れ。

  1. 「繰り返しのルール」を作成するための、繰り返しルール（EventRecurrence クラス）のオブジェクトを生成：必須（初めの一回のみ）

  2. 設定するのが、「繰り返す日にちのパターンの追加」か「繰り返しに該当させない日にちのパターンの設定」なのかを決めます。：必須（追加する繰り返しのルールごとの最初に）

  3. 「繰り返し日の頻度」を決めます。（日単位、週ごと、月ごと、年ごと）：必須（追加する繰り返しのルールごとの最初に）

  4. 「繰り返し日のパターン」を指定します。「毎週火曜と金曜」なら火曜日と金曜日を指定する形です。：任意

  5. 「繰り返しルールの制御」を指定します。「毎週火曜と金曜」の予定を 3 月 1 日まで繰り返すことを指定できます。：任意

「繰り返しルール」作りの流れにおける決まり事

  • 上の１は、繰り返しのルールを作っていくためのオブジェクトが必要なので、それを生成するために最初の一回のみ発動する。let recurrence = CalendarApp.newRecurrence();

  • 繰り返しのルールは、複数の「繰り返しパターン」を追加できるので、２〜５までを一つとして何個でもループして追加できる。

  • ２、３は、メソッドで設定しますが、そのメソッドで２、３をまとめて指定できるメソッドとなっています。（.addDailyRule(), .addDailyExculsion()）

  • ４は任意で、もし４を指定しなかった場合は、「繰り返しの予定（CalendarEventSeries クラス）」を作成する際に指定した予定の日時に基づいて繰り返されます。
    例えば、２０２４年の 3 月 1 日からの繰り返しの予定を毎週繰り返すと指定した場合、２０２４年の 3 月 1 日が金曜なので、毎週金曜日に予定が繰り返されるのです。
    なお、「繰り返し予定」を作成するには、基本的に「Calendar クラス」の「.createEventSeries(...)」や「.createAllDayEventSeries(...)」のメソッドで作成します。

  • ５は任意で４も任意ですが、４が指定されていなくても５を指定することができます。
    例えば、３月１日からの予定を、２、３にあたる毎週繰り返すと指定し、それが毎週金曜日（3 月 1 日が金曜として）の予定となりますが、それの繰り返し回数を５回とできるのです。

  • 5 は任意ではありますが、指定しない場合、永遠と繰り返しのルールが適用されるので、回数や期限を繰り返しパターンを追加するたび（２〜４までの設定）に指定した方が良いと思います。

詳しいメソッドの説明は下で行いますが、ここでどの様に繰り返しのルールを作成していくのかみていきましょう。

お題：２０２４年３月 1 日（金曜日）を初日とした、毎週火曜と金曜日の６時から７時までにランニングを２０２５年の４月 1 日の市民マラソン大会までの予定を作成する。
なお、正月（１月１日〜１月３日）がどちらかの曜日である場合は除き、なんとなく１０月のみは火曜と金曜に加えて日曜日もランニングしようと決意。

上の例題を実現する繰り返しルールが適用された予定の作成する過程のコードを、ちょっと複雑ですが、みてみましょう。

// 繰り返しの期限を設定
let untilDate = new Date('April 1, 2025');

//　繰り返しのルールを作成するためのオブジェクトを生成
let recurrence = CalendarApp.newRecurrence();

//　毎週、火曜と金曜を期限まで繰り返すパターンをルールに追加
recurrence.addWeeklyRule().onlyOnWeekdays([CalendarApp.Weekday.TUESDAY, CalendarApp.Weekday.FRIDAY]).until(untilDate);

//　毎年、１月１、２、３日（年初めから1,2,3番目の日付）は、期限まで予定を入れさせない
recurrence.addYearlyExclusion().onlyOnYearDays([1,2,3]).until(untilDate);

//　期限までの１０月のみ日曜日もランニングする予定を設定
recurrence.addWeeklyRule().onlyOnWeekday(CalendarApp.Weekday.SUNDAY).onlyInMonth(CalendarApp.Month.OCTOBER).until(untilDate);

//　デフォルトのカレンダーに、２０２４年３月１日始まりの6時から７時までのランニングの予定を上で作成した繰り返しルールを適用させた繰り返す予定を作成
let cal = CalnedraApp.getDefaultCalend();
cal.createEventSeries('ランニング', new Date('March 1, 2024　6:00:00'), new Date('March 1, 2024　7:00:00'), recurrence);

そのほかに設定できること

作成した「繰り返しルール」に対して、作成してルールが適用されている地域の「タイムゾーン」と「週の始まりの曜日」を指定できます。
こちらは詳しくわからなかったので割愛させていただきます。

「繰り返しルール」の作成の説明

ここからは、繰り返しルールを構築するためのメソッドをどのような「繰り返しルール」が設定できるのか」の項目で分けた並びで紹介していきます。

追加する繰り返しルールのタイプを設定（繰り返しの頻度と繰り返しの日のパターンを追加するのか排除するのか）

これから作成する繰り返しのルールが、期間（日ごと、週ごと、月ごと、年ごと）に沿って、繰り返すものとして追加するのか、それとも排除（指定した日のパターンを避ける）するのかを宣言する様な形でメソッドを呼びます。

繰り返すものとして追加する

毎日繰り返すルールを追加
.addDailyRule()
引数：無し
戻り値：RecurrenceRule クラスのオブジェクト

毎週繰り返すルールを追加
.addWeeklyRule()
引数：無し
戻り値：RecurrenceRule クラスのオブジェクト

毎月繰り返すルールを追加
.addMonthlyRule()
引数：無し
戻り値：RecurrenceRule クラスのオブジェクト

毎年繰り返すルールを追加
.addYearlyRule()
引数：無し
戻り値：RecurrenceRule クラスのオブジェクト

指定した日のパターンを繰り返しのルールから排除する

日ごとのパターンを繰り返しルールから排除
.addDailyExclusion()
引数：無し
戻り値：RecurrenceRule クラスのオブジェクト

週ごとのパターンを繰り返しルールから排除
.addWeeklyExclusion()
引数：無し
戻り値：RecurrenceRule クラスのオブジェクト

月ごとのパターンを繰り返しルールから排除
.addMonthlyExclusion()
引数：無し
戻り値：RecurrenceRule クラスのオブジェクト

年ごとのパターンを繰り返しルールから排除
.addYearlyExclusion()
引数：無し
戻り値：RecurrenceRule クラスのオブジェクト

追加する繰り返しルールの日にちのパターンを設定

＜繰り返し日のパターンの設定＞で見たように、繰り返しの頻度（日ごと、週ごと。。。）の中で、どのような日のパターンで繰り返していくか指定するためのメソッドになります。
上で言うと、「毎週火曜と金曜」の「火曜と金曜」を指定するところにあたります。

週ごと

毎週の中で一日だけ指定したい場合.onlyOnWeekday(曜日)
引数：曜日（CalendarApp.Weekdayのプロパティ）
戻り値：RecurrenceRule クラスのオブジェクト

毎週の中で複数日を指定したい場合.onlyOnWeekdays(曜日たち)
引数：曜日たち（CalendarApp.Weekdayのプロパティのリスト）
戻り値：RecurrenceRule クラスのオブジェクト

月ごと

毎月の中で一日だけ指定したい場合.onlyOnMonthDay(月の日にち)
引数：日にち（1...31 の整数）
戻り値：RecurrenceRule クラスのオブジェクト

毎月の中で複数日を指定したい場合.onlyOnMonthDays(月の日にち達)
引数：日にち達（1...31 の整数のリスト）
戻り値：RecurrenceRule クラスのオブジェクト

年ごと

  • 年初め（１月１日）を１日目とし、年末（１２月３１日）を３６５日目とした中からの日を指定

年間の中で一日だけ指定したい場合.onlyOnYearDay(数え日)
引数：数え日（1...366 の整数）
戻り値：RecurrenceRule クラスのオブジェクト

年間の中で複数日を指定したい場合.onlyOnYearDays(数え日たち)
引数：数え日たち（1...366 の整数のリスト）
戻り値：RecurrenceRule クラスのオブジェクト

  • 年の初めの週を１週目として、年末最後の週を５３週目とした中から追加したい一週間を指定

年間の中で一つの週だけ指定したい場合.onlyOnWeek(数え週)
引数：数え週（1...53 の整数）
戻り値：RecurrenceRule クラスのオブジェクト

年間の中で複数の週を指定したい場合.onlyOnWeeks(数え週たち)
引数：数え週たち（1...53 の整数のリスト）
戻り値：RecurrenceRule クラスのオブジェクト

  • 特定の月で予定を指定したい場合に設定

一つの月で予定を指定したい場合.onlyInMonth(月)
引数：月（CalendarApp.Monthのプロパティ）
戻り値：RecurrenceRule クラスのオブジェクト

一つの月で予定を指定したい場合.onlyInMonths(月たち)
引数：月たち（CalendarApp.Monthのプロパティのリスト）
戻り値：RecurrenceRule クラスのオブジェクト

追加した繰り返しパターンの繰り返し方の制御（回数、期限、間隔）を設定

回数指定

追加した繰り返しのパターンの回数を指定.times(回数)
引数：回数（整数）
戻り値：RecurrenceRule クラスのオブジェクト

期限の指定

追加した繰り返しのパターンの期限を指定.until(期限日)
引数：期限の日付（Date クラスのオブジェクト）
戻り値：RecurrenceRule クラスのオブジェクト

繰り返す間隔の指定

追加した繰り返しのパターンが何回に一回有効になるかを指定.interval(何回に一回か)
引数：何回に一回か（整数）
戻り値：RecurrenceRule クラスのオブジェクト

###　番外編：繰り返すまたは繰り返しから排除したい日を直接指定する

今までに出てきてはいないのですが、繰り返すパターン（毎週の火曜日と金曜日など）を指定する方法を紹介していましたが、ここで紹介するのは、繰り返す日付を直接指定することができるメソッドの紹介です。
こちらで繰り返しを指定した場合、この繰り返しパターンに対して回数や期限、日のパターンなどは設定できません。

指定した日に予定を繰り返す.addDate(日付)
引数：日付（Date クラスのオブジェクト）
戻り値：EventRecurrence クラスのオブジェクト

指定した日には予定を繰り返さない.addDateExclusion(日付)
引数：日付（Date クラスのオブジェクト）
戻り値：EventRecurrence クラスのオブジェクト

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