Events: import

导入事件。此操作用于将现有活动的不公开副本添加到日历。只能导入 eventType 为 default 的事件。

已弃用的行为：如果导入了非 default 事件，其类型将更改为 default，并且该事件类型可能具有的任何特定于事件类型的属性都将被丢弃。

立即试用或查看示例。

请求

HTTP 请求

POST https://www.googleapis.com/calendar/v3/calendars/calendarId/events/import

参数

参数名称 值 说明
路径参数
calendarId string 日历标识符。要检索日历 ID，请调用 calendarList.list 方法。如果您想访问当前登录用户的主日历，请使用“primary”关键字。
可选的查询参数
conferenceDataVersion integer API 客户端支持的会议数据的版本号。版本 0 假定不支持会议数据，并忽略活动正文中的会议数据。版本 1 支持复制 ConferenceData，还支持使用 sessionData 的 createRequest 字段来创建新会议。默认值为 0。 可接受的值包括0到1（含 0 和 50000）。
supportsAttachments boolean 执行操作的 API 客户端是否支持事件附件。可选。默认值为 False。

授权

此请求需要获得以下至少一个范围的授权：

范围
https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.events

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

请求正文

在请求正文中，提供具有以下属性的 Events 资源：

属性名称 值 说明 备注
必需属性
end nested object 事件的（不含）结束时间。对于周期性活动，这是指第一次活动的结束日期。
iCalUID string RFC5545 中定义的事件唯一标识符。此属性用于在日历系统中对活动进行唯一标识，并且在通过 import 方法导入活动时必须提供。

请注意，iCalUID 和 id 并不相同，在创建事件时应仅提供其中一个。它们在语义上的一个区别在于，在周期性事件中，一个事件的所有出现都具有不同的 id，而它们都共享相同的 iCalUID。如需使用事件 iCalUID 检索事件，请使用 iCalUID 参数调用 events.list 方法。如需使用事件 id 检索事件，请调用 events.get 方法。
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 时区数据库名称，例如“欧洲/苏黎世”）。对于周期性活动，此字段是必填字段，用于指定重复周期对应的时区。对于单个活动，此字段是可选的，表示活动开始/结束的自定义时区。 可写入
extendedProperties.private object 此日历上显示的活动副本的专用属性。 可写入
extendedProperties.shared object 在其他参加者的活动副本之间共享的属性日历。 可写入
focusTimeProperties nested object 专注时间事件数据。当 eventType 为 focusTime 时使用。 可写入
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。 可写入
location string 事件的地理位置，以自由格式文本表示。可选。 可写入
organizer object 活动的组织者。如果组织者同时也是参加者，则 attendees 会通过一个单独的条目来指明这一点，并将 organizer 字段设为 True。要更改组织者，请使用移动操作。只读（导入事件时除外）。 可写入
organizer.displayName string 组织者的姓名（如果有）。 可写入
organizer.email string 组织者的电子邮件地址（如果有）。它必须是符合 RFC5322 规范的有效电子邮件地址。 可写入
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 此提醒使用的方法。可能的值包括：
  • “email”- 提醒通过电子邮件发送。
  • “popup”- 提醒通过 UI 弹出窗口发送。

添加提醒时必填。

 可写入
reminders.overrides[].minutes integer 在事件开始前多少分钟应触发提醒。有效值介于 0 到 40320 之间（4 周的分钟数）。

添加提醒时必填。

 可写入
reminders.useDefault boolean 日历的默认提醒是否适用于相应活动。 可写入
sequence integer 序号与 i 日历 相同。 可写入
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”- 事件已取消（删除）。只有在增量同步（指定了 syncToken 或 updatedMin）或 showDeleted 标志设置为 true 时，list 方法才会返回已取消的事件。get 方法始终会返回这些结果。

    已取消状态表示两种不同的状态，具体取决于事件类型：

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

      已取消的例外情况只能保证为 id、recurringEventId 和 originalStartTime 字段填充值。其他字段可能为空。

    2. 其他所有已取消的活动都代表已删除的活动。客户端应移除其本地同步的副本。此类已取消的活动最终会消失，因此请勿期望它们无限期提供。

      系统只能保证为已删除的事件填充 id 字段。

    在组织者的日历中，已取消的活动会继续显示活动详细信息（摘要、地点等），以便其可以恢复（取消删除）。同样，用户受邀参加以及用户手动移除的活动会继续提供详细信息。不过，showDeleted 设为 false 的增量同步请求不会返回这些详细信息。

    如果某个活动更改了其组织者（例如通过移动操作），并且原来的组织者不在参加者列表中，则会导致该活动已取消，且只保证填充 id 字段。

 可写入
