日历和活动

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

本指南将介绍日历、活动以及相互之间的关系。

日历

日历是相关活动的集合以及其他元数据,例如摘要、默认时区和位置等。每个日历都通过一个电子邮件地址(即电子邮件地址)来标识。日历可以有多个所有者。

活动

“事件”是指与特定日期或时间范围关联的对象。事件通过唯一 ID 进行标识。除了开始和结束日期时间之外,事件还包含其他数据,例如摘要、说明、位置、状态、提醒、附件等。

事件类型

Google 日历支持单一周期性活动:

  • 单个事件表示唯一身份发生实例。
  • 周期性事件定义了多次。

活动也可以设置为定时全天

  • “定时”事件发生在两个特定时间点之间。定时事件使用 start.dateTimeend.dateTime 字段来指定何时发生。
  • 全天活动持续一整天或连续的几天。全天事件使用 start.dateend.date 字段指定发生时间。请注意,时区字段对全天事件没有任何意义。

组织者

活动有一个“组织者”,该日历是包含活动主副本的日历。活动还可以有多个参加者。参加者通常是受邀用户的主日历。

下图显示了日历、活动和其他相关元素之间的概念关系:

主日历和其他日历

主日历是一种与单个用户帐号相关联的特殊日历。此日历是为每个新用户帐号自动创建的,其 ID 通常与用户的主电子邮件地址一致。只要该帐号存在,用户就无法删除其主日历或使其“不拥有”。但仍然可以与其他用户共享。

除了主日历,您还可以明确创建任意数量的其他日历;这些日历可以被修改、删除和在多个用户之间共享。

日历和日历列表

日历集合代表所有现有日历。它可用于创建和删除日历。您还可以检索或设置有权访问日历的所有用户共享的全局属性。例如,日历标题和默认时区是全局属性。

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 点发生的事件,第 5 次发生于 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 中)。

如需了解如何通过 Calendar API 处理周期性活动和实例,请点击此处

时区

时区用于指定遵循统一标准时间的区域。在 Calendar API 中,您可以使用 IANA 时区标识符指定时区。

您可以为日历和活动设置时区。以下部分介绍了这些设置的效果。

日历时区

日历的时区也称为默认时区,因为它会影响查询结果。日历时区会影响 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 字段指定时区。

如果您愿意,也可以按世界协调时间 (UTC) 指定事件时间:

  • 以世界协调时间 (UTC) 指定时间:2017-01-25T14:00:00Z 或使用零偏移 2017-01-25T14:00:00+0000

在这些情况下,事件时间的内部表示形式是相同的,但设置 timeZone 字段会将时区附加到活动上,就像使用日历界面设置活动时区时一样:

显示活动时区的屏幕截图屏幕截图

周期性活动的时区

对于周期性活动,必须始终指定单个时区。 必须这样做才能延长活动周期。