本指南旨在說明日曆、活動及其之間的關係。
日曆
日曆是相關事件的集合,與其他中繼資料包括摘要、預設時區、位置等。每個日曆都透過一個電子郵件地址做為 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 日發生第 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 設定活動時區一樣:
週期性活動時區
如果是週期性活動,一律必須指定單一時區。需要可延長活動的重複週期。