本指南將說明日曆、活動及兩者之間的關係。
日曆
日曆是一組相關事件和其他中繼資料，例如摘要、預設時區、位置等。每個日曆都有一個 ID 做為識別 ID。一個日曆可以有多位擁有者。
活動
事件是與特定日期或時間範圍相關聯的物件。事件會以專屬 ID 識別。除了開始和結束日期之外，事件還包含摘要、說明、位置、狀態、提醒、附件等其他資料。
事件類型
Google 日曆支援單一和週期性活動：
- 單一事件代表不重複的發生。
- 「週期性」事件可定義多個發生次數。
事件也可以是計時模式或全天：
- 「timed」事件會在兩個特定時間點之間發生。計時事件會使用
start.dateTime和end.dateTime欄位指定發生時間。 - 「全天」活動橫跨一整天或連續幾天。全天事件使用
start.date和end.date欄位指定發生時間。請注意，時區欄位對全天活動沒有任何意義。
主辦人
事件有單一「主辦人」，其中包含活動主要副本的日曆。事件也可以有多位參與者。與會者通常是受邀使用者的主要日曆。
下圖顯示日曆、活動和其他相關元素的概念關係：
主日曆和其他日曆
「主要日曆」是與單一使用者帳戶相關聯的特殊日曆類型。系統會自動為每個新使用者帳戶建立這個日曆，其 ID 通常與使用者的主要電子郵件地址相符。只要帳戶存在，使用者就無法刪除或「未擁有」其主要日曆。不過，您仍可與其他使用者共用該檔案。
除了主日曆外，您也可以明確建立任意數量的其他日曆；這些日曆可以修改、刪除，以及與多位使用者共用。
日曆和日曆清單
「日曆」集合代表所有現有的日曆。還可用於建立及刪除日曆。您也可以擷取或設定所有具有日曆存取權的使用者共用的全域屬性。例如，日曆的標題和預設時區都是全域屬性。
CalendarList是使用者新增至清單的所有日曆項目集合 (顯示在網頁版 UI 的左側面板中)。您可以在使用者清單中新增及移除現有日曆。您也可以利用這個 API 擷取及設定使用者特定日曆屬性 (例如預設提醒) 的值。另一個例子是前景顏色，因為不同使用者可能會在同一個日曆上設定不同的顏色。
下表比較兩個集合的作業意義：
| 作業 | 日曆 | CalendarList |
|---|---|---|
insert |
建立新的次要日曆。根據預設，這個日曆也會加入建立者的日曆清單。 | 將現有日曆插入使用者的清單。 |
delete |
刪除次要日曆。 | 從使用者的清單中移除日曆。 |
get |
擷取日曆中繼資料，例如標題、時區。 | 擷取中繼資料「加上」使用者專屬的自訂項目，例如顏色或覆寫提醒。 |
patch/update |
修改日曆中繼資料。 | 修改使用者專屬的日曆屬性。 |
週期性活動
有些事件會按照固定時間表多次出現，例如每週會議、生日和假日。除了開始和結束時間不同之外，這些重複事件通常完全相同。
如果事件根據預定時間表重複重複，則稱為「週期性」。單一事件則為非週期性事件，而且只會發生一次。
重複規則
週期性活動的時間表分為兩個部分：
此物件包含開始和結束欄位 (定義第一次出現的情況，如同這只是一個獨立事件一樣)。
週期欄位 (用來定義事件的重複方式)。
週期欄位包含字串陣列，代表 RFC 5545 中定義的一或多個 RRULE、RDATE 或 EXDATE 屬性。
RRULE 屬性最重要，因為其定義了重複事件的一般規則。其中包含數個元件。包括：
FREQ：事件重複的頻率 (例如DAILY或WEEKLY)。必填。INTERVAL- 可與FREQ搭配使用，指定事件重複的頻率。例如，FREQ=DAILY;INTERVAL=2表示每兩天一次。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 日第五次發生後停止：
... "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 日開始的全天活動 (不含 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 時區 ID 指定時區。
您可以為日曆和活動設定時區。以下各節將說明這些設定的影響。
日曆時區
由於日曆時區會影響查詢結果，因此也稱為「預設時區」，日曆時區會影響 events.get()、events.list() 和 events.instances() 方法解讀或呈現時間值的方式。
- 查詢結果時區轉換
- 系統會按照您在
timeZone參數中指定的時區傳回get()、list()和instances()方法的結果。如果您省略此參數，這些方法全都會使用日曆時區做為預設值。 - 將全天事件與有時間的包圍查詢進行比對
list()和instances()方法可讓您指定開始和結束時間篩選器，此方法會傳回位於指定範圍內的執行個體。日曆時區用於計算全天事件的開始和結束時間，以判斷這些事件是否屬於篩選規格。
活動時區
事件執行個體有開始和結束時間；這些時間的規格可能會包含時區。您可以透過多種方式指定時區；以下所有項目都指定相同的時間：
- 在
dateTime欄位中加入時區偏移，例如2017-01-25T09:00:00-0500。 - 指定沒有偏移值的時間，例如
2017-01-25T09:00:00，將timeZone欄位留白 (默示使用預設時區)。 - 指定沒有偏移值的時間 (例如
2017-01-25T09:00:00)，但請使用timeZone欄位指定時區。
你也可以依照下列方式指定活動時間 (以世界標準時間為準)：
- 指定時間 (世界標準時間)：
2017-01-25T14:00:00Z，或使用零偏移2017-01-25T14:00:00+0000。
在以下情況下，活動時間的內部表示法都是相同的，但設定 timeZone 欄位會將時區附加至活動，就像使用日曆 UI 設定活動時區時一樣：
週期性活動時區
如果是週期性活動，則一律必須指定單一時區。 必須有這個權限才能延展後續活動。