使用Microsoft图形 API处理日历和事件

2025-01-30

Microsoft Graph 日历 API 提供日历、 calendarGroup、事件和其他资源，使你能够创建事件和会议、查找可行的会议时间、管理与会者等。使用日历 API，可以生成各种日历数据体验。

管理事件和会议

事件类型表示日历上的计划事件，例如会议、假日或时间块。会议（如团队会议或一对一会议）均由事件资源表示。可以通过直接创建、取消和删除事件以及其他操作来直接管理事件生命周期。此外，还可以创建草稿事件消息、发送消息、转发消息以及创建草稿回复等。通过处理事件消息，用户可以在创建事件和会议时发挥积极作用。还可以让他们与会议发起人、其他收件人和与会者通信。

直接处理事件

Microsoft图形 API提供了创建、更新、删除和取消事件等操作的方法。下表列出了一些常见的生命周期事件用例以及Microsoft Graph 提供的用于处理这些用例的 API。

用例	谓词	示例 URL
创建事件。	POST	/users/{id \| userPrincipalName}/events
从日历中删除事件。	DELETE	/users/{id \| userPrincipalName}/events/{id}
取消事件并发送取消消息。注意：在请求正文中指定可选的取消消息。	POST	/users/{id \| userPrincipalName}/events/{id}/cancel
更新事件。注意：指定要在请求正文中更新的事件详细信息。	PATCH	/users/{id \| userPrincipalName}/events/{id}
接受事件。	POST	/users/{id \| userPrincipalName}/events/{id}/accept
暂时接受事件。	POST	/users/{id \| userPrincipalName}/events/{id}/tentativelyAccept
拒绝事件。	POST	/users/{id \| userPrincipalName}/events/{id}/decline
关闭事件提醒。	POST	/users/{id \| userPrincipalName}/events/{id}/dismissReminder
暂停事件提醒。	POST	/users/{id \| userPrincipalName}/events/{id}/snoozeReminder

使用事件消息

eventMessage 资源是一种抽象类型，表示会议请求、取消和响应。当邮件收件人接受、暂时接受或拒绝请求时，将生成响应。处理 eventMessageRequest 和 eventMessageResponse 会在其生命周期内移动事件。日历 API 中的消息传递 API 支持 MIME 和 JSON 内容。

下表列出了一些常见的事件消息用例以及使用这些用例的 API。

用例	谓词	示例 URL
发送现有草稿邮件。	POST	/users/{id \| userPrincipalName}/messages/{id}/send
创建草稿答复。	POST	/users/{id \| userPrincipalName}/messages/{id}/createReply
回复事件消息。	POST	/users/{id \| userPrincipalName}/messages/{id}/reply
创建草稿答复全部邮件。	POST	/users/{id \| userPrincipalName}/messages/{id}/createReplyAll
在事件消息中回复所有内容。	POST	/users/{id \| userPrincipalName}/messages/{id}/replyAll
创建草稿转发。	POST	/users/{id \| userPrincipalName}/messages/{id}/createForward
转发事件消息。	POST	/users/{id \| userPrincipalName}/messages/{id}/forward

添加和删除附件

抽象附件类型用作附加到事件、邮件和帖子的文件、项目和引用的基础。例如，可以使用 List attachments 方法查看事件的附件。可以使用 Delete attachment 方法删除附件。组日历中的事件不支持附件。

附件类型

fileAttachment、itemAttachment 和 referenceAttatchment 类型表示可附加到日历项目的三种项目。 itemAttachment 对象表示直接附加到用户事件、消息或帖子的联系人、事件或消息。 fileAttachment 表示直接附加的文件。 referenceAttachment 表示位于 OneDrive for work 或 school 云驱动器或其他受支持的存储位置上的项，例如Word文档或文本文件。例如，若要查看事件的所有附件，可以使用 GET /users/{id | userPrincipalName}/events/{id}/attachments 终结点。

上传附件

可以使用 Add attachment 方法直接将大小小于 3 MB 的附件上传到用户的事件。但是，对于大于 3 MB 的附件，必须使用附件：createUploadSession 方法获取用于迭代上传附件的上传 URL。

使用日历、日历组和 Outlook 类别

使用日历 API，可以创建、读取、更新和删除日历，创建和查看日历事件，获取用户的忙/闲信息，以及查找建议的会议时间。

日历 API 提供对日历和日历组进行操作的方法。下表显示了所选 URL 的一些用例。

注意：下表中显示的许多方法都具有相关用例的其他 URL。例如，若要更新特定日历组中的用户日历，请使用 URL /users/{id | userPrincipalName}/calendarGroups/{id}/calendars/{id}发送 PATCH 操作。

用例	谓词	示例 URL
列出用户的日历。	GET	/users/{id \| userPrincipalName}/calendars
列出组中用户的日历。	GET	/users/{id \| userPrincipalName}/calendarGroups/{calendarGroupId}/calendars
创建日历。	POST	/users/{id \| userPrincipalName}/calendars
获取日历。	GET	/users/{id \| userPrincipalName}/calendars/{id}
更新日历。	PATCH	/users/{id \| userPrincipalName}/calendars/{id}
删除日历。	DELETE	/users/{id \| userPrincipalName}/calendars/{id}
创建日历组。	POST	/users/{id \| userPrincipalName}/calendarGroups
获取日历组。	GET	/users/{id \| userPrincipalName}/calendarGroups/{id}
更新日历组。	PATCH	/users/{id \| userPrincipalName}/calendarGroups/{id}
删除日历组。	DELETE	/users/{id \| userPrincipalName}/calendarGroups/{id}

忙/闲数据和会议时间

日历的两个核心功能是查找忙/闲信息并查找会议时间，以便安排会议。日历 API 提供获取忙/闲计划方法，该方法返回一段时间内的 scheduleInformation 对象的集合以及用户、资源或通讯组列表的集合。你可以向用户显示此信息，以便他们可以手动选择安排会议的适当时间。使用用户：findMeetingTimes 方法获取 meetingTimeSuggestionResult ，其中包含一组 meetingTimeSuggestion 对象，这些对象表示有关建议的会议时间的详细信息的参与者和发送的约束。

Outlook 类别

日历类别是说明和 categoryColor 的组合，共同定义 Outlook 项目的类别并控制 Outlook 显示项目的方式。 Outlook 用户可以按类别对邮件和事件进行分组。有关详细信息，请参阅 outlookCategory。

日历权限

当用户从 Outlook 客户端中与其他用户共享日历时，他们可以控制收件人可以查看或编辑的日历项目。 calendarPermissions 关系包含用户与其共享日历的每个用户的权限。例如，使用此关系可以查看哪些用户可以查看所有者的忙/闲信息、查看所有日历信息或编辑日历上的事件。

使用打开的扩展和扩展属性

开放扩展（以前称为 Office 365 数据扩展插件）表示存储和访问用户邮箱中资源的自定义数据的首选方式。如果 outlook MAPI 属性在Microsoft图形 API元数据中不可用，则可以回退到 Outlook 扩展属性。有关详细信息，请参阅 Outlook 扩展属性概述。

后续步骤

Microsoft Graph 中的日历 API 允许使用日历数据构建一系列体验。若要了解详细信息：

深入了解对方案最有帮助的资源的方法和属性。
尝试在 Graph 浏览器中调用 API。