summary string 活动的标题。 可写入
transparency string 相应活动是否屏蔽了日历上的时间。可选。可能的值包括：
  • “opaque”- 默认值。活动会在日历上阻止时间。这相当于在日历界面中将状态显示为设置为忙碌。
  • “transparent”- 该活动不会阻断日历上的时间。这相当于在日历界面中将状态显示为设置为有空。
 可写入
visibility string 活动的公开范围。可选。可能的值包括：
  • “default”- 使用日历上活动的默认公开范围。这是默认值。
  • “public”- 活动为公开活动，且日历的所有读者均可看到活动详情。
  • “private”- 该活动是私人活动，只有活动参加者才能查看活动详情。
  • “confidential”- 活动为私人活动。提供此值是为了确保兼容性。
 可写入

响应

如果成功，此方法将在响应正文中返回一项 Events 资源。

示例

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

Java

使用 Java 客户端库。

import com.google.api.services.calendar.Calendar;
import com.google.api.services.calendar.model.Event;
import com.google.api.services.calendar.model.EventAttendee;
import com.google.api.services.calendar.model.EventDateTime;
import com.google.api.client.util.DateTime;

import java.util.Date;
// ...

// Initialize Calendar service with valid OAuth credentials
Calendar service = new Calendar.Builder(httpTransport, jsonFactory, credentials)
    .setApplicationName("applicationName").build();

// Create and initialize a new event (could also retrieve an existing event)
Event event = new Event();
event.setICalUID("originalUID");

Event.Organizer organizer = new Event.Organizer();
organizer.setEmail("organizerEmail");
organizer.setDisplayName("organizerDisplayName");
event.setOrganizer(organizer);

ArrayList<EventAttendee> attendees = new ArrayList<EventAttendee>();
attendees.add(new EventAttendee().setEmail("attendeeEmail"));
// ...
event.setAttendees(attendees);

Date startDate = new Date();
Date endDate = new Date(startDate.getTime() + 3600000);
DateTime start = new DateTime(startDate, TimeZone.getTimeZone("UTC"));
event.setStart(new EventDateTime().setDateTime(start));
DateTime end = new DateTime(endDate, TimeZone.getTimeZone("UTC"));
event.setEnd(new EventDateTime().setDateTime(end));

// Import the event into a calendar
Event importedEvent = service.events().calendarImport('primary', event).execute();

System.out.println(importedEvent.getId());

Python

使用 Python 客户端库。

event = {
  'summary': 'Appointment',
  'location': 'Somewhere',
  'organizer': {
    'email': 'organizerEmail',
    'displayName': 'organizerDisplayName'
  },
  'start': {
    'dateTime': '2011-06-03T10:00:00.000-07:00'
  },
  'end': {
    'dateTime': '2011-06-03T10:25:00.000-07:00'
  },
  'attendees': [
    {
      'email': 'attendeeEmail',
      'displayName': 'attendeeDisplayName',
    },
    # ...
  ],
  'iCalUID': 'originalUID'
}

imported_event = service.events().import_(calendarId='primary', body=event).execute()

print imported_event['id']

PHP

使用 PHP 客户端库。

$event = new Google_Service_Calendar_Event();
$event->setSummary('Appointment');
$event->setLocation('Somewhere');
$start = new Google_Service_Calendar_EventDateTime();
$start->setDateTime('2011-06-03T10:00:00.000-07:00');
$event->setStart($start);
$end = new Google_Service_Calendar_EventDateTime();
$end->setDateTime('2011-06-03T10:25:00.000-07:00');
$event->setEnd($end);
$attendee1 = new Google_Service_Calendar_EventAttendee();
$attendee1->setEmail('attendeeEmail');
// ...
$attendees = array($attendee1,
                   // ...,
                  );
$event->attendees = $attendees;
$organizer = new Google_Service_Calendar_EventOrganizer();
$organizer->setEmail('organizerEmail');
$organizer->setDisplayName('organizerDisplayName');
$event->setOrganizer($organizer);
$event->setICalUID('originalUID');
$importedEvent = $service->events->import('primary', $event);

echo $importedEvent->getId();

Ruby

使用 Ruby 客户端库。

event = Google::Apis::CalendarV3::Event.new(
  summary: 'Appointment',
  location: 'Somewhere',
  organizer: {
    email: 'organizerEmail',
    display_name: 'organizerDisplayName'
  },
  start: {
    date_time: '2011-06-03T10:00:00.000-07:00'
  },
  end: {
    date_time: '2011-06-03T10:25:00.000-07:00'
  },
  attendees: [
    {
      email: 'attendeeEmail',
      display_name: 'attendeeDisplayName',
    },
    # ...
  ],
  i_cal_uid: 'originalUID'
)
result = client.import_event('primary', event)
print result.id

试试看！

使用下面的 API Explorer 对实际数据调用此方法，然后查看响应。