本指南介绍了日历、活动及其相互关系。
日历
日历 是一组相关活动，以及其他元数据（ 例如摘要、默认时区、地点等）。每个日历都有一个 ID（即电子邮件地址）。日历可以与他人共享。 主日历归其关联的用户账号所有，其他日历归单个数据所有者所有。
活动
活动是与特定日期或时间范围关联的对象。活动通过唯一 ID 标识。除了开始和结束日期时间之外，活动还包含其他数据，例如摘要、说明、地点、状态、提醒、附件等。
活动类型
Google 日历支持单次活动和周期性活动：
- 单次活动表示一次性事件。
- 周期性活动定义了多次事件。
活动还可以是定时活动或全天活动：
- 定时活动发生在两个特定时间点之间。 定时活动使用
start.dateTime和end.dateTime字段来指定发生时间。 - 全天活动持续一整天或连续几天。 全天活动使用
start.date和end.date字段来指定发生时间。 请注意，时区字段对于全天活动没有意义。
组织者
活动有一个组织者，即包含活动主要副本的日历。 活动还可以有多个 参加者。 参加者通常是受邀用户的主日历。
下图显示了日历、活动和其他相关元素之间的概念关系：
主日历和其他日历
主日历是一种与单个用户账号关联的特殊日历。 系统会自动为每个新用户账号创建此日历，其 ID 通常与用户的主邮箱地址一致。只要账号存在，用户就永远无法删除或“取消拥有”其主日历。不过，用户仍然可以与其他用户共享该日历。
除了主日历之外，您还可以明确创建任意数量的其他日历。您可以修改、删除这些日历，并与他人共享。此类日历只有一个数据所有者，该所有者拥有最高权限，包括删除日历的专属权利。数据所有者的访问权限级别无法降级。数据所有者最初被确定为创建日历的用户，但可以在 Google 日历界面中转移数据所有权。
日历和日历列表
Calendars 集合 表示所有现有日历。您可以使用它来创建和删除日历。您还可以检索或设置与有权访问日历的所有用户共享的全局属性。例如，日历的标题和默认时区是全局属性。
CalendarList 是用户添加到其列表（显示 在网页界面的左侧面板中）的所有日历条目的 集合。您可以使用它来向用户的列表添加和从中移除现有日历。您还可以使用它来检索和设置用户专属日历属性的值，例如默认提醒。另一个示例是前景色，因为不同的用户可以为同一日历设置不同的颜色。
下表比较了这两个集合的操作含义：
| 操作 | Calendars | CalendarList |
|---|---|---|
insert |
创建新的辅助日历。此日历也会添加到 创建者的日历列表中，并且无法移除，除非日历被 删除或转移。 | 将现有日历插入用户的列表。 |
delete |
删除辅助日历。 | 从用户的列表中移除日历。 |
get |
检索日历元数据，例如标题、时区。 | 检索元数据以及 用户专属自定义设置 例如颜色或替换提醒。 |
patch/update |
修改日历元数据。 | 修改用户专属日历属性。 |
周期性活动
有些活动会定期多次发生，例如每周会议、生日和节假日。除了开始和结束时间不同之外，这些重复活动通常是相同的。
如果活动按照定义的日程安排重复发生，则称为周期性活动。 单次活动是非周期性的，只会发生一次。
重复规则
周期性活动的日程安排分为两部分：
开始和结束字段（用于定义首次发生，就像这只是一个独立的单次活动一样），以及
重复字段（用于定义活动应如何随时间重复）。
重复字段包含一个字符串数组，表示
RRULE、RDATE 或 EXDATE 属性，如 RFC
5545 中所定义。
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 日历 API 中，您可以使用 IANA 时区标识符指定时区。
您可以为日历和活动设置时区。以下部分介绍了这些设置的效果。
日历时区
日历的时区也称为默认时区， 因为它对查询结果有影响。日历时区会影响
时间值被
events.get()、
events.list()和
events.instances()方法解释或呈现的方式。
- 查询结果时区转换
- `get()`、`list()` 和 `instances()` 方法的结果以您在
timeZone参数中指定的时区返回。 - 将全天活动与带时间范围的查询匹配
- The
list()和instances()方法可让您指定开始时间和结束时间过滤器，该方法会 返回指定范围内的实例。日历时区用于计算全天活动的开始时间和结束时间，以确定它们是否符合过滤条件规范。
get()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 字段会将时区附加到活动，就像
您使用日历
界面设置活动时区一样：
周期性活动时区
对于周期性活动，必须始终指定单个时区。 这是展开活动重复所必需的。