日曆與活動;活動

本指南說明日曆、活動,以及彼此之間的關係。

日曆

日曆是相關事件的集合,與其他中繼資料包括摘要、預設時區、位置等。每個日曆都透過一個電子郵件地址做為 ID 來識別。日曆可以有多位擁有者。

活動

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

事件類型

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

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

活動也可以是指定時間全天

  • timed 事件會在兩個特定時間點之間發生。計時事件會使用 start.dateTimeend.dateTime 欄位指定發生時間。
  • 全天活動會持續一整天或連續多天。全天事件會使用 start.dateend.date 欄位指定發生時間。請注意,時區欄位對全天活動沒有任何意義。

主辦人

事件只有一個「主辦人」,這是包含活動主要副本的日曆。活動也可以有與會者。參與者通常是受邀使用者的主要日曆。

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

主要日曆和其他日曆

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

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

日曆和日曆清單

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

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

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

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

週期性活動

有些活動會依照固定時間表重複發生,例如每週會議、生日和假日。除了開始和結束時間不同,這些重複事件通常都會相同。

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

重複規則

週期性活動的時間表由兩個部分定義:

  • 其開始和結束欄位 (定義首次發生的事件,就好像這是單一事件一樣),以及

  • 週期欄位 (定義事件重複發生的時間間隔)。

週期欄位包含字串陣列,代表 RFC 5545 中定義的一或多個 RRULERDATEEXDATE 屬性。

RRULE 屬性最為重要,因為它定義了重複事件的規則。由多個元件組成。其中包括:

  • FREQ:應重複事件的頻率 (例如 DAILYWEEKLY)。這是必要欄位。

  • INTERVAL:與 FREQ 搭配使用,用於指定事件的重複頻率。例如,FREQ=DAILY;INTERVAL=2 表示每兩天一次。

  • COUNT:應重複這個事件的次數。

  • UNTIL:活動應重複的日期或日期/時間 (包含)。

  • BYDAY:事件重複發生的星期幾 (SUMOTU 等)。其他類似元件包括 BYMONTHBYYEARDAYBYHOUR

RDATE 屬性可指定事件發生的其他日期或日期/時間。例如:RDATE;VALUE=DATE:19970101,19970120。可用於新增 RRULE 未涵蓋的額外事件。

EXDATE 屬性與 RDATE 相似,但會指定事件「不應」發生的日期或日期/時間。也就是說,應該排除這些例項。必須指向重複規則產生的有效執行個體。

EXDATERDATE 可以有時區,且必須是日期 (而非日期和時間),才能用於全天活動。

每項屬性都可能會重複發生在週期欄位內。重複事件的定義是所有 RRULERDATE 規則的聯集,減去所有 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 日曆 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 設定事件時區一樣:

顯示事件時區的螢幕截圖片段

週期性活動時區

對於週期性活動,您必須一律指定單一時區。這項資訊是用來擴充事件的週期。