本页介绍了 eventType
属性,以及 Google 日历 API 中提供的活动类型的规范。
Google 日历允许用户创建通用活动,以及专为特定使用情形设计且具有自定义属性的活动。
您可以在 API 中的以下位置找到事件类型:
- 所有事件都以
eventType
形式返回。 - 创建或更新活动资源时,需要设置
eventType
。如果未设置,将使用'default'
类型。 eventTypes
可在Events:list
调用中指定,以列出特定类型的事件。如果未指定任何类型,系统将返回所有事件类型。- 可以在
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 Calendar API 作为高级服务来读取和管理活动。如需查看 Google 日历 API 资源和方法的完整列表,请参阅参考文档。
创建并设置脚本
- 前往 script.google.com/create 创建脚本。
- 在左侧窗格中,点击服务旁边的“添加服务”图标 。
- 选择 Google Calendar API,然后点击添加。
- 启用后,该 API 会显示在左侧窗格中。您可以在编辑器中使用 Calendar 关键字列出 API 中的可用方法和类。
(可选)更新 Google Cloud 项目
每个 Google Apps 脚本项目都有一个关联的 Google Cloud 项目。您的脚本可以使用 Google Apps 脚本自动创建的默认项目。如果您想使用自定义 Google Cloud 项目,请参阅切换到其他标准 Cloud 项目。设置 Google Cloud 项目后,选择左侧的编辑器 以返回代码编辑器。
向脚本添加代码
以下代码示例展示了如何列出、读取和创建具有不同 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 脚本访问您的日历。
- 您可以在窗口底部显示的执行日志中检查脚本执行结果。