このガイドでは、カレンダー、予定、それらの相互関係について説明します。
カレンダー
カレンダーは、関連するイベントと、概要、デフォルトのタイムゾーン、場所などの追加のメタデータのコレクションです。各カレンダーは、メールアドレスである ID で識別されます。カレンダーには複数のオーナーを設定できます。
イベント
イベントは、特定の日付または期間に関連付けられたオブジェクトです。イベントは一意の ID で識別されます。開始日時と終了日時のほかに、イベントには概要、説明、場所、ステータス、リマインダー、添付ファイルなどのデータが含まれます。
イベントの種類
Google カレンダーでは、1 件と繰り返しの予定がサポートされています。
- 単一のイベントは、一意の発生回数を表します。
- 定期的なイベントは、複数回発生するイベントを定義します。
予定に時間指定や終日を指定することもできます。
- 時間指定イベントは、2 つの特定の時点の間に発生します。時間指定イベントでは、
start.dateTime
フィールドとend.dateTime
フィールドを使用してタイミングを指定します。 - 終日の予定は、丸 1 日、または連続した日数にまたがります。終日の予定では、
start.date
フィールドとend.date
フィールドを使用して、いつ発生するかを指定します。タイムゾーン フィールドは終日の予定には関係ありません。
主催者
イベントには単一の主催者(イベントのメインコピーを含むカレンダー)が含まれます。イベントに複数の参加者を割り当てることもできます。参加者は通常、招待されたユーザーのメイン カレンダーです。
次の図は、カレンダー、イベント、その他の関連要素の概念的な関係を示しています。
メインのカレンダーとその他のカレンダー
プライマリ カレンダーは、単一のユーザー アカウントに関連付けられた特別なタイプのカレンダーです。このカレンダーは新しいユーザー アカウントごとに自動的に作成され、通常、その ID はユーザーのメインのメールアドレスと一致します。アカウントが存在している限り、そのメイン カレンダーをユーザーが削除したり、「オーナーがいない」状態になったりすることはできません。ただし、他のユーザーとの共有は引き続き可能です。
メイン カレンダー以外にも、任意の数のカレンダーを明示的に作成できます。これらのカレンダーは、変更、削除、複数のユーザー間での共有が可能です。
カレンダーとカレンダー リスト
Calendars コレクションは、既存のすべてのカレンダーを表します。カレンダーの作成と削除に使用できますまた、カレンダーにアクセスできるすべてのユーザー間で共有されるグローバル プロパティを取得または設定することもできます。たとえば、カレンダーのタイトルとデフォルトのタイムゾーンはグローバル プロパティです。
CalendarList は、ユーザーがリストに追加したすべてのカレンダー エントリのコレクションです(ウェブ UI の左側のパネルに表示されます)。既存のカレンダーをリストに追加したり リストから削除したりできますまた、デフォルトのリマインダーなど、ユーザー固有のカレンダー プロパティの値の取得と設定にも使用します。別の例としては前景色があります。これは、ユーザーごとに同じカレンダーに異なる色を設定できるためです。
次の表は、2 つのコレクションのオペレーションの意味を比較したものです。
オペレーション | カレンダー | CalendarList |
---|---|---|
insert |
新しい予備カレンダーを作成します。デフォルトでは、このカレンダーは作成者のカレンダー リストにも追加されます。 | 既存のカレンダーをユーザーのリストに挿入します。 |
delete |
予備カレンダーを削除します。 | ユーザーのリストからカレンダーを削除します。 |
get |
カレンダーのメタデータ(タイトル、タイムゾーンなど)を取得します。 | メタデータに加えて、色やオーバーライド リマインダーなどのユーザー固有のカスタマイズを取得します。 |
patch /update |
カレンダーのメタデータを変更します。 | ユーザー固有のカレンダー プロパティを変更します。 |
定期的な予定
毎週の会議、誕生日、祝日など、イベントの中には、定期的なスケジュールで複数回発生するものがあります。多くの場合、これらの繰り返しイベントは開始時刻と終了時刻が異なることを除けば同一になります。
定義されたスケジュールに従って繰り返されるイベントは、繰り返しと呼ばれます。 単一イベントは定期的なものではなく、1 回のみ発生します。
繰り返しルール
定期的な予定のスケジュールは、次の 2 つの部分で定義されます。
開始フィールドと終了フィールド(スタンドアロンの単一イベントのように最初の発生を定義)
繰り返しフィールド(時間の経過とともにイベントを繰り返す方法を定義します)。
繰り返しフィールドには、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 日から 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
フィールドを設定すると予定にタイムゾーンが関連付けられます。
定期的な予定のタイムゾーン
定期的な予定の場合は、常に単一のタイムゾーンを指定する必要があります。 これは、その予定の繰り返しを増やすために必要です。