Events: insert

创建活动。 立即试用。

请求

HTTP 请求

POST https://www.googleapis.com/calendar/v3/calendars/calendarId/events

参数

参数名称 值 说明
路径参数
calendarId string 日历标识符。如需检索日历 ID，请调用 calendarList.list 方法。如果您想访问当前登录用户的主日历，请使用“primary”关键字。
可选的查询参数
conferenceDataVersion integer API 客户端支持的会议数据的版本号。版本 0 假定不支持会议数据，并忽略活动正文中的会议数据。版本 1 支持复制 ConferenceData，以及使用 conferenceData 的 createRequest 字段创建新会议。默认值为 0。 可接受的值为 0 到 1（含）。
eventLabelVersion integer API 客户端支持的事件标签功能的版本号。版本 0 假定不支持事件标签，并处理 colorId 字段以进行色彩管理。版本 1 支持事件标签，并处理事件正文中的 eventLabelId。在这种情况下，系统会忽略 colorId 字段。默认值为 0。 可接受的值为 0 到 1（含）。
maxAttendees integer 响应中可包含的最多出席者人数。如果出席者人数超过指定人数，则仅返回参与者。可选。
sendNotifications boolean 已弃用。请改用 sendUpdates。

是否发送有关创建新活动的通知。请注意，即使您将值设置为 false，系统可能仍会发送某些电子邮件。默认值为 false。
sendUpdates string 是否发送有关创建新活动的通知。请注意，系统可能仍会发送部分电子邮件。默认值为 false。

可接受的值：
  • “all”：系统会将通知发送给所有邀请对象。
  • “externalOnly”：仅向非 Google 日历邀请对象发送通知。
  • “none”：不发送任何通知。
supportsAttachments boolean 执行操作的 API 客户端是否支持事件附件。可选。默认值为 False。

授权

此请求需要获得以下至少一个范围的授权：

范围
https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.events
https://www.googleapis.com/auth/calendar.app.created
https://www.googleapis.com/auth/calendar.events.owned

如需了解详情，请参阅身份验证和授权页面。

请求正文

在请求正文中，提供具有以下属性的 Events 资源：

属性名称 值 说明 备注
必需属性
end nested object 活动的结束时间（不含）。对于周期性活动，这是第一个实例的结束时间。
start nested object 活动的（含端点值）开始时间。对于周期性活动，这是第一个实例的开始时间。
可选属性
anyoneCanAddSelf boolean 是否允许任何人自行邀请自己参加活动（已弃用）。可选。默认值为 False。 可写入
attachments[].fileUrl string 附件的网址链接。

添加 Google 云端硬盘文件附件时，请使用与 Drive API 中 Files 资源的 alternateLink 属性相同的格式。

添加附件时必须指定。

 可写入
attendees[] list 活动的参加者。如需详细了解如何与其他日历用户安排活动，请参阅有参加者的活动指南。服务账号需要使用全网域授权来填充参会者名单。 可写入
attendees[].additionalGuests integer 额外房客人数。可选。默认值为 0。 可写入
attendees[].comment string 参会者的回答评论。可选。 可写入
attendees[].displayName string 参会者的姓名（如果有）。可选。 可写入
attendees[].email string 参会者的电子邮件地址（如有）。添加参会者时，必须提供此字段。必须是符合 RFC5322 的有效电子邮件地址。

添加参会者时必须指定这项设置。

 可写入
attendees[].optional boolean 相应人员是否为可选参加者。可选。默认值为 False。 可写入
attendees[].resource boolean 相应出席者是否为资源。只能在首次将参会者添加到活动时设置。后续修改会被忽略。可选。默认值为 False。 可写入
attendees[].responseStatus string 参会者的回复状态。可能的值包括：
  • needsAction” - 参加者尚未回复邀请（建议用于新活动）。
  • “declined” - 参加者已拒绝邀请。
  • “tentative” - 参加者已暂时接受邀请。
  • “accepted” - 受邀者已接受邀请。
 可写入
