通过

Office 365 API 预览版中的日历 REST API

  • 项目

日历 API 提供了对 Exchange Online 中作为 Office 365 一部分的日历组、日历和事件的完全访问权限。日历 API 涵盖了从检查即将发生的事件到发送会议邀请的各方面。本文提供了您在应用程序中使用用户日历时需要了解的所有信息。

上次修改时间： 2014年10月28日

适用范围： Exchange Online | Office 365

本文内容
访问日历 API
CalendarGroup 实体
Calendar 实体
Event 实体
其他资源

您可以使用日历 API 中的 CalendarGroup、Calendar 和 Event 实体获取、创建、更新和删除日历组、日历及事件，并响应会议请求。

访问日历 API

要使用日历 API，您需要在 Microsoft Azure Active Directory 中使用适当的范围注册您的应用程序，并构建 REST 终结点 URL。

选择正确的范围

要使用日历 API，必须使用适当的范围注册您的应用程序。一般情况下，HTTP GET 用于检索项目，POST 用于创建新的项目，PATCH 用于更新项目，DELETE 用于删除项目。

备注

user_impersonation 作用域（在 Azure AD 管理门户中看起来具有用户邮箱(预览)的完全访问权限不是 Office 365 API 预览 的有效作用域。它设计为用于 EWS Managed API 和 Exchange Web Services (EWS)。

表 1. 日历范围值和相应访问权限

范围值

访问权限

Calendar.Read

允许 GET 请求。

Calendar.Write

允许 GET、POST、PATCH 和 DELETE 请求。

REST 终结点 URL

您通过对特定 URL 的 HTTP 请求访问日历 API。对所有日历 API 调用的基 URL 使用以下格式构建。

"https://" + SERVERNAME + "/EWS/OData"

SERVERNAME 是用作日历 API 的 REST 终结点的服务器的主机名；例如，"outlook.office365.com"。此服务器的名称可通过发现服务来找到。特定实体的有效地址会附加到基 URL 中；例如：https://outlook.office365.com/EWS/OData/Me/Calendar。

使用基 URL，您可以请求元数据文档，获取日历、邮件和联系人 API 支持的数据模型的完整表示形式。打开 Web 浏览器并输入基 URL，结尾附加"/$metadata"。服务器将返回描述 API 的元数据文档。

当您拥有了 REST 终结点 URL 并且您已使用适当的范围注册了您的应用程序，您就可以开始使用日历 API。

CalendarGroup 实体

日历组是组织多个日历的一种方式。用户可以使用 Outlook 或 Outlook Web App 将多个日历添加到一个日历组中。这样用户就可以更加简单快速地查看组中的所有日历。

获取日历组

所需范围：Calendar.Read 或 Calendar.Write

您可以通过 User 实体的 CalendarGroups 属性请求邮箱中所有的日历组（或使用 $filter OData 查询参数请求筛选的列表）。

GET https://outlook.office365.com/ews/odata/Me/CalendarGroups

还可以使用 CalendarGroup 实体的 Id 属性检索有关特定日历组的信息。

GET https://outlook.office365.com/ews/odata/Me/CalendarGroups(<calendargroup_id>)

服务器将返回日历组的 JSON 表示形式作为响应。

{
  "@odata.id": "https://outlook.office365.com/EWS/OData/Users('sadie@contoso.com')/CalendarGroups('AQMkAGI3...')",
  "@odata.editLink": "https://outlook.office365.com/EWS/OData/Users('sadie@contoso.com')/CalendarGroups('AQMkAGI3...')",
  "Id": "AQMkAGI3...",
  "Name": "My Calendars",
  "ChangeKey": "R9CVg8njOEeBFPLI1qvQugAAAAAI5A==",
  "ClassId": "0006f0b7-0000-0000-c000-000000000046",
  "Calendars@odata.navigationLink": "https://outlook.office365.com/EWS/OData/Users('sadie@contoso.com')/CalendarGroups('AQMkAGI3...')/Calendars"
    }

创建日历组

所需范围：Calendar.Write

您可以通过将带有 JSON 表示形式的 CalendarGroup 实体的 POST 请求发送给 User 实体的 CalendarGroups 属性，来创建日历组。

POST https://outlook.office365.com/ews/odata/Me/CalendarGroups

以下是请求正文。

{
  "@odata.type": "#Microsoft.Exchange.Services.OData.Model.CalendarGroup",
  "Name": <new_calendargroup_name>
}

