Events: list

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

请求

HTTP 请求

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

参数

参数名称 说明
路径参数
calendarId string 日历标识符。要检索日历 ID,请调用 calendarList.list 方法。如果您想访问当前登录的用户的主日历,请使用关键字“primary”。
可选的查询参数
alwaysIncludeEmail boolean 已废弃并忽略。
eventTypes string 要返回的事件类型。可选。此参数可以重复多次以返回不同类型的事件。默认值为 ["default", "focusTime", "outOfOffice"]

可接受的值为:
  • default”:常规活动。
  • focusTime”:专注时间活动。
  • 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

这些搜索字词还会将预定义的关键字与工作地点、不在办公室和专注时间活动的所有显示标题翻译进行匹配。例如,搜索“Office”或“Bureau”会返回 officeLocation 类型的工作地点事件,而搜索“外出”或“Abwesend”会返回“不在办公室”活动。可选。

sharedExtendedProperty string 已指定为 propertyName=value 的扩展属性限制条件。仅匹配共享属性。此参数可以重复多次,以返回与所有给定约束条件匹配的事件。
showDeleted boolean 结果中是否包含已删除的事件(status 等于“cancelled”)。如果 showDeletedsingleEvents 的值均为 False,则已取消的周期性活动(但不包含底层的周期性活动)实例将仍然包含在内。如果 showDeletedsingleEvents 的值均为 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

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

请求正文

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

响应

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

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