通过

获取事件

  • 项目

命名空间：microsoft.graph

重要

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

获取指定的 event 对象的属性和关系。

如果出现以下问题，应用可以在其他用户的日历中获取事件：

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

由于 事件 资源支持 扩展，因此还可以使用 GET 操作获取 事件 实例中的自定义属性和扩展数据。

此 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
委派（个人 Microsoft 帐户） Calendars.ReadBasic Calendars.Read
应用程序 Calendars.ReadBasic Calendars.Read

HTTP 请求

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

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

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

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

可选的查询参数

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

请求标头

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

请求正文

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

响应

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

示例

示例 1：获取指定的事件

请求

以下示例获取指定的事件。 它指定以下内容：

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

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

GET https://graph.microsoft.com/beta/me/events/AAMkAGIAAAoZDOFAAA=?$select=subject,body,bodyPreview,organizer,attendees,start,end,location,hideAttendees
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,hideAttendees)/$entity",
    "@odata.etag":"W/\"ZlnW4RIAV06KYYwlrfNZvQAAKGWwbw==\"",
    "id":"AAMkAGIAAAoZDOFAAA=",
    "iCalUId": "040000008200E00074=",
    "uid": "040000008200E00074C=",
    "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":"tentativelyAccepted",
                "time":"0001-01-01T00:00:00Z"
            },
            "proposedNewTime": {
                "start": {
                    "dateTime": "2019-08-16T12:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                },
                "end": {
                    "dateTime": "2019-08-16T14:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                }
            },
            "emailAddress":{
                "name":"Dana Swope",
                "address":"danas@contoso.com"
            }
        }
    ],
    "hideAttendees": false,
    "organizer":{
        "emailAddress":{
            "name":"Samantha Booth",
            "address":"samanthab@contoso.com"
        }
    }
}

示例 2：获取文本格式的 body 属性

请求

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

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

GET https://graph.microsoft.com/beta/me/events/AAMkAGI1AAAoZDOFAAA=?$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)/$entity",
    "@odata.etag":"W/\"ZlnW4RIAV06KYYwlrfNZvQAAKGWwbw==\"",
    "id":"AAMkAGI1AAAoZDOFAAA=",
    "iCalUId": "040000008200E00074=",
    "uid": "040000008200E00074C=",
    "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"
    }
}

示例 3：获取指定多个位置的事件

请求

以下示例演示如何获取指定多个位置的事件。 该请求指定返回特定属性的 $select 查询参数。

GET https://graph.microsoft.com/beta/me/events/AAMkADAGAADDdm4NAAA=?$select=subject,body,bodyPreview,organizer,attendees,start,end,location,locations

响应

以下示例显示了相应的响应。 locations 属性包括组织事件的 3 个地点的详细信息。