birthdayProperties nested object 生日或特殊活动数据。如果 eventType 为 "birthday"，则使用此字段。固定不变。 可写入
birthdayProperties.type string 生日或特殊活动的类型。可能的值包括：
  • "anniversary" - 生日以外的纪念日。始终具有 contact。
  • "birthday" - 生日活动。这是默认值。
  • "custom" - 一种特殊日期，其标签在 customTypeName 字段中进一步指定。始终具有 contact。
  • "other" - 不属于其他类别且没有自定义标签的特殊日期。始终具有 contact。
  • "self" - 日历所有者本人的生日。不得有 contact。
日历 API 仅支持创建类型为 "birthday" 的活动。活动创建后，类型便无法更改。		 可写入
colorId string 活动的颜色。此 ID 是指颜色定义 event 部分中的一个条目（请参阅 颜色端点）。可选。 可写入
conferenceData nested object 与会议相关的信息，例如 Google Meet 会议的详细信息。如需创建新的会议详细信息，请使用 createRequest 字段。如需保留所做更改，请务必将所有事件修改请求的 conferenceDataVersion 请求参数设置为 1。 可写入
description string 活动的说明。可包含 HTML。可选。 可写入
end.date date 如果活动为全天活动，则为日期，格式为“yyyy-mm-dd”。 可写入
end.dateTime datetime 时间，以组合日期时间值（根据 RFC3339 格式设置）表示。除非在 timeZone 中明确指定了时区，否则必须提供时区偏移量。 可写入
end.timeZone string 指定时间所处的时区。（格式采用 IANA 时区数据库名称，例如“Europe/Zurich”。）对于周期性活动，此字段是必需字段，用于指定展开重复周期的时区。对于单次活动，此字段为可选字段，用于指明活动开始/结束时间的自定义时区。 可写入
eventLabelId string 分配给相应事件的事件标签的 ID。可选。指日历的 labelProperties.eventLabels 属性中条目的 ID（请参阅 Calendars.get 端点）。

此属性取代了基于索引的 colorId 属性。如需设置或更改此属性，您需要在 insert、import、update 和 patch 方法的参数中指定 eventLabelVersion=1。

如果将此字段设置为空字符串或根本不设置此字段，系统会从相应活动中移除现有标签。

 可写入
eventType string 事件的具体类型。活动创建后，此设置将无法修改。可能的值包括：
  • “birthday” - 一种每年重复一次的特殊全天活动。
  • “default” - 常规活动或未进一步指定。
  • “focusTime” - 专注时间活动。
  • “fromGmail” - 来自 Gmail 的活动。无法创建此类活动。
  • “outOfOffice” - “不在办公室”活动。
  • “workingLocation” - 工作地点事件。
 可写入
extendedProperties.private object 相应活动副本（显示在此日历上）的私有属性。 可写入
extendedProperties.shared object 其他参加者日历中活动副本之间共享的属性。 可写入
focusTimeProperties nested object 专注时间事件数据。如果 eventType 为 focusTime，则使用此字段。 可写入
gadget.display string 设备的显示模式。已弃用。可能的值包括：
  • “icon” - 该微件会显示在日历视图中活动标题的旁边。
  • “chip” - 点击相应活动时，微件会显示。
 可写入
gadget.height integer 相应信息块的高度（以像素为单位）。高度必须是大于 0 的整数。可选。已弃用。 可写入
gadget.preferences object 偏好设置。 可写入
gadget.title string 小工具的标题。已弃用。 可写入
gadget.type string 相应信息块的类型。已弃用。 可写入
gadget.width integer 微件的宽度（以像素为单位）。宽度必须是大于 0 的整数。可选。已弃用。 可写入
guestsCanInviteOthers boolean 除组织者之外的参会者是否可以邀请他人参加活动。可选。默认值为 True。 可写入
guestsCanModify boolean 组织者以外的参与者是否可以修改活动。可选。默认值为 False。 可写入
guestsCanSeeOtherGuests boolean 指定除组织者之外的参会者能否查看活动的参会者。可选。默认值为 True。 可写入
id string 相应事件的不透明标识符。创建新的单次活动或周期性活动时，您可以指定其 ID。提供的 ID 必须遵循以下规则：
  • ID 中允许使用的字符是 base32hex 编码中使用的字符，即小写字母 a-v 和数字 0-9，请参阅 RFC2938 中的第 3.1.2 节
  • ID 的长度必须介于 5 到 1024 个字符之间
  • 每个日历的 ID 必须是唯一的
