事件类型

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

借助 Google 日历，用户可以创建通用活动，以及专为特定用例设计且具有自定义属性的活动。

您可以在 API 的以下位置找到该事件类型：

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

默认事件

系统会创建 default 事件类型的事件，并将其用作 Google Calendar API 的主要资源之一。它们支持各种属性，可用于进一步自定义事件。

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

生日

生日是每年重复的全天特殊活动。

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

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

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

  • type：此特殊活动的类型，例如生日、周年纪念日或其他重要日期。
  • customTypeName：用户为此特殊事件指定的标签。如果 type 设置为 'custom'，系统会填充此字段。
  • contact：此特殊活动关联到的联系人的资源名称（如果有）。此 ID 的格式为 '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 Calendar 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'。

您可以使用 Google Calendar API 的 delete 方法删除 Gmail 中的活动。

不支持使用 move 或 update 方法通过 Gmail 更改活动组织者。

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

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

这些功能仅适用于主日历，并且仅面向部分 Google 日历用户提供。如需了解详情，请参阅管理专注时间、外出和工作地点事件。

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

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

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

创建和设置脚本

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

（可选）更新 Google Cloud 项目

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

向脚本添加代码

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

  1. 将以下代码粘贴到代码编辑器中。

    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/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/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/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。

运行代码示例

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