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

这些搜索字词还会将预定义的关键字与工作地点、“不在办公室”和“专注时间”活动的所有显示标题翻译进行匹配。例如，搜索“Office”或“Bureau”会返回类型为 officeLocation 的工作地点活动，而搜索“Out of office”或“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” - 用户拥有对日历的读取权限。私密活动将向拥有读取权限的用户显示，但活动详细信息将被隐藏。
  • “writerWithoutPrivateAccess” - 用户拥有对日历的读写权限。私密活动将向拥有 writerWithoutPrivateAccess 权限的用户显示，但活动详细信息将被隐藏。
  • “writer” - 用户拥有对日历的读写权限。私密活动将向拥有写入权限的用户显示，并且活动详细信息将可见。
  • “owner” - 用户拥有对日历的管理权限。此角色拥有写入角色的所有权限，并且还能够查看和修改其他用户的访问权限级别。
defaultReminders[] list 已通过身份验证的用户的日历上的默认提醒。这些提醒适用于此日历上所有未明确替换这些提醒的活动（即未将 reminders.useDefault 设置为 True）。
defaultReminders[].method string 此提醒使用的方法。可能的值为：
  • “email” - 系统会通过电子邮件发送提醒。
  • “popup” - 系统会通过界面弹出式窗口发送提醒。

添加提醒时是必需的。

 可写
defaultReminders[].minutes integer 提醒应在活动开始前多少分钟触发。有效值介于 0 到 40320 之间（以分钟为单位，相当于 4 周）。

添加提醒时是必需的。

 可写
nextPageToken string 用于访问此结果的下一页的令牌。如果没有更多结果，则省略此字段，在这种情况下，系统会提供 nextSyncToken。
items[] list 日历上的活动列表。
nextSyncToken string 稍后用于仅检索自返回此结果以来发生更改的条目的令牌。如果有更多结果，则省略此字段，在这种情况下，系统会提供 nextPageToken。

试试看！

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