事件类型

本页面介绍了 eventType 属性，以及 Google 日历 API 中提供的事件类型的规范。

Google 日历允许用户创建通用事件，以及专为特定用例设计且具有自定义属性的事件。

您可以在 API 中的以下位置发现事件类型：

所有事件都会返回 eventType。
eventType 创建或更新事件资源时，需要设置。如果未设置，系统将使用 'default' 类型。
eventTypes 可以在 Events:list 调用中指定，以列出特定类型的事件。如果未指定任何类型，系统将返回所有事件类型。
eventTypes 可以在 Events:watch 调用中指定，以订阅特定类型事件的更新。如果未指定任何类型，该请求将导致订阅所有事件类型。

默认事件

具有 default 事件类型的事件是作为 Google 日历 API 的主要资源之一创建和使用的。它们支持各种属性，可用于进一步自定义事件。

如需开始使用 Google 日历事件，请参阅创建事件。

生日

生日是特殊的整天活动，每年重复一次。

用户可以在 Google 日历上手动创建生日活动。此外，当用户添加人员并在 Google 通讯录中添加其生日和其他重要日期时，生日信息会与 Google 日历同步。用户自己的生日也会从其 Google 账号个人资料同步到 Google 日历。

Google 日历 API 支持使用 get、 instances 和 list 方法读取生日活动。eventTypes 可以设置为 'birthday'，以仅列出生日活动。如果未指定任何类型，生日将与其他所有事件类型一起列出。

在返回的 Event 对象中，检查 birthdayProperties 字段，详细了解此特殊事件。birthdayProperties 具有以下字段：

type：此特殊事件的类型，是生日、周年纪念日还是其他重要日期。
customTypeName：用户为此特殊事件指定的标签。如果 type 设置为 'custom'，系统会填充此字段。
contact：此特殊事件所关联的联系人的资源名称（如果有）。此字段的格式为 'people/c12345'，可用于从 People API 中提取联系人详细信息。

借助 API，您可以使用 insert 方法创建生日活动，并遵循以下规范：

eventType 设置为 'birthday'。
start 和 end 字段需要定义一个持续时间正好为一天的全天活动。
visibility 字段值必须为 'private'。
transparency 字段值必须为 'transparent'。
需要每年重复一次，这意味着 recurrence字段必须为 'RRULE:FREQ=YEARLY'。在 2 月 29 日的生日活动必须具有以下重复规则： 'RRULE:FREQ=YEARLY;BYMONTH=2;BYMONTHDAY=-1'。
可以具有 colorId、 summary 和 reminders。
可以具有 birthdayProperties。如果指定了 type，则必须为 'birthday'，并且 customTypeName 和 contact 都必须为空。
不能具有任何其他事件属性。

借助 API，您可以使用 update 和 patch 方法更新生日活动的 colorId、 summary 和 reminders。 start 和 end 字段也可以更新来更改活动日期。在这种情况下，新值需要定义一个持续时间正好为一天的全天活动。如果生日活动与 contact相关联，或者其 type 为 'self'，则无法更新生日活动的计时详细信息。

Google 日历 API 不允许创建具有自定义 birthdayProperties的生日活动，也不允许更新这些属性。您可以使用 People API修改重要日期，所做的更改会与 Google 日历同步。同样，用户可以在其 Google 账号个人资料中修改自己的生日，并且该生日会与 Google 日历同步。

尝试以不受支持的方式创建或更新生日的请求将会失败。在这种情况下，请检查错误消息以找出问题。

API 支持对生日活动执行 import 操作；不过，该活动将作为默认活动导入。换句话说，eventType 将为 'default'。

API 支持使用 watch 方法订阅 Google 日历中生日活动的更改。 eventTypes 可以设置为 'birthday'，以订阅生日活动的更新。如果未指定任何类型，系统将订阅所有事件类型，包括生日。

您可以使用 Google Calendar API 的 delete方法删除生日活动。从 Google 日历中删除生日活动不会影响Google 通讯录或 Google 账号个人资料中的数据。

不支持使用 move或 update方法更改生日活动的主办方。

来自 Gmail 的活动

从 Gmail 自动生成的活动具有 'fromGmail' 事件类型。

Google Calendar API 不允许使用 insert 方法创建此事件类型。

借助 API，您可以使用update 和patch方法更新 colorId、 reminders、 visibility、 transparency、 status、 attendees、 private 和shared 扩展属性。

API 支持使用 get 和 list 方法读取来自 Gmail 的活动。eventTypes 可以设置为 'fromGmail'，以仅列出从 Gmail 生成的活动。如果未指定任何类型，来自 Gmail 的活动将与其他所有事件类型一起列出。

API 支持使用 watch 方法订阅 Google 日历中来自 Gmail 的活动的更改。如果未指定任何类型，系统将订阅所有事件类型，包括'fromGmail'。

