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，以及使用 conferenceData 的 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
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”- 参加者已接受邀请。
 可写入
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 时区数据库名称，例如“Europe/Zurich”）。对于周期性活动，此字段是必填字段，用于指定展开周期性活动时所采用的时区。对于单个事件，此字段为可选字段，用于指明事件开始/结束的自定义时区。 可写入
extendedProperties.private object 此日历上显示的活动副本的私有属性。 可写入
extendedProperties.shared object 其他参加者日历中活动副本之间共享的属性。 可写入
focusTimeProperties nested object “专注时间”活动数据。如果 eventType 设为 focusTime，则此字段适用。 可写入
gadget.display string 小工具的显示模式。已弃用。可能的值包括：
  • “icon”- 该微件会显示在日历视图中活动标题旁边。
  • “chip”- 点击事件时显示该小工具。
 可写入
gadget.height integer 小工具的高度（以像素为单位）。高度必须是正整数。可选。已弃用。 可写入
gadget.preferences object 偏好设置。 可写入
gadget.title string 微件的标题。已弃用。 可写入
gadget.type string 该小工具的类型。已弃用。 可写入
gadget.width integer 该小工具的宽度（以像素为单位）。宽度必须是正整数。可选。已弃用。 可写入
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 时区数据库名称，例如“Europe/Zurich”）。对于周期性活动，此字段是必填字段，用于指定展开周期性活动时所采用的时区。对于单个事件，此字段为可选字段，用于指明事件开始/结束的自定义时区。 可写入
outOfOfficeProperties nested object “不在办公室”活动数据。如果 eventType 设为 outOfOffice，则此字段适用。 可写入
recurrence[] list 如 RFC5545 中所指定，重复性事件的 RRULE、EXRULE、RDATE 和 EXDATE 行列表。请注意，此字段不允许使用 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”- 活动不会占用日历上的时间。这相当于在 Google 日历界面中将将我显示为设置为空闲。
 可写入
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 资源。

示例

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

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 对实际数据调用此方法，然后查看响应。