Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

事件类型

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

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

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

所有事件都会返回 eventType。
在创建或更新活动资源时，设置 eventType。如果未设置，则 API 会使用 'default'。
在 events.list 调用中指定 eventTypes，以列出特定类型的事件。如果未指定任何类型，该 API 会返回所有事件类型。
在 events.watch 调用中指定 eventTypes，以订阅特定类型事件的更新。如果未指定任何类型，则相应请求会订阅所有事件类型。

默认活动

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

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

生日

生日是特殊的周期性全天活动，每年重复一次。

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

日历 API 支持 events.get、events.instances 和 events.list 方法来读取生日活动。您可以将 eventTypes 设置为 'birthday'，以仅列出生日活动。如果未指定任何类型，则响应会列出所有其他活动类型以及生日。

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

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

您可以使用 events.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，您可以使用 events.update 和 events.patch 方法更新生日活动的 colorId、summary 和 reminders。您还可以更新 start 和 end 字段来更改活动日期。在这种情况下，新值必须定义一个持续时间恰好为一天的全天活动。如果生日活动与 contact 相关联，或者其 type 为 'self'，则无法更新生日活动的具体时间。

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

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

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

该 API 支持 events.watch 方法，用于订阅日历中生日活动的更改。您可以将 eventTypes 设置为 'birthday'，以订阅生日活动的更新。如果未指定任何类型，则相应请求会订阅所有事件类型，包括生日。

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

不支持使用 events.move 或 events.update 方法更改生日活动的组织者。

来自 Gmail 的活动

根据 Gmail 自动生成的活动具有 'fromGmail' 活动类型。

Calendar API 不允许使用 events.insert 方法创建此类活动。

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

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

该 API 支持 events.watch 方法，用于订阅 Google 日历中来自 Gmail 的活动的更改。如果未指定任何类型，则相应请求会订阅所有事件类型，包括 'fromGmail'。

您可以使用 Calendar API 的 events.delete 方法删除来自 Gmail 的活动。

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

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

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

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

探索 Apps 脚本中的事件类型

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

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

创建并设置脚本

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

（可选）更新 Cloud 项目

每个 Apps 脚本项目都有一个关联的云项目。您的脚本可以使用 Apps 脚本自动创建的默认项目。如果您想使用自定义云项目，请参阅切换到其他标准云项目。设置云项目后，选择左侧的 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 脚本访问您的日历。
您可以在窗口底部显示的执行日志中检查脚本执行结果。