通过

列出事件

  • 项目

命名空间：microsoft.graph

重要

Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用，请使用 版本 选择器。

从用户的默认日历或指定的日历获取事件对象列表。 该列表包含单实例会议和系列主控事件。

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

在以下两种情况下，应用程序可以获取其他用户的日历中的事件：

  • 如果该应用程序具有应用程序权限，或者
  • 如果应用程序具有来自某个用户的相应委派权限，而另一个用户与该用户共享了日历，或者已为该用户授予委派的访问权限。 请参阅详细信息和示例。

此 API 可用于以下国家级云部署。

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国
✅ ✅ ✅ ✅

支持不同时区

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

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

Prefer: outlook.timezone="Eastern Standard Time"

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

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

权限

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

权限类型 权限（从最低特权到最高特权）
委派（工作或学校帐户） Calendars.ReadBasic、Calendars.Read、Calendars.ReadWrite
委派（个人 Microsoft 帐户） Calendars.ReadBasic、Calendars.Read、Calendars.ReadWrite
应用程序 Calendars.ReadBasic、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/calendarGroups/{id}/calendars/{id}/events
GET /users/{id | userPrincipalName}/calendarGroups/{id}/calendars/{id}/events

可选的查询参数

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

注意

不能使用 $filter 参数来筛选 定期 属性。

请求标头

名称 类型 说明
Authorization string 持有者 {token}。 必填。 详细了解 身份验证和授权。
Prefer: outlook.timezone string 此选项可用于指定响应中开始时间和结束时间的时区。 如果未指定，返回的这些时间值采用 UTC 时区。 可选。
Prefer: outlook.body-content-type string 要返回的 body 属性的格式。 可取值为“text”或“html”。 如果指定此 Preference-Applied 头，返回 Prefer 头作为证明。 如果未指定此头，采用 HTML 格式返回 body 属性。 可选。

请求正文

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

响应

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

示例

示例 1：获取所有用户的事件

第一个示例获取用户的所有事件。 它指定以下内容：

  • 获取以太平洋标准时间格式返回的日期时间值的 Prefer: outlook.timezone 标头。
  • 用于 $select 返回特定属性的查询参数。 如果没有 $select 参数，将返回所有事件属性。

该请求未指定任何 Prefer: outlook.body-content-type 标头来指示返回的事件正文的特定格式。

请求

GET https://graph.microsoft.com/beta/me/events?$select=subject,body,bodyPreview,organizer,attendees,start,end,location
Prefer: outlook.timezone="Pacific Standard Time"

响应

以下示例显示了相应的响应。 由于未指定任何 Prefer: outlook.body-content-type 标头，将以默认 HTML 格式返回 body 属性。

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

{
    "@odata.context":"https://graph.microsoft.com/beta/$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",
                "locationType": "default",
                "uniqueId": "Assembly Hall",
                "uniqueIdType": "private"
            },
            "locations": [
                {
                    "displayName": "Assembly Hall",
                    "locationType": "default",
                    "uniqueIdType": "unknown"
                }
            ],
            "attendees":[
                {
                    "type":"required",
                    "status":{
                        "response":"none",
                        "time":"0001-01-01T00:00:00Z"
                    },
                    "emailAddress":{
                        "name":"Samantha Booth",
                        "address":"samanthab@contoso.com"
                    }
                },
                {
                    "type":"required",
                    "status":{
                        "response":"none",
                        "time":"0001-01-01T00:00:00Z"
                    },
                    "emailAddress":{
                        "name":"Dana Swope",
                        "address":"danas@contoso.com"
                    }
                }
            ],
            "organizer":{
                "emailAddress":{
                    "name":"Samantha Booth",
                    "address":"samanthab@contoso.com"
                }
            }
        }
    ]
}

示例 2：获取消息的正文属性

以下示例演示如何使用 Prefer: outlook.body-content-type="text" 标头获取文本格式的指定邮件的 正文 属性。

该请求还使用 $select 查询参数返回特定属性。 如果没有 $select 参数，将返回所有事件属性。

请求

GET https://graph.microsoft.com/beta/me/events?$select=subject,body,bodyPreview
Prefer: outlook.body-content-type="text"

响应

以下示例显示了相应的响应。 以文本格式返回 body 属性。

HTTP/1.1 200 OK
Content-type: application/json
Preference-Applied: outlook.body-content-type="text"

{
    "@odata.context":"https://graph.microsoft.com/beta/$metadata#users('cd209b0b-3f83-4c35-82d2-d88a61820480')/events(subject,body,bodyPreview)",
    "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":"text",
                "content":"Dana, this is the time you selected for our orientation. Please bring the notes I sent you.\r\n"
            }
        }
    ]
}