此页面由 Cloud Translation API 翻译。

Events: list

返回指定日历中的活动。立即试用或查看示例。

请求

HTTP 请求

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

参数

参数名称	值	说明
路径参数
`calendarId`	`string`	日历标识符。如需检索日历 ID，请调用 calendarList.list 方法。如果您想访问当前登录用户的主要日历，请使用“`primary`”关键字。
可选的查询参数
`alwaysIncludeEmail`	`boolean`	已废弃且已忽略。
`eventTypes`	`string`	要返回的事件类型。可选。此参数可以重复多次，以返回不同类型的事件。如果未设置，则返回所有事件类型。可接受的值包括： “`birthday`”：每年重复一次的特别全天活动。 “`default`”：常规事件。 “`focusTime`”：专注时间活动。 “`fromGmail`”：来自 Gmail 的活动。 “`outOfOffice`”：不在办公室的活动。 “`workingLocation`”：工作地点事件。
`iCalUID`	`string`	指定要在响应中提供的 iCalendar 格式的活动 ID。可选。如果您想按 iCalendar ID 搜索活动，请使用此字段。
`maxAttendees`	`integer`	响应中包含的参加者数量上限。如果参加者人数超过指定数量，则只返回参与者。可选。
`maxResults`	`integer`	一个结果页面中返回的事件数上限。即使有更多事件与查询匹配，结果页面中的事件数也可能少于此值，甚至可能为零。系统可以通过响应中不为空的 `nextPageToken` 字段检测不完整的网页。默认值为 250 个事件。页面大小不得超过 2500 个事件。可选。
`orderBy`	`string`	结果中返回事件的顺序。可选。默认值为未指定的稳定顺序。可接受的值包括： “`startTime`”：按开始日期/时间排序（升序）。只有在查询单个事件（即参数 `singleEvents` 为 True）时，此参数才可用 “`updated`”：按上次修改时间排序（升序）。
`pageToken`	`string`	用于指定要返回的结果页面的令牌。可选。
`privateExtendedProperty`	`string`	扩展属性约束条件，指定为 propertyName=value。仅匹配私有媒体资源。此参数可能会重复多次，以返回与所有给定约束条件匹配的事件。
`q`	`string`	自由文本搜索字词，用于在以下字段中查找与这些字词匹配的事件： `summary` `description` `location` 参加者的 `displayName` 参加者的 `email` 组织者的 `displayName` 组织者的 `email` `workingLocationProperties.officeLocation.buildingId` `workingLocationProperties.officeLocation.deskId` `workingLocationProperties.officeLocation.label` `workingLocationProperties.customLocation.label` 这些搜索字词还会与预定义关键字匹配，以查找工作地点、外出和专注时间活动的所有显示标题翻译。例如，搜索“办公室”或“局”会返回类型为 `officeLocation` 的工作地点事件，而搜索“外出”或“Abwesend”会返回外出事件。可选。
`sharedExtendedProperty`	`string`	扩展属性约束条件，指定为 propertyName=value。仅匹配共享的房源。此参数可能会重复多次，以返回与所有给定约束条件匹配的事件。
`showDeleted`	`boolean`	是否在结果中包含已删除的事件（`status` 等于“`cancelled`”）。如果 `showDeleted` 和 `singleEvents` 均为 False，系统仍会包含已取消的周期性活动实例（但不包括基础周期性活动）。如果 `showDeleted` 和 `singleEvents` 均为 True，则仅返回已删除事件的单个实例（但不返回底层周期性事件）。可选。默认值为 False。
`showHiddenInvitations`	`boolean`	是否在结果中包含已隐藏的邀请。可选。默认值为 False。
`singleEvents`	`boolean`	是否将周期性活动展开为实例，并仅返回单次性活动和周期性活动的实例，而不是底层周期性活动本身。可选。默认值为 False。
`syncToken`	`string`	从上一个列表请求的最后一页结果中返回的 `nextSyncToken` 字段中获取的令牌。这会使此列表请求的结果仅包含自那时起发生更改的条目。自上次列表请求之后删除的所有事件始终会出现在结果集中，并且不允许将 `showDeleted` 设置为 False。为了确保客户端状态的一致性，有几个查询参数不能与 `nextSyncToken` 一起指定。这些是： `iCalUID` `orderBy` `privateExtendedProperty` `q` `sharedExtendedProperty` `timeMin` `timeMax` `updatedMin` 所有其他查询参数应与初始同步相同，以避免出现未定义的行为。如果 `syncToken` 过期，服务器将返回 410 GONE 响应代码，客户端应清除其存储空间，并在不使用任何 `syncToken` 的情况下执行完整同步。详细了解增量同步。可选。默认是返回所有条目。
`timeMax`	`datetime`	用于过滤事件开始时间的上限（不包括该时间）。可选。默认情况下，不按开始时间过滤。必须是包含强制性时区偏移的 RFC3339 时间戳，例如 2011-06-03T10:00:00-07:00、2011-06-03T10:00:00Z。您可以提供毫秒数，但系统会忽略这些数值。如果设置了 `timeMin`，则 `timeMax` 必须大于 `timeMin`。
`timeMin`	`datetime`	要过滤的事件结束时间的下限（不含此时间）。可选。默认情况下，不会按结束时间过滤。必须是包含强制性时区偏移的 RFC3339 时间戳，例如 2011-06-03T10:00:00-07:00、2011-06-03T10:00:00Z。您可以提供毫秒数，但系统会忽略这些数值。如果设置了 `timeMax`，则 `timeMin` 必须小于 `timeMax`。
`timeZone`	`string`	响应中使用的时区。可选。默认值为日历的时区。
`updatedMin`	`datetime`	事件上次修改时间的下限（以 RFC3339 时间戳的形式），用于过滤条件。如果指定了此时间，则无论 `showDeleted` 如何，系统始终会包含自此时间起被删除的条目。可选。默认情况下，不会按上次修改时间过滤。