成功的响应包含新日历组的 JSON 表示形式。

更新日历组

所需范围：Calendar.Write

您可以通过发送带有 JSON 有效负载（其中包含要更新的属性）的 PATCH 请求来更新日历组。Name 属性是 CalendarGroup 实体的唯一可写属性。

PATCH https://outlook.office365.com/ews/odata /Me/CalendarGroups(<calendargroup_id>)

以下是请求正文。

{
  "Name": <updated_calendargroup_name>
}

成功的响应包含已更新日历组的 JSON 表示形式。

删除日历组

所需范围：Calendar.Write

将 DELETE 请求发送给 CalendarGroup 实体的 URL 即可删除日历组。

DELETE https://outlook.office365.com/ews/odata/Me/CalendarGroups(<calendargroup_id>)

Calendar 实体

日历充当事件的容器。用户可以拥有多个日历，可将每个日历分配到一个日历组。

获取日历

所需范围：Calendar.Read 或 Calendar.Write

您可以通过 User 实体的 Calendars 属性请求所有用户的日历（或通过使用 $filter OData 查询参数请求筛选的列表），或通过 CalendarGroup 实体的 Calendars 属性仅在特定日历组中请求所有日历。

GET https://outlook.office365.com/ews/odata/Me/Calendars
GET https://outlook.office365.com/ews/odata/Me/CalendarGroups(<calendargroup_id>/Calendars

您还可以使用 Calendar 实体的 Id 属性检索有关特定日历的信息，或使用 User 实体的 Calendar 属性检索有关默认日历的信息。

GET https://outlook.office365.com/ews/odata/Me/Calendars(<calendar_id>)
GET https://outlook.office365.com/ews/odata/Me/Calendar

服务器将返回日历的 JSON 表示形式作为响应。

{
  "@odata.id": "https://outlook.office365.com/EWS/OData/Users('sadie@contoso.com')/Calendars('AQMkAGI3...')",
  "@odata.editLink": "https://outlook.office365.com/EWS/OData/Users('sadie@contoso.com')/Calendars('AQMkAGI3...')",
  "Id": "AQMkAGI3...",
  "Name": "Calendar",
  "ChangeKey": "R9CVg8njOEeBFPLI1qvQugAAAAAI5Q==",
  "Events@odata.navigationLink": "https://outlook.office365.com/EWS/OData/Users('sadie@contoso.com')/Calendars('AQMkAGI3...')/Events"
}

创建日历

所需范围：Calendar.Write

您可以将带有 JSON 表示形式的 Calendar 实体的 POST 请求发送给 User 实体的 Calendars 属性（在默认日历组中创建日历）或 CalendarGroup 实体的 Calendars 属性（在该日历组中创建日历），来创建日历。

POST https://outlook.office365.com/ews/odata/Me/Calendars
POST https://outlook.office365.com/ews/odata/Me/CalendarGroups(<calendargroup_id>)/Calendars

以下是请求正文。

{
  "@odata.type": "#Microsoft.Exchange.Services.OData.Model.Calendar",
  "Name": <new_calendar_name>
}

成功的响应包含新日历的 JSON 表示形式。

更新日历

所需范围：Calendar.Write

您可以通过发送带有 JSON 有效负载（其中包含要更新的属性）的 PATCH 请求来更新日历。Calendar 实体只有一个可写属性，即 Name 属性。

PATCH https://outlook.office365.com/ews/odata /Me/Calendars(<calendar_id>)

请求正文

{
  "Name": <updated_calendar_name>
}

成功的响应包含已更新日历的 JSON 表示形式。

删除日历

所需范围：Calendar.Write

将 DELETE 请求发送给 Calendar 实体的 URL 即可删除日历。

DELETE https://outlook.office365.com/ews/odata/Me/Calendars(<calendar_id>)

Event 实体

Event 实体表示用户日历上的约会或会议。

获取事件

所需范围：Calendar.Read 或 Calendar.Write

您可以通过 User 实体的 Events 属性请求所有日历的所有事件（或通过使用 $filter OData 查询参数请求筛选的列表），或通过 Calendar 实体的 Events 属性请求特定日历中的所有事件。

GET https://outlook.office365.com/ews/odata/Me/Events
GET https://outlook.office365.com/ews/odata/Me/Calendar/Events
GET https://outlook.office365.com/ews/odata/Me/Calendars(<calendar_id>)/Events

