请求
HTTP 请求
GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events
参数
参数名称 | 值 | 说明 |
---|---|---|
路径参数 | ||
calendarId |
string |
日历标识符。如需检索日历 ID,请调用 calendarList.list 方法。如果您想访问当前登录用户的主要日历,请使用“primary ”关键字。
|
可选的查询参数 | ||
alwaysIncludeEmail |
boolean |
已废弃且已忽略。 |
eventTypes |
string |
要返回的事件类型。可选。此参数可以重复多次,以返回不同类型的事件。如果未设置,则返回所有事件类型。
可接受的值包括:
|
iCalUID |
string |
指定要在响应中提供的 iCalendar 格式的活动 ID。可选。如果您想按活动的 i 日历 ID 搜索活动,则使用此方法。 |
maxAttendees |
integer |
响应中包含的参加者数量上限。如果参加者人数超过指定数量,则只返回参与者。可选。 |
maxResults |
integer |
一个结果页上返回的事件数上限。结果页面中的事件数量可能少于此值,或者根本没有事件数量(即使有更多事件与查询匹配)。系统可以通过响应中不为空的 nextPageToken 字段检测不完整的网页。默认值为 250 个事件。页面大小不得超过 2500 个事件。可选。
|
orderBy |
string |
结果中返回事件的顺序。可选。默认值为未指定的稳定顺序。
可接受的值包括:
|
pageToken |
string |
用于指定要返回的结果页面的令牌。可选。 |
privateExtendedProperty |
string |
以 propertyName=value 指定的扩展属性约束条件。仅匹配私有媒体资源。此参数可能会重复多次,以返回与所有给定约束条件匹配的事件。 |
q |
string |
自由文本搜索字词,用于在以下字段中查找与这些字词匹配的事件:
这些搜索字词还会将预定义关键字与工作地点、不在办公室和专注时间活动的所有显示标题翻译进行匹配。例如,搜索“办公室”或“局”会返回类型为 |
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 一起指定。这些是:
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 |
用户对此日历的访问角色。只读。可能的值包括:
|
|
defaultReminders[] |
list |
已通过身份验证的用户日历中的默认提醒。这些提醒会应用于此日历上所有不会明确覆盖它们的活动(即没有将 reminders.useDefault 设置为 True)。 |
|
defaultReminders[].method |
string |
此提醒所使用的提醒方法。可能的值包括:
添加提醒时必填。 |
可写入 |
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 对实际数据调用此方法,然后查看响应。