日曆與活動；活動

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

日曆

日曆是一組相關活動，以及摘要、預設時區、地點等其他中繼資料。每個日曆都有一個 ID (電子郵件地址)。日曆可以有多位擁有者。

事件

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

事件類型

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

  • 單一事件代表不重複的發生次數。
  • 週期性活動會定義多個發生次數。

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

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

主辦人

活動只有一位主辦人，也就是包含活動主要副本的日曆。活動也可以有多位參與者。受邀使用者的主要日曆通常就是出席者。

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

主要日曆和其他日曆

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

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

日曆和日曆清單

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

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

下表比較這兩個集合的作業意義：

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

週期性活動

有些活動會定期重複發生，例如每週例會、生日和節慶。除了開始和結束時間不同，這些重複活動通常完全相同。

如果活動會按照排定的時間表重複舉行，則稱為週期性活動。 單一活動不會重複發生，只會進行一次。

重複規則

週期性活動的排程分為兩部分：

  • 開始和結束欄位 (定義第一次發生時間，如同這只是單一獨立活動)，以及

  • 週期性欄位 (定義活動在一段時間內的重複方式)。

遞迴欄位包含字串陣列，代表一或多個 RRULE、RDATE 或 EXDATE 屬性，如 RFC 5545 所定義。

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 規則排除的規則。

以下列舉幾個週期性活動的例子：

  1. 從 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"
],
…

  2. 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() 方法解讀或呈現時間值的方式。

查詢結果時區轉換
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 欄位指定時區。

您也可以視需要以世界標準時間指定活動時間：

  • 以世界標準時間指定時間：2017-01-25T14:00:00Z 或使用零時差 2017-01-25T14:00:00+0000。

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

螢幕截圖片段：顯示活動的時區

週期性活動時區

如果是週期性活動，則一律必須指定單一時區。 這是展開活動週期所必須的步驟。