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,以及使用 meetingData 的 createRequest 字段创建新会议。默认值为 0。 可接受的值包括 01(闭区间)。
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

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

请求正文

在请求正文中,提供具有以下属性的 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”- 参加者已接受邀请。
可写
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 时区数据库名称,例如“欧洲/苏黎世”。)对于周期性活动,此字段为必填字段,用于指定周期性活动扩展的时区。对于单个活动,此字段为选填字段,用于表示活动开始/结束时间的自定义时区。 可写
eventType string 事件的具体类型。活动创建后,此字段便无法修改。可能的值包括:
  • default”:常规事件或未进一步指定。
  • outOfOffice”:不在办公室的活动。
  • focusTime”:专注时间活动。
  • workingLocation”- 工作地点活动。
目前,只能使用该 API 创建“default”和“workingLocation”事件。后续版本将扩展对其他事件类型的支持。
可写
extendedProperties.private object 仅对此日历上显示的活动的副本不公开的属性。 可写
extendedProperties.shared object 其他参与者日历上的活动副本之间共享的属性。 可写
focusTimeProperties nested object 专注时间事件数据。如果 eventTypefocusTime,使用此属性。 可写
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 中允许使用的字符是指采用 Base32 十六进制编码的字符,即小写字母 a-v 和数字 0-9,请参阅 RFC2938 中的第 3.1.2 节
  • ID 的长度必须介于 5 到 1024 个字符之间
  • 每个日历的 ID 必须是唯一的
由于该系统的全球分布式特性,我们无法保证会在创建活动时检测到 ID 冲突。为了最大限度地降低冲突风险,我们建议您使用已建立的 UUID 算法,例如 RFC4122 中所述的算法。

如果您未指定 ID,服务器将自动生成 ID。

请注意,icalUIDid 不完全相同,在创建事件时应仅提供其中一个。其语义的一个区别在于,在周期性事件中,一个事件的所有事件都具有不同的 id,而它们均具有相同的 icalUID

可写
location string 活动的地理位置(以自由格式文本表示)。可选。 可写
originalStartTime.date date 如果是全天活动,则采用“yyyy-mm-dd”格式的日期。 可写
originalStartTime.dateTime datetime 时间,采用日期-时间的组合值形式(格式遵循 RFC3339)。除非在 timeZone 中明确指定了时区,否则必须指定时区偏移量。 可写
originalStartTime.timeZone string 指定时间的时区。(格式为 IANA 时区数据库名称,例如“欧洲/苏黎世”。)对于周期性活动,此字段为必填字段,用于指定周期性活动扩展的时区。对于单个活动,此字段为选填字段,用于表示活动开始/结束时间的自定义时区。 可写
outOfOfficeProperties nested object 不在办公室的活动数据。如果 eventTypeoutOfOffice,使用此属性。 可写
recurrence[] list 周期性事件的 RRULE、EXRULE、RDATE 和 EXDATE 行的列表,如 RFC5545 中所指定。请注意,此字段中不允许使用 DTSTART 和 DTEND 行;事件的开始时间和结束时间需在 startend 字段中指定。单个活动或周期性活动的实例将省略此字段。 可写
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”- 活动已取消(已删除)。只有在增量同步时(指定了 syncTokenupdatedMin 时)或 showDeleted 标志设置为 true 时,list 方法才会返回已取消的事件。get 方法始终会返回这些类。

    “已取消”状态表示两种不同的状态,具体取决于事件类型:

    1. 对于未取消的周期性活动,其已取消的异常表示不应再向用户显示此实例。客户端应在父级周期性事件的生命周期内存储这些事件。

      已取消的异常只能保证填充 idrecurringEventIdoriginalStartTime 字段的值。其他字段可能为空。

    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 客户端库

// 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 对实时数据调用此方法并查看响应。