本指南將說明日曆、活動及兩者之間的關係。
日曆
日曆是一組相關事件和其他中繼資料,例如摘要、預設時區、位置等。每個日曆都有一個 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 設定活動時區時一樣:
週期性活動時區
如果是週期性活動,則一律必須指定單一時區。 必須有這個權限才能延展後續活動。