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

日曆與活動；活動

本指南旨在說明日曆、活動及其之間的關係。

日曆

日曆是相關事件的集合，與其他中繼資料包括摘要、預設時區、位置等。每個日曆都透過一個電子郵件地址做為 ID 來識別。日曆可以有多位擁有者，

活動

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

事件類型

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

單一事件代表重複出現的情況。
「週期性」事件定義了多個重複事件。

事件也可能是計時或全天：

timed 事件會在兩個特定時間點之間發生。定時事件會使用 start.dateTime 和 end.dateTime 欄位指定這些事件的發生時間。
「全天」活動橫跨一整天或連續幾天。全天事件使用 start.date 和 end.date 欄位指定發生時間。請注意，時區欄位對全天活動沒有重要意義。

活動的開始和結束時間必須設為計時，或兩者皆為全天。例如，指定 start.date 和 end.dateTime 無效。

主辦人

事件只有一個「主辦人」，這是包含活動主要副本的日曆。事件也可以有多位參與者。參與者通常是受邀使用者的主要日曆。

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

主要日曆和其他日曆

「主要」日曆是與單一使用者帳戶相關聯的特殊日曆類型。系統會為每個新使用者帳戶自動建立這個日曆，而且日曆 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：應重複這個事件的次數。

您可以使用 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 日發生第 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 時區 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 欄位會為事件附加時區，就和使用 Google 日曆 UI 設定活動時區一樣：

週期性活動時區

如果是週期性活動，一律必須指定單一時區。需要可延長活動的重複週期。