本頁面由 Cloud Translation API 翻譯而成。

日曆與活動；活動

本指南說明日曆、活動，以及彼此之間的關係。

日曆

日曆是相關活動的集合，以及摘要、預設時區、位置等其他中繼資料。每個日曆都會以電子郵件地址做為 ID 進行識別。日曆可以有多位擁有者。

活動

事件是與特定日期或時間範圍相關聯的物件。事件會透過專屬 ID 識別。除了開始和結束日期/時間，活動還包含其他資料，例如摘要、說明、地點、狀態、提醒、附件等。

事件類型

Google 日曆支援單一和週期性活動：

單一事件代表獨特事件。
週期性事件定義多次發生的事件。

活動也可以是指定時間或全天：

定時事件會在兩個特定時間點之間發生。時間限制事件會使用 start.dateTime 和 end.dateTime 欄位指定發生時間。
全天活動會持續一整天或連續多天。全天事件會使用 start.date 和 end.date 欄位指定發生時間。請注意，時區欄位對全天活動沒有任何意義。

活動的開始和結束時間都必須有時間限制，或都設為全天。舉例來說，指定 start.date 和 end.dateTime 無效。

主辦人

每個活動都有一個主辦人，也就是含有活動主要副本的日曆。活動也可以有多位與會者。與會者通常是受邀使用者的主日曆。

下圖顯示日曆、活動和其他相關元素之間的概念關係：

主要日曆和其他日曆

主要日曆是一種特殊類型的日曆，與單一使用者帳戶相關聯。系統會為每個新使用者帳戶自動建立這個日曆，其 ID 通常會與使用者的主要電子郵件地址相符。只要帳戶存在，使用者就無法刪除或「取消擁有」主要日曆。但仍可與其他使用者共用。

除了主要日曆外，您可以明確建立任意數量的其他日曆，這些日曆可供多位使用者修改、刪除及共用。

日曆和日曆清單

日曆集合代表所有現有日曆。可用於建立及刪除日曆。您也可以擷取或設定所有日曆存取權使用者共用的全域屬性。舉例來說，日曆的標題和預設時區都是全域屬性。

CalendarList 是使用者新增至清單的所有日曆項目集合 (顯示在網頁 UI 的左側面板)。您可以使用這個 API 新增或移除使用者清單中的現有日曆。您也可以使用這個 API 擷取及設定使用者專屬日曆屬性的值，例如預設提醒。另一個例子是前景色彩，因為不同使用者可為相同日曆設定不同的顏色。

下表比較兩個集合的運算意義：

作業	日曆	CalendarList
`insert`	建立新的次要日曆。根據預設，這個日曆也會新增至創作者的日曆清單。	將現有日曆插入使用者清單。
`delete`	刪除次要日曆。	從使用者清單中移除日曆。
`get`	擷取日曆中繼資料，例如名稱、時區。	擷取中繼資料和使用者專屬的客製化設定，例如顏色或覆寫提醒。
`patch`/`update`	修改日曆中繼資料。	修改使用者專屬的日曆屬性。

週期性活動

有些活動會依照固定時間表重複發生，例如每週會議、生日和假日。除了開始和結束時間不同，這些重複事件通常都會相同。

如果事件會依照指定的時間表重複發生，就稱為「週期性」。單一事件不會重複發生，只會發生一次。

重複規則

週期性活動的時間表由兩個部分定義：

其開始和結束欄位 (定義首次發生事件，就好像這是單一事件一樣)，以及
週期欄位 (定義事件重複發生的時間間隔)。

週期欄位包含字串陣列，代表 RFC 5545 中定義的一或多個 RRULE、RDATE 或 EXDATE 屬性。

RRULE 屬性最為重要，因為它定義了重複事件的規則。由多個元件組成。其中包括：

FREQ：事件的重複頻率 (例如 DAILY 或 WEEKLY)。必填。
INTERVAL：與 FREQ 搭配使用，用於指定事件的重複頻率。例如 FREQ=DAILY;INTERVAL=2 表示每兩天一次。
COUNT：重複執行此事件的次數。

您可以使用 COUNT 或 UNTIL 指定事件週期結束時間。請勿在同一個規則中同時使用這兩種設定。
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 日開始，每隔 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 日曆 API 處理週期性活動和例項的範例，請參閱這篇文章。

時區

時區可指定遵循統一標準時間的區域。在 Google 日曆 API 中，您可以使用 IANA 時區 ID 指定時區。

您可以為日曆和活動設定時區。下列各節將說明這些設定的效果。

日曆時區

日曆的時區也稱為預設時區，因為它會影響查詢結果。日曆時區會影響 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) 指定時間：2017-01-25T14:00:00Z 或使用零偏移 2017-01-25T14:00:00+0000。

在所有這些情況下，事件時間的內部表示法都相同，但設定 timeZone 欄位會將時區附加至事件，就像使用日曆 UI 設定事件時區一樣：

週期性活動時區

對於週期性活動，您必須一律指定單一時區。這項資訊是用來擴充事件的週期。