日曆與活動；活動

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

日曆

日曆 是一組相關事件，以及其他中繼資料 例如摘要、預設時區和位置等等 由電子郵件地址或電子郵件地址所組成日曆可以有多位擁有者，

活動

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

事件類型

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

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

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

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

主辦人

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

下圖顯示了 事件及其他相關元素：

主要日曆和其他日曆

主要日曆是與單一使用者相關聯的特殊日曆類型 使用者帳戶。系統會自動為每個新的使用者帳戶建立這個日曆 且 ID 通常會與使用者的主要電子郵件地址相符。只要 帳戶仍存在，日曆的主要日曆即無法刪除或「沒有擁有者」由 內容。不過，這些資料仍可與其他使用者共用。

除了主要日曆外，您還可以明確建立 其他日曆；可以修改、刪除及共用這些日曆 可讓多位使用者

日曆與日曆清單

日曆集合 代表所有現有的日曆。可用於建立及刪除 日曆。您也可以擷取或設定跨所有資源共用的全域屬性 也就是能存取日曆的使用者例如日曆的標題和預設值 時區是全域屬性

CalendarList 是 使用者新增至清單的所有日曆項目集合 (系統會顯示 。你可以使用這個選項 新增/來自使用者清單中的日曆。您也可以用它來擷取及設定 使用者專屬日曆屬性的值，例如預設提醒。其他 例子就是前景顏色，因為不同使用者能使用不同顏色 以同一個日曆資源為準

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

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

週期性活動

有些活動會定期定期舉行，例如每週會議。 生日和假日。除了開始和結束時間不同 這些重複事件通常完全相同

如果活動依照預定時間表重複，就稱為「週期性」。 單一事件並非週期性，且只會發生一次。

重複規則

週期性活動的時間表分為兩個部分：

• 這是開始和結束欄位 (用於定義第一次出現的位置，就像 只是獨立的單一活動)，而

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

週期欄位包含代表一或多個字串的字串陣列 RFC 中定義的 RRULE、RDATE 或 EXDATE 屬性 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. 活動開始時間為每週二和週五上午 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"
   ],
   …
   

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 欄位會為事件附加時區，就像 使用 Google 日曆設定活動時區時 使用者介面：

週期性活動時區

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