由于请求未指定任何 Prefer: outlook.timezone 或 Prefer: outlook.body-content-type 标头， 因此开始 和 结束 属性以默认 UTC 时区显示，并且正文采用默认 HTML 格式。

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#users('d1a2fae9-db66-4cc9-8133-2184c77af1b8')/events(subject,body,bodyPreview,organizer,attendees,start,end,location,locations)/$entity",
  "@odata.etag":"W/\"y53lbKh6jkaxHzFwGhgyxgAAw5zhug==\"",
  "id":"AAMkADAGAADDdm4NAAA=",
  "iCalUId": "040000008200E00074=",
  "uid": "040000008200E00074C=",
  "subject":"Plan summer company picnic",
  "bodyPreview":"Let's kick-start this event planning!",
  "body":{
    "contentType":"html",
    "content":"<html>\r\n<head>\r\n</head>\r\n<body>\r\nLet's kick-start this event planning!\r\n</body>\r\n</html>\r\n"
  },
  "start":{
    "dateTime":"2017-08-30T11:00:00.0000000",
    "timeZone":"UTC"
  },
  "end":{
    "dateTime":"2017-08-30T12:00:00.0000000",
    "timeZone":"UTC"
  },
  "location":{
    "displayName":"Conf Room 3; Fourth Coffee; Home Office",
    "locationType":"default",
    "uniqueId":"Conf Room 3; Fourth Coffee; Home Office",
    "uniqueIdType":"private"
  },
  "locations":[
    {
      "displayName":"Conf Room 3",
      "locationType":"default",
      "uniqueIdType":"unknown"
    },
    {
      "displayName":"Fourth Coffee",
      "locationType":"default",
      "uniqueId":"Fourth Coffee",
      "uniqueIdType":"private",
      "address":{
        "type":"unknown",
        "street":"4567 Main St",
        "city":"Redmond",
        "state":"WA",
        "countryOrRegion":"US",
        "postalCode":"32008"
      },
      "coordinates":{
        "latitude":47.672,
        "longitude":-102.103
      }
    },
    {
      "displayName":"Home Office",
      "locationType":"default",
      "uniqueIdType":"unknown"
    }
  ],
  "attendees":[
    {
      "type":"required",
      "status":{
        "response":"none",
        "time":"0001-01-01T00:00:00Z"
      },
      "emailAddress":{
        "name":"Dana Swope",
        "address":"DanaS@contoso.com"
      }
    },
    {
      "type":"required",
      "status":{
        "response":"none",
        "time":"0001-01-01T00:00:00Z"
      },
      "emailAddress":{
        "name":"Alex Wilber",
        "address":"AlexW@contoso.com"
      }
    }
  ],
  "organizer":{
    "emailAddress":{
      "name":"Adele Vance",
      "address":"AdeleV@contoso.com"
    }
  }
}

示例 4：展开系列母版事件

请求

以下示例演示如何展开包含异常和取消的重复序列的系列主事件。 该请求指定返回特定属性的 $select 查询参数。

GET https://graph.microsoft.com/beta/me/events/AAMkADAGAADDdm4NAAA=?$select=subject,start,end,occurrenceId,exceptionOccurrences,cancelledOccurrences&$expand=exceptionOccurrences

响应

GET 操作返回序列母版事件的选定属性。 具体而言，对于 exceptionOccurrences 集合中的事件，该操作返回 id 属性，以及适用的所选属性 (subject、 start、 end、 occurrenceId) 。 对于 cancelledOccurrences 集合中的事件，由于事件不再存在，因此操作仅返回其 occurrenceId 属性值。

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#users('d1a2fae9-db66-4cc9-8133-2184c77af1b8')/events(subject,start,end,occurrenceId,exceptionOccurrences,cancelledOccurrences)/$entity",
  "@odata.etag":"W/\"y53lbKh6jkaxHzFwGhgyxgAAw5zhug==\"",
  "id":"AAMkADAGAADDdm4NAAA=",
  "iCalUId": "040000008200E00074=",
  "uid": "040000008200E00074C=",
  "subject": "Daily stand-up",
  "cancelledOccurrences": [
     "OID.AAMkADAGAADDdm4NAAA=.2020-04-30",
     "OID.AAMkADAGAADDdm4NAAA=.2020-05-07",
     "OID.AAMkADAGAADDdm4NAAA=.2020-05-14"
    ],
  "occurrenceId": null,
    "start": {
        "dateTime": "2020-04-23T11:30:00.0000000",
        "timeZone": "UTC"
    },
  "end": {
        "dateTime": "2020-04-23T12:00:00.0000000",
        "timeZone": "UTC"
    },
  "exceptionOccurrences": [
        {
            "id": "AAMkADM0ZGRhMjdjLTA==",
            "Subject": "SM update 24",
            "occurrenceId": "OID.AAMkADAGAADDdm4NAAA=.2020-05-21",
            "start": {
                "dateTime": "2020-05-21T11:30:00.0000000",
                "timeZone": "UTC"
            },
            "end": {
                "dateTime": "2020-05-21T12:00:00.0000000",
                "timeZone": "UTC"
            }
        }
    ]
}

相关内容