本指南說明日曆、活動,以及彼此之間的關係。
日曆
日曆是相關事件的集合,與其他中繼資料包括摘要、預設時區、位置等。每個日曆都透過一個電子郵件地址做為 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 日開始,每隔 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 日曆 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 設定事件時區一樣:
週期性活動時區
對於週期性活動,您必須一律指定單一時區。這項資訊是用來擴充事件的週期。