创建活动

假设有一款应用可帮助用户查找最佳远足路线。通过将远足计划添加为日历活动，用户可以自动保持井然有序。Google 日历可帮助他们分享计划并提醒他们，让他们能够轻松无忧地做好准备。此外，得益于 Google 产品的无缝集成，Google Now 会提醒他们出发时间，Google 地图会引导他们准时到达会议地点。

本文介绍了如何创建日历活动并将其添加到用户的日历中。

添加活动

如需创建事件，请调用 events.insert() 方法，并至少提供以下参数：

• calendarId 是日历标识符，可以是用于创建活动的日历的电子邮件地址，也可以是特殊关键字 'primary'，后者将使用已登录用户的主日历。如果您不知道要使用的日历的电子邮件地址，可以查看 Google 日历 Web 界面的日历设置（“日历地址”部分），也可以在 calendarList.list() 调用的结果中查找。
• event 是要创建的事件，其中包含开始时间和结束时间等所有必要的详细信息。只有两个必填字段，即 start 和 end 时间。如需了解完整的事件字段，请参阅 event 参考文档。
  使用 start.dateTime 和 end.dateTime 字段指定定时事件。对于全天活动，请改用 start.date 和 end.date。

若要成功创建事件，您需要满足以下条件：

• 将 OAuth 范围设置为 https://www.googleapis.com/auth/calendar，以便您拥有对用户日历的修改权限。
• 确保已通过身份验证的用户对您提供的 calendarId 拥有日历写入权限（例如，通过为 calendarId 调用 calendarList.get() 并检查 accessRole）。

添加事件元数据

创建日历活动时，您可以选择添加活动元数据。如果您选择在创建时不添加元数据，则可以使用 events.update() 更新许多字段；不过，某些字段（例如事件 ID）只能在 events.insert() 操作期间设置。

位置

在“位置”字段中添加地址后，您可以使用以下功能：

“出发时间”或显示带路线的地图。

事件 ID

创建事件时，您可以选择自行生成事件 ID

符合我们的格式要求。这样，您就可以让本地数据库中的实体与 Google 日历中的活动保持同步。此外，如果操作在 Google 日历后端成功执行后在某个时间点失败，它还可以防止创建重复的活动。如果未提供事件 ID，服务器会为您生成一个。如需了解详情，请参阅事件 ID 参考文档。

参加者

您创建的活动会显示在以下各方的所有主要 Google 日历中：

您使用相同事件 ID 添加的参加者。如果您在插入请求中将 sendNotifications 设置为 true，则参加者也会收到活动的电子邮件通知。如需了解详情，请参阅包含多名参加者的活动指南。

以下示例演示了如何创建事件并设置其元数据：

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:"[e-mail]"},
    &calendar.EventAttendee{Email:"[e-mail]"},
  },
}

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)

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("[e-mail]"),
    new EventAttendee().setEmail("[e-mail]"),
};
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());

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.

const 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': '[e-mail]'},
    {'email': '[e-mail]'}
  ],
  'reminders': {
    'useDefault': false,
    'overrides': [
      {'method': 'email', 'minutes': 24 * 60},
      {'method': 'popup', 'minutes': 10}
    ]
  }
};

const request = gapi.client.calendar.events.insert({
  'calendarId': 'primary',
  'resource': event
});

request.execute(function(event) {
  appendPre('Event created: ' + event.htmlLink);
});

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.

const 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': '[e-mail]'},
    {'email': '[e-mail]'},
  ],
  '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);
});

PHP

$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' => '[e-mail]'),
    array('email' => '[e-mail]'),
  ),
  '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);

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': '[e-mail]'},
    {'email': '[e-mail]'},
  ],
  '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'))

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: '[e-mail]'
    ),
    Google::Apis::CalendarV3::EventAttendee.new(
      email: '[e-mail]'
    )
  ],
  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}"

向活动添加云端硬盘附件

您可以将 Google 云端硬盘文件（例如文档中的会议备注、表格中的预算、幻灯片中的演示文稿，或任何其他相关的 Google 云端硬盘文件）附加到日历活动中。您可以在使用 events.insert() 或更高版本创建事件时，在更新（例如使用 events.patch()）过程中添加附件

将 Google 云端硬盘文件附加到活动的步骤分为两部分：

1. 从 Drive API 文件资源中获取文件 alternateLink 网址、title 和 mimeType，通常使用 files.get() 方法。
2. 在请求正文中设置 attachments 字段，并将 supportsAttachments 参数设置为 true，以创建或更新事件。

以下代码示例演示了如何更新现有事件以添加附件：

Java

