请求
HTTP 请求
POST https://www.googleapis.com/calendar/v3/calendars/calendarId/events
参数
参数名称 | 值 | 说明 |
---|---|---|
路径参数 | ||
calendarId |
string |
日历标识符。如需检索日历 ID,请调用 calendarList.list 方法。如果您想访问当前登录用户的主要日历,请使用“primary ”关键字。
|
可选的查询参数 | ||
conferenceDataVersion |
integer |
API 客户端支持的会议数据的版本号。版本 0 假定不支持会议数据,并会忽略事件正文中的会议数据。版本 1 支持复制 ConferenceData,还支持使用 meetingData 的 createRequest 字段创建新会议。默认值为 0。
可接受的值为 0 到 1 (含)。
|
maxAttendees |
integer |
响应中包含的参加者数量上限。如果参加者人数超过指定数量,则只返回参与者。可选。 |
sendNotifications |
boolean |
已弃用。请改用 sendUpdates。 是否发送有关新事件创建的通知。请注意,即使您将该值设为 false ,系统可能仍会发送某些电子邮件。默认值为 false 。
|
sendUpdates |
string |
是否发送有关新事件创建的通知。请注意,系统可能仍会发送某些电子邮件。默认值为 false 。
可接受的值包括:
|
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 |
参加者的回复状态。可能的值包括:
|
可写入 |
birthdayProperties |
nested object |
生日或特殊活动数据。如果 eventType 设为 "birthday" ,则此字段可用。固定不变。 |
可写入 |
birthdayProperties.type |
string |
生日或特殊活动的类型。可能的值包括:
"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”)。对于周期性活动,此字段是必填字段,用于指定重复周期对应的时区。对于单个事件,此字段为可选字段,用于指明事件开始/结束的自定义时区。 | 可写入 |
eventType |
string |
事件的特定类型。活动创建后,此设置将无法修改。可能的值包括:
|
可写入 |
extendedProperties.private |
object |
此日历上显示的活动副本的私有属性。 | 可写入 |
extendedProperties.shared |
object |
其他参加者日历中活动副本之间共享的属性。 | 可写入 |
focusTimeProperties |
nested object |
“专注时间”活动数据。如果 eventType 设为 focusTime ,则使用此字段。 |
可写入 |
gadget.display |
string |
小工具的显示模式。已弃用。可能的值包括:
|
可写入 |
gadget.height |
integer |
小工具的高度(以像素为单位)。高度必须是正整数。可选。已弃用。 | 可写入 |
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。 | 可写入 |
id |
string |
事件的不透明标识符。创建新的单次或周期性事件时,您可以指定其 ID。提供的 ID 必须遵循以下规则:
如果您未指定 ID,服务器会自动生成 ID。 请注意, |
可写入 |
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 |
此提醒所使用的提醒方法。可能的值包括:
添加提醒时必填。 |
可写入 |
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 |
事件的状态。可选。可能的值包括:
|
可写入 |
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 日历网页版和移动版客户端中显示的办公室名称。我们建议您引用组织的“资源”数据库中的建筑物名称。 | 可写入 |
workingLocationProperties.type |
string |
工作地点的类型。可能的值包括:
添加工作地点属性时必填。 |
可写入 |
响应
如果成功,此方法将在响应正文中返回一项 Events 资源。
示例
注意:此方法的代码示例并未列出所有受支持的编程语言(请参阅客户端库页面,查看受支持的语言列表)。
Java
使用 Java 客户端库。
// Refer to the Java quickstart on how to setup the environment: // https://developers.google.com/calendar/quickstart/java // Change the scope to CalendarScopes.CALENDAR and delete any stored // credentials. Event event = new Event() .setSummary("Google I/O 2015") .setLocation("800 Howard St., San Francisco, CA 94103") .setDescription("A chance to hear more about Google's developer products."); DateTime startDateTime = new DateTime("2015-05-28T09:00:00-07:00"); EventDateTime start = new EventDateTime() .setDateTime(startDateTime) .setTimeZone("America/Los_Angeles"); event.setStart(start); DateTime endDateTime = new DateTime("2015-05-28T17:00:00-07:00"); EventDateTime end = new EventDateTime() .setDateTime(endDateTime) .setTimeZone("America/Los_Angeles"); event.setEnd(end); String[] recurrence = new String[] {"RRULE:FREQ=DAILY;COUNT=2"}; event.setRecurrence(Arrays.asList(recurrence)); EventAttendee[] attendees = new EventAttendee[] { new EventAttendee().setEmail("lpage@example.com"), new EventAttendee().setEmail("sbrin@example.com"), }; event.setAttendees(Arrays.asList(attendees)); EventReminder[] reminderOverrides = new EventReminder[] { new EventReminder().setMethod("email").setMinutes(24 * 60), new EventReminder().setMethod("popup").setMinutes(10), }; Event.Reminders reminders = new Event.Reminders() .setUseDefault(false) .setOverrides(Arrays.asList(reminderOverrides)); event.setReminders(reminders); String calendarId = "primary"; event = service.events().insert(calendarId, event).execute(); System.out.printf("Event created: %s\n", event.getHtmlLink());
Python
使用 Python 客户端库。
# Refer to the Python quickstart on how to setup the environment: # https://developers.google.com/calendar/quickstart/python # Change the scope to 'https://www.googleapis.com/auth/calendar' and delete any # stored credentials. event = { 'summary': 'Google I/O 2015', 'location': '800 Howard St., San Francisco, CA 94103', 'description': 'A chance to hear more about Google\'s developer products.', 'start': { 'dateTime': '2015-05-28T09:00:00-07:00', 'timeZone': 'America/Los_Angeles', }, 'end': { 'dateTime': '2015-05-28T17:00:00-07:00', 'timeZone': 'America/Los_Angeles', }, 'recurrence': [ 'RRULE:FREQ=DAILY;COUNT=2' ], 'attendees': [ {'email': 'lpage@example.com'}, {'email': 'sbrin@example.com'}, ], 'reminders': { 'useDefault': False, 'overrides': [ {'method': 'email', 'minutes': 24 * 60}, {'method': 'popup', 'minutes': 10}, ], }, } event = service.events().insert(calendarId='primary', body=event).execute() print 'Event created: %s' % (event.get('htmlLink'))
PHP
使用 PHP 客户端库。
// Refer to the PHP quickstart on how to setup the environment: // https://developers.google.com/calendar/quickstart/php // Change the scope to Google_Service_Calendar::CALENDAR and delete any stored // credentials. $event = new Google_Service_Calendar_Event(array( 'summary' => 'Google I/O 2015', 'location' => '800 Howard St., San Francisco, CA 94103', 'description' => 'A chance to hear more about Google\'s developer products.', 'start' => array( 'dateTime' => '2015-05-28T09:00:00-07:00', 'timeZone' => 'America/Los_Angeles', ), 'end' => array( 'dateTime' => '2015-05-28T17:00:00-07:00', 'timeZone' => 'America/Los_Angeles', ), 'recurrence' => array( 'RRULE:FREQ=DAILY;COUNT=2' ), 'attendees' => array( array('email' => 'lpage@example.com'), array('email' => 'sbrin@example.com'), ), 'reminders' => array( 'useDefault' => FALSE, 'overrides' => array( array('method' => 'email', 'minutes' => 24 * 60), array('method' => 'popup', 'minutes' => 10), ), ), )); $calendarId = 'primary'; $event = $service->events->insert($calendarId, $event); printf('Event created: %s\n', $event->htmlLink);
Ruby
使用 Ruby 客户端库。
event = Google::Apis::CalendarV3::Event.new( summary: 'Google I/O 2015', location: '800 Howard St., San Francisco, CA 94103', description: 'A chance to hear more about Google\'s developer products.', start: Google::Apis::CalendarV3::EventDateTime.new( date_time: '2015-05-28T09:00:00-07:00', time_zone: 'America/Los_Angeles' ), end: Google::Apis::CalendarV3::EventDateTime.new( date_time: '2015-05-28T17:00:00-07:00', time_zone: 'America/Los_Angeles' ), recurrence: [ 'RRULE:FREQ=DAILY;COUNT=2' ], attendees: [ Google::Apis::CalendarV3::EventAttendee.new( email: 'lpage@example.com' ), Google::Apis::CalendarV3::EventAttendee.new( email: 'sbrin@example.com' ) ], reminders: Google::Apis::CalendarV3::Event::Reminders.new( use_default: false, overrides: [ Google::Apis::CalendarV3::EventReminder.new( reminder_method: 'email', minutes: 24 * 60 ), Google::Apis::CalendarV3::EventReminder.new( reminder_method: 'popup', minutes: 10 ) ] ) ) result = client.insert_event('primary', event) puts "Event created: #{result.html_link}"
.NET
使用 .NET 客户端库。
// Refer to the .NET quickstart on how to setup the environment: // https://developers.google.com/calendar/quickstart/dotnet // Change the scope to CalendarService.Scope.Calendar and delete any stored // credentials. Event newEvent = new Event() { Summary = "Google I/O 2015", Location = "800 Howard St., San Francisco, CA 94103", Description = "A chance to hear more about Google's developer products.", Start = new EventDateTime() { DateTime = DateTime.Parse("2015-05-28T09:00:00-07:00"), TimeZone = "America/Los_Angeles", }, End = new EventDateTime() { DateTime = DateTime.Parse("2015-05-28T17:00:00-07:00"), TimeZone = "America/Los_Angeles", }, Recurrence = new String[] { "RRULE:FREQ=DAILY;COUNT=2" }, Attendees = new EventAttendee[] { new EventAttendee() { Email = "lpage@example.com" }, new EventAttendee() { Email = "sbrin@example.com" }, }, Reminders = new Event.RemindersData() { UseDefault = false, Overrides = new EventReminder[] { new EventReminder() { Method = "email", Minutes = 24 * 60 }, new EventReminder() { Method = "sms", Minutes = 10 }, } } }; String calendarId = "primary"; EventsResource.InsertRequest request = service.Events.Insert(newEvent, calendarId); Event createdEvent = request.Execute(); Console.WriteLine("Event created: {0}", createdEvent.HtmlLink);
Go
使用 Go 客户端库。
// Refer to the Go quickstart on how to setup the environment: // https://developers.google.com/calendar/quickstart/go // Change the scope to calendar.CalendarScope and delete any stored credentials. event := &calendar.Event{ Summary: "Google I/O 2015", Location: "800 Howard St., San Francisco, CA 94103", Description: "A chance to hear more about Google's developer products.", Start: &calendar.EventDateTime{ DateTime: "2015-05-28T09:00:00-07:00", TimeZone: "America/Los_Angeles", }, End: &calendar.EventDateTime{ DateTime: "2015-05-28T17:00:00-07:00", TimeZone: "America/Los_Angeles", }, Recurrence: []string{"RRULE:FREQ=DAILY;COUNT=2"}, Attendees: []*calendar.EventAttendee{ &calendar.EventAttendee{Email:"lpage@example.com"}, &calendar.EventAttendee{Email:"sbrin@example.com"}, }, } calendarId := "primary" event, err = srv.Events.Insert(calendarId, event).Do() if err != nil { log.Fatalf("Unable to create event. %v\n", err) } fmt.Printf("Event created: %s\n", event.HtmlLink)
JavaScript
使用 JavaScript 客户端库。
// Refer to the JavaScript quickstart on how to setup the environment: // https://developers.google.com/calendar/quickstart/js // Change the scope to 'https://www.googleapis.com/auth/calendar' and delete any // stored credentials. var event = { 'summary': 'Google I/O 2015', 'location': '800 Howard St., San Francisco, CA 94103', 'description': 'A chance to hear more about Google\'s developer products.', 'start': { 'dateTime': '2015-05-28T09:00:00-07:00', 'timeZone': 'America/Los_Angeles' }, 'end': { 'dateTime': '2015-05-28T17:00:00-07:00', 'timeZone': 'America/Los_Angeles' }, 'recurrence': [ 'RRULE:FREQ=DAILY;COUNT=2' ], 'attendees': [ {'email': 'lpage@example.com'}, {'email': 'sbrin@example.com'} ], 'reminders': { 'useDefault': false, 'overrides': [ {'method': 'email', 'minutes': 24 * 60}, {'method': 'popup', 'minutes': 10} ] } }; var request = gapi.client.calendar.events.insert({ 'calendarId': 'primary', 'resource': event }); request.execute(function(event) { appendPre('Event created: ' + event.htmlLink); });
Node.js
使用 Node.js 客户端库。
// Refer to the Node.js quickstart on how to setup the environment: // https://developers.google.com/calendar/quickstart/node // Change the scope to 'https://www.googleapis.com/auth/calendar' and delete any // stored credentials. var event = { 'summary': 'Google I/O 2015', 'location': '800 Howard St., San Francisco, CA 94103', 'description': 'A chance to hear more about Google\'s developer products.', 'start': { 'dateTime': '2015-05-28T09:00:00-07:00', 'timeZone': 'America/Los_Angeles', }, 'end': { 'dateTime': '2015-05-28T17:00:00-07:00', 'timeZone': 'America/Los_Angeles', }, 'recurrence': [ 'RRULE:FREQ=DAILY;COUNT=2' ], 'attendees': [ {'email': 'lpage@example.com'}, {'email': 'sbrin@example.com'}, ], 'reminders': { 'useDefault': false, 'overrides': [ {'method': 'email', 'minutes': 24 * 60}, {'method': 'popup', 'minutes': 10}, ], }, }; calendar.events.insert({ auth: auth, calendarId: 'primary', resource: event, }, function(err, event) { if (err) { console.log('There was an error contacting the Calendar service: ' + err); return; } console.log('Event created: %s', event.htmlLink); });
试试看!
使用下面的 API Explorer 对实际数据调用此方法,然后查看响应。