日曆與活動;活動

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

日曆

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

活動

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

事件類型

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

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

事件也可能是計時全天

  • timed 事件會在兩個特定時間點之間發生。計時事件 請使用 start.dateTimeend.dateTime 欄位指定 。
  • 「全天」活動橫跨一整天或連續幾天。整日 事件會使用 start.dateend.date 欄位指定發生時間。 請注意,時區欄位對全天活動沒有重要意義。
,瞭解如何調查及移除這項存取權。

主辦人

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

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

主要日曆和其他日曆

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

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

日曆與日曆清單

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

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

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

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

週期性活動

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

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

重複規則

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

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

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

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

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. 活動開始時間為每週二和週五上午 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 日曆設定活動時區時 使用者介面

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

週期性活動時區

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