授权

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

范围
`https://www.googleapis.com/auth/calendar.readonly`
`https://www.googleapis.com/auth/calendar`
`https://www.googleapis.com/auth/calendar.events.readonly`
`https://www.googleapis.com/auth/calendar.events`
`https://www.googleapis.com/auth/calendar.app.created`
`https://www.googleapis.com/auth/calendar.events.freebusy`
`https://www.googleapis.com/auth/calendar.events.owned`
`https://www.googleapis.com/auth/calendar.events.owned.readonly`
`https://www.googleapis.com/auth/calendar.events.public.readonly`

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

请求正文

使用此方法时请勿提供请求正文。

响应

如果成功，此方法将返回采用以下结构的响应正文：

{
  "kind": "calendar#events",
  "etag": etag,
  "summary": string,
  "description": string,
  "updated": datetime,
  "timeZone": string,
  "accessRole": string,
  "defaultReminders": [
    {
      "method": string,
      "minutes": integer
    }
  ],
  "nextPageToken": string,
  "nextSyncToken": string,
  "items": [
    events Resource
  ]
}

属性名称	值	说明	备注
`kind`	`string`	集合类型（“`calendar#events`”）。
`etag`	`etag`	集合的 ETag。
`summary`	`string`	日历的标题。只读。
`description`	`string`	日历的说明。只读。
`updated`	`datetime`	日历的上次修改时间（采用 RFC3339 时间戳）。只读。
`timeZone`	`string`	日历的时区。只读。
`accessRole`	`string`	用户对此日历的访问权限角色。只读。可能的值包括： “`none`”- 用户无权访问。 “`freeBusyReader`”- 用户对有空/忙碌信息拥有读取权限。 “`reader`”- 用户对日历拥有读取权限。不公开活动会向拥有读者访问权限的用户显示，但活动详情将被隐藏。 “`writer`”- 用户对日历拥有读写权限。不公开活动会向具有创作者访问权限的用户显示，并且系统会显示活动详情。 “`owner`”- 用户拥有日历的所有权。此角色具有“Writer”角色的所有权限，还可以查看和操作 ACL。
`defaultReminders[]`	`list`	已通过身份验证的用户日历中的默认提醒。这些提醒适用于此日历中未明确替换它们的所有事件（即未将 `reminders.useDefault` 设置为 True）。
`defaultReminders[].method`	`string`	此提醒所使用的提醒方法。可能的值包括： “`email`”- 系统会通过电子邮件发送提醒。 “`popup`”- 通过界面弹出式窗口发送提醒。添加提醒时必填。	可写入
`defaultReminders[].minutes`	`integer`	提醒应在活动开始前多少分钟触发。有效值介于 0 到 40320（4 周，以分钟为单位）之间。添加提醒时必填。	可写入
`nextPageToken`	`string`	用于访问此结果的下一页的令牌。如果没有更多结果，则省略此字段，在这种情况下，系统会提供 `nextSyncToken`。
`items[]`	`list`	日历中的活动列表。
`nextSyncToken`	`string`	在稍后的时间点用于仅检索自此结果返回后发生更改的条目。如果还有其他结果，则省略此字段，并提供 `nextPageToken`。

示例

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

Java

使用 Java 客户端库。

import com.google.api.services.calendar.Calendar;
import com.google.api.services.calendar.model.Event;
import com.google.api.services.calendar.model.Events;

// ...

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

// Iterate over the events in the specified calendar
String pageToken = null;
do {
  Events events = service.events().list('primary').setPageToken(pageToken).execute();
  List<Event> items = events.getItems();
  for (Event event : items) {
    System.out.println(event.getSummary());
  }
  pageToken = events.getNextPageToken();
} while (pageToken != null);

Python

使用 Python 客户端库。

page_token = None
while True:
  events = service.events().list(calendarId='primary', pageToken=page_token).execute()
  for event in events['items']:
    print event['summary']
  page_token = events.get('nextPageToken')
  if not page_token:
    break

PHP

使用 PHP 客户端库。

$events = $service->events->listEvents('primary');

while(true) {
  foreach ($events->getItems() as $event) {
    echo $event->getSummary();
  }
  $pageToken = $events->getNextPageToken();
  if ($pageToken) {
    $optParams = array('pageToken' => $pageToken);
    $events = $service->events->listEvents('primary', $optParams);
  } else {
    break;
  }
}

Ruby

使用 Ruby 客户端库。

page_token = nil
begin
  result = client.list_events('primary', page_token: page_token)
  result.items.each do |e|
    print e.summary + "\n"
  end
  if result.next_page_token != page_token
    page_token = result.next_page_token
  else
    page_token = nil
  end
end while !page_token.nil?

试试看！

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