public static void addAttachment(Calendar calendarService, Drive driveService, String calendarId,
    String eventId, String fileId) throws IOException {
  File file = driveService.files().get(fileId).execute();
  Event event = calendarService.events().get(calendarId, eventId).execute();

  List<EventAttachment> attachments = event.getAttachments();
  if (attachments == null) {
    attachments = new ArrayList<EventAttachment>();
  }
  attachments.add(new EventAttachment()
      .setFileUrl(file.getAlternateLink())
      .setMimeType(file.getMimeType())
      .setTitle(file.getTitle()));

  Event changes = new Event()
      .setAttachments(attachments);
  calendarService.events().patch(calendarId, eventId, changes)
      .setSupportsAttachments(true)
      .execute();
}

PHP

function addAttachment($calendarService, $driveService, $calendarId, $eventId, $fileId) {
  $file = $driveService->files->get($fileId);
  $event = $calendarService->events->get($calendarId, $eventId);
  $attachments = $event->attachments;

  $attachments[] = array(
    'fileUrl' => $file->alternateLink,
    'mimeType' => $file->mimeType,
    'title' => $file->title
  );
  $changes = new Google_Service_Calendar_Event(array(
    'attachments' => $attachments
  ));

  $calendarService->events->patch($calendarId, $eventId, $changes, array(
    'supportsAttachments' => TRUE
  ));
}

Python

def add_attachment(calendarService, driveService, calendarId, eventId, fileId):
    file = driveService.files().get(fileId=fileId).execute()
    event = calendarService.events().get(calendarId=calendarId,
                                         eventId=eventId).execute()

    attachments = event.get('attachments', [])
    attachments.append({
        'fileUrl': file['alternateLink'],
        'mimeType': file['mimeType'],
        'title': file['title']
    })

    changes = {
        'attachments': attachments
    }
    calendarService.events().patch(calendarId=calendarId, eventId=eventId,
                                   body=changes,
                                   supportsAttachments=True).execute()

重要提示： 如果您要向在本地存储事件的现有应用中添加附件支持，则必须先对所有事件执行完整同步，然后才能为事件修改启用 supportsAttachments 参数。如果您不先执行同步，可能会无意中从用户的活动中移除现有附件。

向活动添加视频和电话会议

您可以将活动与 Hangouts 和 Google Meet 会议相关联，以便用户通过电话或视频通话远程会议。

conferenceData 字段可用于读取、复制和清除现有会议详细信息；还可用于请求生成新会议。如需允许创建和修改会议详情，请将 conferenceDataVersion 请求参数设置为 1。

目前支持三种类型的 conferenceData，分别用 conferenceData.conferenceSolution.key.type 表示：

1. 面向个人的 Hangouts (eventHangout)
2. 面向 Google Workspace 用户的传统版 Hangouts（已废弃；eventNamedHangout）
3. Google Meet (hangoutsMeet)

您可以查看 calendars 和 calendarList 集合中的 conferenceProperties.allowedConferenceSolutionTypes，了解用户的任何给定日历支持哪些会议类型。您还可以通过检查 settings 集合中的 autoAddHangouts 设置，了解用户是否希望为其所有新创建的活动创建 Hangouts。

除了 type 之外，conferenceSolution 还提供 name 和 iconUri 字段，您可以使用这些字段来表示会议解决方案，如下所示：

JavaScript

const solution = event.conferenceData.conferenceSolution;

const content = document.getElementById("content");
const text = document.createTextNode("Join " + solution.name);
const icon = document.createElement("img");
icon.src = solution.iconUri;

content.appendChild(icon);
content.appendChild(text);

您可以为活动创建新的会议，方法是向 createRequest 提供新生成的 requestId（可以是随机的 string）。会议是异步创建的，但您可以随时查看请求状态，以便让用户了解最新动态。

例如，如需为现有事件请求生成会议，请执行以下操作：

JavaScript

const eventPatch = {
  conferenceData: {
    createRequest: {requestId: "7qxalsvy0e"}
  }
};

gapi.client.calendar.events.patch({
  calendarId: "primary",
  eventId: "7cbh8rpc10lrc0ckih9tafss99",
  resource: eventPatch,
  sendNotifications: true,
  conferenceDataVersion: 1
}).execute(function(event) {
  console.log("Conference created for event: %s", event.htmlLink);
});

对此调用的立即响应可能尚不包含完全填充的 conferenceData；这由 status 字段中的状态代码 pending 表示。填充会议信息后，状态代码会更改为 success。entryPoints 字段包含有关用户可以拨打哪些视频和电话 URI 的信息。

如果您想安排多个具有相同会议详细信息的日历活动，可以将整个 conferenceData 从一个活动复制到另一个活动。

在某些情况下，复制非常有用。例如，假设您正在开发一个招聘应用，该应用会为候选人和面试官分别设置事件。您希望保护面试官的身份，但也希望确保所有参与者加入同一电话会议。

重要提示： 如果您要向本地存储事件的现有应用中添加会议支持，则必须先对所有事件执行完整同步，然后才能启用会议数据支持（通过将 conferenceDataVersion 请求参数设置为 1 来修改事件）。如果您不先执行同步，可能会无意中从用户的活动中移除现有会议。