还可以使用 Event 实体的 Id 属性检索有关特定事件的信息。

GET https://outlook.office365.com/ews/odata/Me/Events(<event_id>)

服务器将返回事件的 JSON 表示形式作为响应。

{
  "@odata.id": "https://outlook.office365.com/EWS/OData/Users('sadie@contoso.com')/Events('AAMkAGI3...')",
  "@odata.editLink": "https://outlook.office365.com/EWS/OData/Users('sadie@contoso.com')/Events('AAMkAGI3...')",
  "Id": "AAMkAGI3...",
  "ChangeKey": "R9CVg8njOEeBFPLI1qvQugAABHL2eg==",
  "Subject": "Lunch",
  "BodyPreview": "Let's meet for lunch and go over the project plan.",
  "Body": {
    "ContentType": "HTML",
    "Content": "Let's meet for lunch and go over the project plan."
  },
  "Importance": "Normal",
  "Categories": [],
  "HasAttachments": false,
  "Start": "2014-02-13T20:30:00Z",
  "End": "2014-02-13T21:00:00Z",
  "Location": {
    "DisplayName": "Cafeteria"
  },
  "ShowAs": "Tentative",
  "IsAllDay": false,
  "IsCancelled": false,
  "IsOrganizer": false,
  "ResponseRequested": true,
  "Type": "SingleInstance",
  "SeriesId": null,
  "Attendees": [],
  "Recurrence": null,
  "Attachments@odata.navigationLink": "https://outlook.office365.com/EWS/OData/Users('sadie@contoso.com')/Events('AAMkAGI3...')/Attachments",
  "Calendar@odata.navigationLink": "https://outlook.office365.com/EWS/OData/Users('sadie@contoso.com')/Events('AAMkAGI3...')/Calendar"
}

创建事件

所需范围：Calendar.Write

您可以将带有 JSON 表示形式的 Event 实体的 POST 请求发送给 User 实体的 Events 属性（在默认日历中创建事件）或特定 Calendar 实体的 Events 属性（在该日历中创建事件），来创建事件。

POST https://outlook.office365.com/ews/odata/Me/Events
POST https://outlook.office365.com/ews/odata/Me/Calendars(<calendar_id>)/Events

请求正文可包含以下参数。

表 2.  创建事件参数

参数

可选项或必选项

@odata.type

必需

Subject

可选

Body

可选

Importance

可选

Categories

可选

Start

可选

End

可选

Location

可选

ShowAs

可选

IsAllDay

可选

ResponseRequested

可选

Attendees

可选

Recurrence

可选

以下是请求正文的示例。

{
  "@odata.type": "#Microsoft.Exchange.Services.OData.Model.Event",
  "Subject": "Discuss the Calendar REST API",
  "Body": {
    "ContentType": "HTML",
    "Content": "I think it will meet our requirements!"
  },
  "Start": "2014-07-02T18:00:00Z",
  "End": "2014-07-02T19:00:00Z",
  "Location": {
      "DisplayName": "Conference Room 1"
    },
  "ShowAs": "Busy",
  "Attendees": [
    {
      "Name": "Alex Darrow",
      "Address": "alexd@contoso.com",
      "Type": "Required"
    },
    {
      "Name": "Anne Wallace",
      "Address": "annew@contoso.com",
      "Type": "Optional"
    },
    {
      "Name": "Conference Room 1",
      "Address": "conf1@contoso.com",
      "Type": "Resource"
    }
  ]
}

成功的响应包含新事件的 JSON 表示形式。如果 Attendees 属性中包含任何参与者，服务器将向所有参与者发送会议请求。

更新事件

所需范围：Calendar.Write

要更新事件，可以向事件（带有包含要更新属性的 JSON 对象）的 URL 发送 PATCH 请求。只有包括在有效负载中的属性发生了更改。

PATCH https://outlook.office365.com/ews/odata/Me/Events(<event_id>)

请求正文至少包含创建参数列表中的一个可选参数。

以下是请求正文的示例。

{
  "Location": {
    "DisplayName": "Your office"
  }
}

成功的响应包含已更新事件的 JSON 表示形式。如果 Attendees 属性中包含任何参与者，且用户为组织者，服务器将向所有参与者发送会议更新。

删除约会

所需范围：Calendar.Write

您只需将 DELETE 请求发送到 Event 实体的 URL 即可删除约会。

DELETE https://outlook.office365.com/ews/odata/Me/Events(<event_id>)

