このガイドでは、カレンダー、予定、それらの相互関係について説明します。
カレンダー
カレンダーは、関連するイベントと、サマリー、デフォルトのタイムゾーン、場所などの追加のメタデータをまとめたものです。各カレンダーはメールアドレスである ID で識別されます。カレンダーには複数のオーナーを指定できます。
イベント
イベントは、特定の日付または期間に関連付けられたオブジェクトです。イベントは一意の ID で識別されます。イベントには、開始日時と終了日時のほかに、概要、説明、場所、ステータス、リマインダー、添付ファイルなどの他のデータが含まれます。
イベントの種類
Google カレンダーは、1 つの予定と定期的な予定をサポートしています。
- 1 つのイベントは、一意の発生を表します。
- 繰り返しの予定では、複数回の発生を定義します。
イベントは、時間指定または終日に設定することもできます。
- 時間指定イベントは、特定の 2 つの時点の間で発生します。時間指定イベントは、
start.dateTime
フィールドとend.dateTime
フィールドを使用して、いつ発生するかを指定します。 - 終日の予定とは、丸 1 日または連続した複数の日にまたがる予定のことです。終日のイベントでは、
start.date
フィールドとend.date
フィールドを使って、イベントが発生するタイミングを指定します。なお、タイムゾーン フィールドは、終日の予定には影響しません。
主催者
予定には 1 つの主催者があります。主催者は、予定のメインコピーを格納するカレンダーです。イベントには複数の参加者を含めることもできます。参加者は通常、招待されたユーザーのメイン カレンダーです。
次の図は、カレンダー、イベント、その他の関連する要素の概念的な関係を示しています。
メイン カレンダーと他のカレンダー
メイン カレンダーは、単一のユーザー アカウントに関連付けられた特別なタイプのカレンダーです。このカレンダーは、新しいユーザー アカウントごとに自動的に作成され、その ID は通常、ユーザーのメインのメールアドレスと一致します。アカウントが存在している限り、ユーザーがメイン カレンダーを削除したり、「オーナーを解除」したりすることはできません。ただし、他のユーザーと共有することは可能です。
メイン カレンダーに加えて、他のカレンダーをいくつでも明示的に作成できます。作成したカレンダーは、複数のユーザー間で変更、削除、共有できます。
カレンダーとカレンダー リスト
Calendars コレクションは既存のすべてのカレンダーを表します。カレンダーの作成や削除に使用できます。カレンダーにアクセスできるすべてのユーザーで共有されるグローバル プロパティを取得または設定することもできます。たとえば、カレンダーのタイトルとデフォルトのタイムゾーンはグローバル プロパティです。
CalendarList は、ユーザーがリストに追加したすべてのカレンダー エントリのコレクションです(ウェブ UI の左側のパネルに表示されます)。ユーザーリストに既存カレンダーを追加したり、リストから削除したりできます。また、デフォルトのリマインダーなど、ユーザー固有のカレンダー プロパティの値の取得と設定にも使用できます。別の例として、前景色です。同じカレンダーに異なる色を設定できるためです。
次の表は、2 つのコレクションのオペレーションの意味を比較したものです。
オペレーション | カレンダー | CalendarList |
---|---|---|
insert |
新しい予備カレンダーを作成します。デフォルトでは、このカレンダーは作成者のカレンダー リストにも追加されます。 | ユーザーのリストに既存のカレンダーを挿入します。 |
delete |
予備カレンダーを削除します。 | ユーザーのリストからカレンダーを削除します。 |
get |
カレンダーのメタデータ(タイトル、タイムゾーンなど)を取得します。 | メタデータとユーザー固有のカスタマイズ(色やオーバーライド リマインダーなど)を取得します。 |
patch /update |
カレンダーのメタデータを変更します。 | ユーザー固有のカレンダー プロパティを変更します。 |
定期的な予定
毎週のミーティング、誕生日、祝日など、一部のイベントは定期的に複数回発生します。開始時刻と終了時刻が異なることを除き、これらの繰り返しイベントは多くの場合同じです。
定義したスケジュールで繰り返されるイベントは、「繰り返し」と呼ばれます。単独のイベントは、繰り返し発生せず、1 回だけ発生します。
繰り返しルール
定期的な予定のスケジュールは、次の 2 つの部分で定義されます。
開始フィールドと終了フィールド(単独の単一のイベントであるかのように最初の発生を定義します)
繰り返しフィールド(時間の経過に伴うイベントの繰り返しの程度を定義します)。
recurrence フィールドには、RFC 5545 で定義されている 1 つまたは複数の RRULE
、RDATE
、または EXDATE
プロパティを表す文字列の配列を指定します。
RRULE
プロパティは、イベントを繰り返すための通常のルールを定義するため、最も重要なものです。これは複数のコンポーネントで構成されています。その一部を以下にご紹介します。
FREQ
- イベントの繰り返しの頻度(DAILY
、WEEKLY
など)。必須。INTERVAL
-FREQ
と連携して、イベントを繰り返す頻度を指定します。たとえば、FREQ=DAILY;INTERVAL=2
は 2 日に 1 回を意味します。COUNT
- このイベントを繰り返す回数。UNTIL
- イベントの繰り返す終了日時(指定した日時を含む)です。BYDAY
- イベントを繰り返す曜日(SU
、MO
、TU
など)。他の同様のコンポーネントには、BYMONTH
、BYYEARDAY
、BYHOUR
があります。
RDATE
プロパティは、イベントが発生する追加の日付または日時を指定します。(例: RDATE;VALUE=DATE:19970101,19970120
)。これを使用して、RRULE
でカバーされていないオカレンスを追加します。
EXDATE
プロパティは RDATE と似ていますが、イベントが発生しない日付または日時を指定します。つまり、そのようなオカレンスは除外する必要があります。これは、繰り返しルールによって生成された有効なインスタンスを指している必要があります。
EXDATE
と RDATE
にはタイムゾーンを含めることができ、終日の予定の場合は日付(日時以外)を指定する必要があります。
各プロパティは、繰り返しフィールドで複数回指定することができます。
繰り返しは、すべての RRULE
ルールと RDATE
ルールの合計から、すべての EXDATE
ルールによって除外されたルールを引いた値として定義されます。
繰り返しイベントの例を次に示します。
2015 年 9 月 15 日から毎週火曜日と金曜日の午前 6 時から午前 7 時まで発生し、9 月 29 日の 5 回目の発生後に停止するイベントの場合、次のようになります。
... "start": { "dateTime": "2015-09-15T06:00:00+02:00", "timeZone": "Europe/Zurich" }, "end": { "dateTime": "2015-09-15T07:00:00+02:00", "timeZone": "Europe/Zurich" }, "recurrence": [ "RRULE:FREQ=WEEKLY;COUNT=5;BYDAY=TU,FR" ], …
2015 年 6 月 1 日から 1 か月を通して 3 日ごとに繰り返す終日イベント(6 月 10 日を除く、6 月 9 日と 11 日を含む)。
... "start": { "date": "2015-06-01" }, "end": { "date": "2015-06-02" }, "recurrence": [ "EXDATE;VALUE=DATE:20150610", "RDATE;VALUE=DATE:20150609,20150611", "RRULE:FREQ=DAILY;UNTIL=20150628;INTERVAL=3" ], …
インスタンスと例外
定期的な予定は、異なる時刻に発生する特定のインスタンスで構成されます。これらのインスタンスはイベントそのものとして機能します。
定期的な予定の変更は、定期的な予定全体(とそのすべてのインスタンス)に影響するか、個々のインスタンスに影響する可能性があります。親の定期的なイベントとは異なるインスタンスは例外と呼ばれます。
たとえば、例外の概要、開始時間、そのインスタンスのみに招待された追加の参加者などを設定できます。定期的なイベントを削除せずにインスタンスを完全にキャンセルすることもできます(インスタンスのキャンセルはイベント status
に反映されます)。
Google Calendar API を使用して定期的な予定やインスタンスを操作する方法の例については、こちらをご覧ください。
タイムゾーン
タイムゾーンは、統一された標準時間に準拠するリージョンを指定します。Google Calendar API では、IANA タイムゾーン識別子を使用してタイムゾーンを指定します。
カレンダーと予定の両方にタイムゾーンを設定できます。以降のセクションでは、これらの設定の影響について説明します。
カレンダーのタイムゾーン
カレンダーのタイムゾーンは、クエリ結果に影響するため、デフォルトのタイムゾーンとも呼ばれます。カレンダーのタイムゾーンは、events.get()
、events.list()
、events.instances()
メソッドによる時刻値の解釈または提示方法に影響します。
- クエリ結果のタイムゾーン変換
get()
、list()
、instances()
メソッドの結果は、timeZone
パラメータで指定したタイムゾーンで返されます。このパラメータを省略すると、これらのメソッドはすべて、デフォルトとしてカレンダーのタイムゾーンを使用します。- 終日イベントを時間範囲で区切ったクエリと照合
list()
メソッドとinstances()
メソッドを使用すると、開始時刻と終了時刻のフィルタを指定できます。これらのメソッドにより、指定した範囲内のインスタンスが返されます。終日イベントの開始時刻と終了時刻が計算され、フィルタ仕様に該当するかどうかを判断する際に、カレンダーのタイムゾーンが使用されます。
予定のタイムゾーン
イベント インスタンスには開始時刻と終了時刻があります。これらの時間の仕様にはタイムゾーンを含めることができます。タイムゾーンはいくつかの方法で指定できます。どの方法でも同じ時刻を指定します。
dateTime
フィールドにタイムゾーン オフセット(2017-01-25T09:00:00-0500
など)を含めます。- オフセットなしで時間を指定します(例:
2017-01-25T09:00:00
)。timeZone
フィールドは空のままにしておきます(デフォルトのタイムゾーンが暗黙的に使用されます)。 - オフセットなしで時間を指定します(例:
2017-01-25T09:00:00
)。ただし、タイムゾーンを指定するにはtimeZone
フィールドを使用します。
必要に応じて、UTC でイベントの時刻を指定することもできます。
- 時刻を UTC(
2017-01-25T14:00:00Z
)で指定するか、ゼロ オフセット2017-01-25T14:00:00+0000
を使用します。
いずれの場合も、予定時刻の内部表現は同じですが、カレンダー UI を使用して予定のタイムゾーンを設定する場合と同様に、timeZone
フィールドを設定するとタイムゾーンが予定に追加されます。
定期的な予定のタイムゾーン
定期的な予定の場合は、常に 1 つのタイムゾーンを指定する必要があります。これはイベントの繰り返し回数を増やすために必要です。