本指南介绍了日历、活动以及它们之间的关系。
日历
日历是相关活动以及其他元数据(如摘要、默认时区、地点等)的集合。每个日历都由一个 ID(即电子邮件地址)进行标识。日历可以有多个所有者。
事件
事件是与特定日期或时间范围相关联的对象。事件由唯一 ID 进行标识。除了开始和结束日期时间之外,事件还包含其他数据,例如摘要、说明、地点、状态、提醒、附件等。
事件类型
Google 日历支持单次活动和周期性活动:
- 一个事件表示不重复的一次事件。
- recurring 事件定义了多次发生。
活动也可以为定时或全天:
- “定时”事件发生在两个特定时间点之间。计时事件使用
start.dateTime
和end.dateTime
字段来指定事件发生的时间。 - 全天活动会跨越一整天或连续的一系列日期。全天活动使用
start.date
和end.date
字段来指定活动时间。请注意,时区字段对于全天活动没有意义。
组织者
活动只有一个组织者,即包含活动主副本的日历。活动还可以有多个参加者。参加者通常是受邀用户的主日历。
下图显示了日历、活动和其他相关元素之间的概念关系:
主日历和其他日历
主日历是与单个用户帐号关联的特殊日历类型。系统会自动为每个新用户帐号创建此日历,其 ID 通常与用户的主电子邮件地址匹配。只要帐号存在,用户就永远不能删除其主日历或使其“失去所有权”。但是,您仍然可以与其他用户共享此文件。
除主日历之外,您还可以明确创建任意数量的其他日历;这些日历可以在多个用户之间修改、删除和共享。
日历和日历列表
Calendars 集合表示所有现有日历。它可用于创建和删除日历。您还可以检索或设置有权访问日历的所有用户共享的全局属性。例如,日历的标题和默认时区就是全局属性。
CalendarList 是一个集合,其中包含用户已添加到其列表的所有日历条目(如网页界面的左侧面板中所示)。您可以使用此日历向用户列表中添加和移除现有日历。您还可以使用它来检索和设置特定于用户的日历属性的值,例如默认提醒。另一个示例是前景颜色,因为不同的用户可以为同一日历设置不同的颜色。
下表比较了这两个集合的操作含义:
操作 | 日历 | 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 日开始的全天活动,在整个月(不包括 6 月 10 日,但包括 6 月 9 日和 11 日)每 3 天重复一次:
... "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 时区标识符指定时区。
您可以同时为日历和活动设置时区。以下部分介绍了这些设置的影响。
日历时区
日历的时区也称为默认时区,因为它会影响查询结果。日历时区会影响 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
字段会为事件附加时区,就像使用日历界面设置事件时区一样:
周期性活动的时区
对于周期性活动,必须始终指定单个时区。 需要扩展活动的重复周期。