一旦成功，约会将移动到用户的"已删除邮件"文件夹。如果约会为会议，会向所有参与者发送取消通知。

响应会议请求

所需范围：Mail.Write 和 Calendar.Write

要对用户收件箱中的会议请求做出响应，您需执行几个步骤。因为会议请求是 Message 实体，而非 Event 实体，会议请求没有可用操作直接接受、拒绝或暂时接受会议。要访问这些操作，您需要在日历中找到相应的 Event 实体。

现在我们来看一下这个与会议请求对应的示例 Message 实体。Message 实体通过使用邮件 REST API 进行访问。

{
  "@odata.id": "https://outlook.office365.com/EWS/OData/Users('sadie@contoso.com')/Messages('AAMkAGI3...')",
  "@odata.editLink": "https://outlook.office365.com/EWS/OData/Users('sadie@contoso.com')/Messages('AAMkAGI3...')",
  "Id": "AAMkAGI3...",
  "ChangeKey": "CwAAABYAAABH0JWDyeM4R4EU8sjWq9C6AAAEcqJz",
  "ClassName": "IPM.Schedule.Meeting.Request",
  "Subject": "Lunch",
  "BodyPreview": "Let's meet for lunch and go over the project plan.",
  "Body": {
    "ContentType": "HTML",
    "Content": "Let's meet for lunch and go over the project plan."
  },
  "Importance": "Normal",
  "Categories": [],
  "HasAttachments": false,
  "ParentFolderId": "AQMkAGIF...",
  "From": {
    "Name": "Hope Gross",
    "Address": "hope@contoso.com"
  },
  "Sender": {
    "Name": "Hope Gross",
    "Address": "hope@contoso.com"
  },
  "ToRecipients": [
    {
      "Name": "Sadie Daniels",
      "Address": "sadie@contoso.com"
    }
  ],
  "CcRecipients": [],
  "BccRecipients": [],
  "ReplyTo": [],
  "ConversationId": "AAQkAGI3...",
  "DateTimeReceived": "2014-02-12T21:57:00Z",
  "DateTimeSent": "2014-02-12T21:56:52Z",
  "IsDeliveryReceiptRequested": null,
  "IsReadReceiptRequested": false,
  "IsDraft": false,
  "IsRead": false,
  "EventId": "AAMkAGI4...",
  "MeetingMessageType": "MeetingRequest",
  "DateTimeCreated": "2014-02-12T21:56:59Z",
  "LastModifiedTime": "2014-02-12T21:57:00Z",
  "Attachments@odata.navigationLink": "https://outlook.office365.com/EWS/OData/Users('sadie@contoso.com')/Messages('AAMkAGI3...')/Attachments"
}

此实体包含两条重要信息。一是值为"MeetingRequest"的 MeetingMessageType 属性，它指示此邮件为会议请求。二是 EventId 属性，它提供了日历上对应 Event 实体的标识符。您可以使用此标识符访问事件并调用 Accept、Decline 或 Tentative 操作，以便向组织者发送回复并更新用户日历上的事件。以下请求示例接受会议并向组织者发送响应。请求包括值为"SendAndSaveCopy"的自定义查询选项 MessageDisposition，这将使响应保存在"已发送邮件"文件夹中。

POST https://outlook.office365.com/ews/odata/Me/Events(<event_id>)/Accept?MessageDisposition=<message_disposition>
POST https://outlook.office365.com/ews/odata/Me/Events(<event_id>)/Decline?MessageDisposition=<message_disposition>
POST https://outlook.office365.com/ews/odata/Me/Events(<event_id>)/Tentative?MessageDisposition=<message_disposition>

请求 URL 包括 MessageDisposition 查询选项，控制响应消息在发送后的处理方式。以下是可能的值：

  • "SendOnly" — 发送响应，不在"已发送邮件"文件夹中保存副本。

  • "SaveOnly" — 将响应保存在"草稿"文件夹中，不发送。

  • "SendAndSaveCopy" — 发送响应，并在"已发送邮件"文件夹中保存副本。

请求正文可以为空，也可以包括 Comment 参数，此参数用于在发送给组织者的响应中加入消息。

以下是请求正文的示例。

{
  "Comment": "I'll be there!"
}

最后一步是使用邮件 API 将会议请求从"收件箱"移动到"已删除邮件"。

事件附件

您可以使用 FileAttachment 和 ItemAttachment 实体轻松获取、添加、删除和更新约会的附件。

其他资源