由于系统是全球分布式的，我们无法保证在创建活动时检测到 ID 冲突。为尽可能降低冲突风险，我们建议使用成熟的 UUID 算法，例如 RFC4122 中描述的算法。

如果您未指定 ID，服务器会自动生成一个 ID。

请注意，icalUID 和 id 并不相同，在创建事件时只能提供其中一个。在语义上，两者的一大区别在于，在周期性活动中，一个活动的所有发生时间都具有不同的 id，但它们都具有相同的 icalUID。

 可写入
location string 活动的地理位置（自由格式文本）。可选。 可写入
originalStartTime.date date 如果活动为全天活动，则为日期，格式为“yyyy-mm-dd”。 可写入
originalStartTime.dateTime datetime 时间，以组合日期时间值（根据 RFC3339 格式设置）表示。除非在 timeZone 中明确指定了时区，否则必须提供时区偏移量。 可写入
originalStartTime.timeZone string 指定时间所处的时区。（格式采用 IANA 时区数据库名称，例如“Europe/Zurich”。）对于周期性活动，此字段是必需字段，用于指定展开重复周期的时区。对于单次活动，此字段为可选字段，用于指明活动开始/结束时间的自定义时区。 可写入
outOfOfficeProperties nested object “不在办公室”活动数据。如果 eventType 为 outOfOffice，则使用此字段。 可写入
recurrence[] list 重复性活动的 RRULE、EXRULE、RDATE 和 EXDATE 行的列表，如 RFC5545 中所指定。请注意，此字段中不允许使用 DTSTART 和 DTEND 行；活动开始时间和结束时间在 start 和 end 字段中指定。对于单次活动或周期性活动的实例，此字段会被省略。 可写入
reminders.overrides[] list 如果活动不使用默认提醒，则此属性会列出特定于活动的提醒；如果未设置提醒，则会指明此活动未设置任何提醒。替换提醒的数量上限为 5 个。 可写入
reminders.overrides[].method string 相应提醒所用的方法。可能的值包括：
  • “email” - 系统会通过电子邮件发送提醒。
  • “popup” - 通过界面弹出窗口发送提醒。

添加提醒时必须提供。

 可写入
reminders.overrides[].minutes integer 提醒应在活动开始前多少分钟触发。有效值介于 0 到 40320 之间（以分钟为单位，相当于 4 周）。

添加提醒时必须提供。

 可写入
