Events: update

更新活动。此方法不支持补丁语义，并且会始终更新整个事件资源。如需执行部分更新，请使用 etag 执行 get，后跟 update，以确保原子性。立即试用或查看示例。

请求

HTTP 请求

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

参数

参数名称 值 说明
路径参数
calendarId string 日历标识符。要检索日历 ID，请调用 calendarList.list 方法。如果您想访问当前登录的用户的主日历，请使用关键字“primary”。
eventId string 事件标识符。
可选的查询参数
alwaysIncludeEmail boolean 已弃用并忽略。即使没有真实的电子邮件地址可供使用，系统也会始终在组织者、创作者和参加者的 email 字段中返回一个值（即，将提供一个生成的非工作值）。
conferenceDataVersion integer API 客户端支持的会议数据的版本号。版本 0 假定不支持任何会议数据，并忽略活动正文中的会议数据。版本 1 支持复制 ConferenceData，以及使用 meetingData 的 createRequest 字段创建新会议。默认值为 0。 可接受的值包括 0 到 1（闭区间）。
maxAttendees integer 回复中可包含的参加者人数上限。如果参加者人数超过指定数量，则仅返回参与者。可选。
sendNotifications boolean 已弃用。请改用 sendUpdates。

是否发送有关活动更新的通知（例如说明更改等）。请注意，即使将值设置为 false，系统可能仍会发送某些电子邮件。默认值为 false。
sendUpdates string 应收到活动更新通知（例如标题更改等）的邀请对象。

可接受的值：
  • “all”：系统会向所有邀请对象发送通知。
  • “externalOnly”：通知仅会发送给非 Google 日历邀请对象。
  • “none”：不发送通知。对于日历迁移任务，请考虑改用 Events.import 方法。
supportsAttachments boolean 执行操作的 API 客户端是否支持事件附件。可选。默认值为 False。

授权

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

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

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

请求正文

在请求正文中，提供具有以下属性的 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”- 参加者已接受邀请。
 可写
attendeesOmitted boolean 是否从活动的信息图中省略了参加者。在检索事件时，这可能是由于 maxAttendee 查询参数指定的限制造成的。更新活动时，此字段可用于仅更新参与者的回复。可选。默认值为 False。 可写
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 时区数据库名称，例如“欧洲/苏黎世”。）对于周期性活动，此字段为必填字段，用于指定周期性活动扩展的时区。对于单个活动，此字段为选填字段，用于表示活动开始/结束时间的自定义时区。 可写
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。 可写
location string 活动的地理位置（以自由格式文本表示）。可选。 可写
originalStartTime.date date 如果是全天活动，则采用“yyyy-mm-dd”格式的日期。 可写
originalStartTime.dateTime datetime 时间，采用日期-时间的组合值形式（格式遵循 RFC3339）。除非在 timeZone 中明确指定了时区，否则必须指定时区偏移量。 可写
originalStartTime.timeZone string 指定时间的时区。（格式为 IANA 时区数据库名称，例如“欧洲/苏黎世”。）对于周期性活动，此字段为必填字段，用于指定周期性活动扩展的时区。对于单个活动，此字段为选填字段，用于表示活动开始/结束时间的自定义时区。 可写
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 时区数据库名称，例如“欧洲/苏黎世”。）对于周期性活动，此字段为必填字段，用于指定周期性活动扩展的时区。对于单个活动，此字段为选填字段，用于表示活动开始/结束时间的自定义时区。 可写
status string 事件的状态。可选。可能的值包括：
  • “confirmed”- 活动已确认。这是默认状态。
  • “tentative”- 该活动是暂定确认的。
  • “cancelled”- 活动已取消（已删除）。只有在增量同步时（指定了 syncToken 或 updatedMin 时）或 showDeleted 标志设置为 true 时，list 方法才会返回已取消的事件。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 日历网页版和移动版客户端中显示的 Office 名称。我们建议您在组织的“资源”数据库中引用建筑物名称。 可写
workingLocationProperties.type string 工作地点的类型。可能的值包括：
  • “homeOffice”- 用户在家工作。
  • “officeLocation”- 用户在办公室工作。
  • “customLocation”- 用户正在自定义位置工作。
。所有详细信息都会在所指定名称的子字段中指定，但如果此字段为空，则可能缺失。任何其他字段都会被忽略。

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

 可写

响应

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

示例

注意：此方法的代码示例并未列出所有受支持的编程语言（请参阅客户端库页面，查看受支持的语言列表）。

Java

使用 Java 客户端库。

import com.google.api.services.calendar.Calendar;
import com.google.api.services.calendar.model.Event;

// ...

// Initialize Calendar service with valid OAuth credentials
Calendar service = new Calendar.Builder(httpTransport, jsonFactory, credentials)
    .setApplicationName("applicationName").build();

// Retrieve the event from the API
Event event = service.events().get("primary", "eventId").execute();

// Make a change
event.setSummary("Appointment at Somewhere");

// Update the event
Event updatedEvent = service.events().update("primary", event.getId(), event).execute();

System.out.println(updatedEvent.getUpdated());

Python

使用 Python 客户端库。

# First retrieve the event from the API.
event = service.events().get(calendarId='primary', eventId='eventId').execute()

event['summary'] = 'Appointment at Somewhere'

updated_event = service.events().update(calendarId='primary', eventId=event['id'], body=event).execute()

# Print the updated date.
print updated_event['updated']

PHP

使用 PHP 客户端库。

// First retrieve the event from the API.
$event = $service->events->get('primary', 'eventId');

$event->setSummary('Appointment at Somewhere');

$updatedEvent = $service->events->update('primary', $event->getId(), $event);

// Print the updated date.
echo $updatedEvent->getUpdated();

Ruby

使用 Ruby 客户端库。

event = client.get_event('primary', 'eventId')
event.summary = 'Appointment at Somewhere'
result = client.update_event('primary', event.id, event)
print result.updated

试试看！

请使用下面的 API Explorer 对实时数据调用此方法并查看响应。