列出事件

获取用户邮箱中的 event 对象列表。该列表包含单个实例会议和系列主控形状。

目前,此操作返回纯 HTML 格式的事件正文。

要获取扩展的事件实例,可以获取日历视图,或者获取事件的实例

获取其他用户的日历中的事件

如果你具有应用程序权限,或者具有某个用户的相应的委派权限,则可以获取其他用户的日历中的事件。 本部分重点介绍涉及委派权限的应用场景。

例如,你的应用已从用户 John 获得委派权限。 假设另一位用户 Garth 与 John 共享了一个日历。 可以通过在下面所示的查询示例中指定 Garth 的用户 ID(或者用户主体名称)来获取该共享日历中的事件。

GET /users/{Garth-id | Garth-userPrincipalName}/events

此功能适用于对单个用户执行的所有支持的 GET 事件操作,如下面的 HTTP 请求部分所示。 如果 Garth 将他的整个邮箱委派给 John,此功能同样适用。

如果 Garth 未与 John 共享他的日历,也未将他的邮箱委派给 John,那么在这些 GET 操作中指定 Garth 的用户 ID 或用户主体名称将返回错误。 在这种情况下,指定用户 ID 或用户主体名称只适用于获取已登录用户自己的日历中的事件,而此查询等效于使用 /me 快捷方式:

GET /me/events

此功能仅适用于以下资源的 GET 操作:

  • 共享联系人文件夹
  • 共享日历
  • 共享文件夹中的联系人和事件
  • 委派邮箱中的上述资源

此功能不适用于针对联系人、事件及其文件夹的其他操作。

支持不同时区

对于返回事件的所有 GET 操作,你可以使用 Prefer: outlook.timezone 标头在响应中指定事件开始和结束时间的时区。

例如,下面的 Prefer: outlook.timezone 标头将响应中的开始和结束时间设置为东部标准时间。

Prefer: outlook.timezone="Eastern Standard Time"

如果该事件是在不同的时区中创建的,则根据 Prefer 标头中指定的时区调整开始和结束时间。请查看此 列表 了解支持的时区名称。如果未指定 Prefer: outlook.timezone 标头,则返回用 UTC 表示的开始和结束时间。

可以使用事件资源中的 OriginalStartTimeZoneOriginalEndTimeZone 属性来查找创建事件时使用的时区。

权限

要调用此 API,需要以下权限之一。要了解详细信息,包括如何选择权限的信息,请参阅权限

权限类型 权限(从最低特权到最高特权)
委派(工作或学校帐户) Calendars.Read、Calendars.ReadWrite
委派(个人 Microsoft 帐户) Calendars.Read、Calendars.ReadWrite
应用程序 Calendars.Read、Calendars.ReadWrite

HTTP 请求

GET /me/events
GET /users/{id | userPrincipalName}/events

GET /me/calendar/events
GET /users/{id | userPrincipalName}/calendar/events

GET /me/calendars/{id}/events
GET /users/{id | userPrincipalName}/calendars/{id}/events

GET /me/calendargroup/calendars/{id}/events
GET /users/{id | userPrincipalName}/calendargroup/calendars/{id}/events

GET /me/calendargroups/{id}/calendars/{id}/events
GET /users/{id | userPrincipalName}/calendargroups/{id}/calendars/{id}/events

可选的查询参数

此方法支持 OData 查询参数 来帮助自定义响应。

请求标头

名称 类型 说明
Authorization string Bearer {token}。必需。
Prefer: outlook.timezone 字符串 事件在响应中的默认时区。可选。

请求正文

请勿提供此方法的请求正文。

响应

如果成功,此方法在响应正文中返回 200 OK 响应代码和 event 对象集合。

示例

请求

下面是一个请求示例。它指定以下内容:

  • 获取以太平洋标准时间格式返回的日期时间值的 Prefer: outlook.timezone 标头。
  • 返回特定属性的 $select 查询参数。如果没有 $select 参数,将返回所有事件属性。
GET https://graph.microsoft.com/v1.0/me/events?$select=subject,body,bodyPreview,organizer,attendees,start,end,location
Prefer: outlook.timezone="Pacific Standard Time"
响应

下面是一个响应示例。以默认的 HTML 格式返回 body 属性。

HTTP/1.1 200 OK
Content-type: application/json
Preference-Applied: outlook.timezone="Pacific Standard Time"
Content-length: 1932

{
    "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users('cd209b0b-3f83-4c35-82d2-d88a61820480')/events(subject,body,bodyPreview,organizer,attendees,start,end,location)",
    "value":[
        {
            "@odata.etag":"W/\"ZlnW4RIAV06KYYwlrfNZvQAAKGWwbw==\"",
            "id":"AAMkAGIAAAoZDOFAAA=",
            "subject":"Orientation ",
            "bodyPreview":"Dana, this is the time you selected for our orientation. Please bring the notes I sent you.",
            "body":{
                "contentType":"html",
                "content":"<html><head></head><body><p>Dana, this is the time you selected for our orientation. Please bring the notes I sent you.</p></body></html>"
            },
            "start":{
                "dateTime":"2017-04-21T10:00:00.0000000",
                "timeZone":"Pacific Standard Time"
            },
            "end":{
                "dateTime":"2017-04-21T12:00:00.0000000",
                "timeZone":"Pacific Standard Time"
            },
            "location":{
                "displayName":"Assembly Hall"
            },
            "attendees":[
                {
                    "type":"required",
                    "status":{
                        "response":"none",
                        "time":"0001-01-01T00:00:00Z"
                    },
                    "emailAddress":{
                        "name":"Samantha Booth",
                        "address":"samanthab@a830edad905084922E17020313.onmicrosoft.com"
                    }
                },
                {
                    "type":"required",
                    "status":{
                        "response":"none",
                        "time":"0001-01-01T00:00:00Z"
                    },
                    "emailAddress":{
                        "name":"Dana Swope",
                        "address":"danas@a830edad905084922E17020313.onmicrosoft.com"
                    }
                }
            ],
            "organizer":{
                "emailAddress":{
                    "name":"Samantha Booth",
                    "address":"samanthab@a830edad905084922E17020313.onmicrosoft.com"
                }
            }
        }
    ]
}