您可以使用 delete方法删除来自 Gmail 的活动，该方法属于 Google 日历 API。

不支持使用 move 或 update 方法更改来自 Gmail 的活动的主办方。

专注时间、不在办公室和工作地点

Google Calendar API 可用于创建和管理显示 Google 日历用户状态的活动。

这些功能仅在主日历上可用，并且仅适用于部分 Google 日历用户。如需了解详情，请参阅管理专注时间、不在办公室和工作地点活动。

探索 Google Apps 脚本中的事件类型

Google Apps 脚本是一种基于 JavaScript 的云端脚本语言，可让您构建与 Google Workspace 集成的商务应用。脚本在基于浏览器的代码编辑器中开发，并存储在 Google 的服务器上并在其上运行。另请参阅 Google Apps 脚本快速入门，了解如何开始使用 Apps 脚本向 Google 日历 API 发送请求。

以下说明介绍了如何在 Google Apps 脚本中使用 Google Calendar API作为高级服务来读取和管理事件。如需查看 Google 日历 API 资源和方法的完整列表，请参阅参考文档。

创建和设置脚本

前往 script.google.com/create创建脚本。
在左侧窗格中，点击服务旁边的“添加服务”图标。
选择 Google Calendar API ，然后点击添加。
启用后，API 会显示在左侧窗格中。您可以使用编辑器中的 Calendar 关键字列出 API 中的可用方法和类。

（可选）更新 Google Cloud 项目

每个 Google Apps 脚本项目都有一个关联的 Google Cloud 项目。您的脚本可以使用 Google Apps 脚本自动创建的默认项目。如果您想使用自定义 Google Cloud 项目，请参阅切换到其他标准云项目。设置 Google Cloud 云项目后，选择左侧的Editor ，以返回到代码编辑器。

向脚本添加代码

以下代码示例展示了如何使用不同的 eventType 值列出、读取和创建事件。

将以下内容粘贴到代码编辑器中。

const CALENDAR_ID = 'CALENDAR_ID' || 'primary';

/** Lists default events. */
function listDefaultEvents() {
  listEvents('default');
}

/** Lists birthday events. */
function listBirthdays() {
  listEvents('birthday');
}

/** Lists events from Gmail. */
function listEventsFromGmail() {
  listEvents('fromGmail');
}

/**
  * Lists events with the given event type. If no type is specified, lists all events.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events/list
  */
function listEvents(eventType = undefined) {
  // Query parameters for the list request.
  const optionalArgs = {
    eventTypes: eventType ? [eventType] : undefined,
    singleEvents: true,
    timeMax: '2024-07-30T00:00:00+01:00',
    timeMin: '2024-07-29T00:00:00+01:00',
  }
  try {
    var response = Calendar.Events.list(CALENDAR_ID, optionalArgs);
    response.items.forEach(event => console.log(event));
  } catch (exception) {
    console.log(exception.message);
  }
}

/**
  * Reads the event with the given eventId.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events/get
  */
function readEvent() {
  try {
    var response = Calendar.Events.get(CALENDAR_ID, 'EVENT_ID');
    console.log(response);
  } catch (exception) {
    console.log(exception.message);
  }
}

/** Creates a default event. */
function createDefaultEvent() {
  const event = {
    start: { dateTime: '2024-07-30T10:30:00+01:00'},
    end: { dateTime: '2024-07-30T12:30:00+01:00'},
    description: 'Created from Apps Script.',
    eventType: 'default',
    summary: 'Sample event',
  }
  createEvent(event);
}

/** Creates a birthday event. */
function createBirthday() {
  const event = {
    start: { date: '2024-01-29' },
    end: { date: '2024-01-30' },
    eventType: 'birthday',
    recurrence: ["RRULE:FREQ=YEARLY"],
    summary: "My friend's birthday",
    transparency: "transparent",
    visibility: "private",
  }
  createEvent(event);
}

/**
  * Creates a Calendar event.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events/insert
  */
function createEvent(event) {

  try {
    var response = Calendar.Events.insert(event, CALENDAR_ID);
    console.log(response);
  } catch (exception) {
    console.log(exception.message);
  }
}

替换以下内容：

CALENDAR_ID：用于检索和创建事件的日历的电子邮件地址。此常量最初设置为 'primary'，这是一个用于访问已登录用户的主日历的关键字。更改此值可让您读取您有权访问的其他用户的日历中的事件。
EVENT_ID：事件的 ID。您可以调用 Events:list 来检索事件 ID。

运行代码示例

在代码编辑器上方，从下拉菜单中选择要运行的函数，然后点击运行。
首次执行时，系统会提示您授权访问。请查看并允许 Apps 脚本访问您的日历。
您可以在窗口底部显示的执行日志 中检查脚本执行结果。