reminders.useDefault boolean 日历的默认提醒是否适用于相应活动。 可写入
sequence integer iCalendar 中的序列号。 可写入
source.title string 来源的标题；例如网页的标题或电子邮件的主题。 可写入
source.url string 指向资源的来源的网址。网址协议必须是 HTTP 或 HTTPS。 可写入
start.date date 如果活动为全天活动，则为日期，格式为“yyyy-mm-dd”。 可写入
start.dateTime datetime 时间，以组合日期时间值（根据 RFC3339 格式设置）表示。除非在 timeZone 中明确指定了时区，否则必须提供时区偏移量。 可写入
start.timeZone string 指定时间所处的时区。（格式采用 IANA 时区数据库名称，例如“Europe/Zurich”。）对于周期性活动，此字段是必需字段，用于指定展开重复周期的时区。对于单次活动，此字段为可选字段，用于指明活动开始/结束时间的自定义时区。 可写入
status string 活动的状态。可选。可能的值包括：
  • “confirmed” - 活动已确认。这是默认状态。
  • “tentative” - 活动已暂时确认。
  • “cancelled” - 活动已取消（已删除）。list 方法仅在增量同步（指定了 syncToken 或 updatedMin）时或 showDeleted 标志设置为 true 时返回已取消的活动。get 方法始终会返回这些信息。

    “已取消”状态表示两种不同的状态，具体取决于活动类型：

    1. 未取消的周期性活动的已取消例外情况表示相应实例不应再向用户显示。客户端应在父周期性活动的整个生命周期内存储这些事件。

      对于已取消的异常，系统仅保证会填充 id、recurringEventId 和 originalStartTime 字段的值。其他字段可能为空。

    2. 所有其他已取消的活动都表示已删除的活动。客户应移除本地同步的副本。此类已取消的活动最终会消失，因此请勿指望它们会无限期保留。

      已删除的事件仅保证填充了 id 字段。

    在组织者的日历中，已取消的活动会继续显示活动详情（摘要、地点等），以便恢复（取消删除）这些活动。同样，用户受邀参加并手动移除的活动仍会提供详细信息。不过，如果将 showDeleted 设置为 false，增量同步请求将不会返回这些详细信息。

    如果活动的组织者发生更改（例如通过移动操作），并且原始组织者不在参加者列表中，则会留下一个已取消的活动，其中只有 id 字段保证会填充。

 可写入
summary string 活动的标题。 可写入
transparency string 活动是否会占用日历中的时间。可选。可能的值包括：
  • “opaque” - 默认值。活动会占用日历中的时间。这相当于在日历界面中将显示为设置为忙碌。
  • “transparent”：活动不会占用日历上的时间。这相当于在日历界面中将显示为设置为有空。
 可写入
visibility string 活动的公开范围。可选。可能的值包括：
  • “default” - 使用日历中活动的默认公开范围。这是默认值。
  • “public” - 活动是公开的，日历的所有读者都可以查看活动详情。
  • “private” - 活动是不公开的，只有活动参会者可以查看活动详情。
  • “confidential” - 活动是不公开的。提供此值是为了保持兼容性。

关于周期性活动的注意事项：更改周期性活动中单个活动的公开范围可能会影响整个系列中的所有活动。如果新设置的限制更严格（例如，从公开变为不公开），则会应用于所有实例。如果新设置的限制较少（例如从“不公开”更改为“公开”），则系统会忽略相应更改。如需放宽周期性活动的限制，您必须更新父周期性活动。

 可写入
workingLocationProperties nested object 工作地点事件数据。 可写入
workingLocationProperties.customLocation object 如果存在，则表示用户正在自定义位置办公。 可写入
workingLocationProperties.customLocation.label string 用于提供额外信息的可选额外标签。 可写入
workingLocationProperties.homeOffice any value 如果存在，则指定用户在家办公。 可写入
workingLocationProperties.officeLocation object 如果存在，则指定用户在办公室工作。 可写入
workingLocationProperties.officeLocation.buildingId string 可选的建筑标识符。此值应引用组织资源数据库中的建筑物 ID。 可写入
workingLocationProperties.officeLocation.deskId string 可选的办公桌标识符。 可写入
workingLocationProperties.officeLocation.floorId string 可选的楼层标识符。 可写入
workingLocationProperties.officeLocation.floorSectionId string 可选的楼层部分标识符。 可写入
workingLocationProperties.officeLocation.label string 在 Google 日历网页版和移动版客户端中显示的办公室名称。建议您引用组织资源数据库中的建筑物名称。 可写入
workingLocationProperties.type string 工作地点的类型。可能的值包括：
  • “homeOffice” - 用户在家办公。
  • “officeLocation” - 用户在办公室工作。
  • “customLocation” - 用户在自定义位置办公。
任何详细信息都在指定名称的子字段中指定，但如果为空，则此字段可能会缺失。系统会忽略所有其他字段。

添加工作地点属性时必需。

 可写入

响应

如果成功，此方法将在响应正文中返回一项 Events 资源。

试试看！

使用下面的 API Explorer 对实际数据调用此方法，然后查看响应。