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

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

请求正文

在请求正文中,提供具有以下属性的事件资源

属性名称 说明 备注
必需属性
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 时区数据库名称,例如“欧洲/苏黎世”。)对于周期性活动,此字段是必填字段,并用于指定展开重复活动的时区。对于单个活动,此字段是可选的,表示活动开始/结束时间的自定义时区。 可写入
extendedProperties.private object 仅此日历中显示的活动副本的私有属性。 可写入
extendedProperties.shared object 在其他参加者的日历上的活动副本之间共享的属性。 可写入
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,服务器便会自动生成。

请注意,icalUIDid 不完全相同,在创建事件时只应提供其中一个。它们在语义上的一个区别在于,在周期性事件中,一个事件的所有发生实例都有不同的 id,但它们全部共用相同的 icalUID

可写入
location string 活动的地理位置(采用自由格式文本)。可选。 可写入
originalStartTime.date date 如果日期为全天活动,则日期格式为“yyyy-mm-dd”。 可写入
originalStartTime.dateTime datetime 时间,采用日期时间组合值格式(遵循 RFC3339 格式)。除非在 timeZone 中明确指定时区,否则必须提供时区偏移量。 可写入
originalStartTime.timeZone string 指定时间的时区。(格式为 IANA 时区数据库名称,例如“欧洲/苏黎世”。)对于周期性活动,此字段是必填字段,并用于指定展开重复活动的时区。对于单个活动,此字段是可选的,表示活动开始/结束时间的自定义时区。 可写入
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”- 活动不会阻止日历上的时间。等同于在 Google 日历界面中将状态显示为设置为有空
可写入
visibility string 活动的公开范围。(可选)可能的值包括:
  • default”- 对日历中的活动使用默认公开范围。这是默认值。
  • public”- 活动为公开活动,并且日历的所有读者都可以看到活动详情。
  • private”- 活动为私人状态,只有活动参加者才能查看活动详情。
  • confidential”- 活动为私密活动。提供此值是为了确保兼容性。
可写入

响应

如果成功,此方法将在响应正文中返回 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 针对实际数据调用此方法,然后查看响应。