更新活动。此方法不支持补丁语义,并且会始终更新整个事件资源。如需执行部分更新,请使用 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 |
应收到活动更新通知(例如标题更改等)的邀请对象。
可接受的值:
|
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 中 添加附件时必填。 |
可写 |
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 |
参加者的响应状态。可能的值包括:
|
可写 |
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 |
小工具的显示模式。已弃用。可能的值包括:
|
可写 |
gadget.height |
integer |
小工具的高度(以像素为单位)。高度必须是大于 0 的整数。可选。已弃用。 | 可写 |
gadget.iconLink |
string |
小工具的图标网址。网址架构必须是 HTTPS。已弃用。 | 可写 |
gadget.link |
string |
小工具的网址。网址架构必须是 HTTPS。已弃用。 | 可写 |
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 |
此提醒使用的方法。可能的值包括:
添加提醒时必填。 |
可写 |
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 |
事件的状态。可选。可能的值包括:
|
可写 |
summary |
string |
活动的标题。 | 可写 |
transparency |
string |
相应活动是否会在日历上占用时间。可选。可能的值包括:
|
可写 |
visibility |
string |
活动的公开范围。可选。可能的值包括:
|
可写 |
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 |
工作地点的类型。可能的值包括:
添加工作地点属性时必填。 |
可写 |
响应
如果成功,此方法将在响应正文中返回一项 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 对实时数据调用此方法并查看响应。