在 Outlook 外接程序中实现共享文件夹和共享邮箱方案
本文介绍如何在 Outlook 外接程序中实现共享文件夹 (也称为委托访问) 和共享邮箱方案，包括 Office JavaScript API 支持的权限。
支持的客户端和平台
下表显示了此功能支持的客户端-服务器组合，包括所需的最低累积更新（如果适用）。 不支持排除的组合。
| 客户端 | Exchange Online | Exchange 2019 本地 (累积更新 1 或更高版本) |
Exchange 2016 本地 (累积更新 6 或更高版本) |
|---|---|---|---|
| Web 浏览器 (新式 Outlook UI) | 支持 | 不适用 | 不适用 |
| Web 浏览器 (经典 Outlook UI) | 不适用 | 不适用 | 不适用 |
| 新的 Outlook on Windows | 支持 | 不适用 | 不适用 |
|
Windows (经典) 共享文件夹：版本 1910 (内部版本 12130.20272) 或更高版本 共享邮箱：版本 2304 (内部版本 16327.20248) 或更高版本 |
支持 | 支持* | 支持* |
|
Mac 版本 16.47 或更高版本 |
支持 | 支持 | 支持 |
注意
* 从经典 Outlook on Windows 版本 2206 (内部版本 15330.20000) 当前频道和版本 2207 (每月企业频道内部版本 15427.20000) 开始，在本地 Exchange 环境中支持此功能。
支持的设置
以下部分介绍共享邮箱和共享文件夹支持的配置。 功能 API 在其他配置中可能无法按预期工作。 选择要了解如何配置的平台。
共享文件夹
邮箱所有者必须首先提供对代理人的访问权限。
若要提供代表邮箱所有者管理会议和会议响应的权限，请参阅 Outlook 网页版 中的日历委派。
若要提供代表邮箱所有者管理收件箱和日历的权限，必须通过以下选项之一配置访问权限。
邮箱所有者可以通过经典 Outlook on Windows 配置访问权限。 若要了解详细信息，请参阅 允许其他人管理你的邮件和日历。
管理员可以通过Microsoft 365 管理中心配置访问权限。 若要了解详细信息，请参阅 向另一Microsoft 365 用户授予邮箱权限。
管理员可以通过 Exchange 管理中心配置访问权限。 若要了解详细信息，请参阅 管理收件人的权限。
提供访问权限后，代理必须按照访问其他人的邮箱一文的“在 Outlook Web App 中将其他人的邮箱添加到文件夹列表”部分中概述的说明进行操作。
共享邮箱
共享邮箱允许一组用户使用共享电子邮件地址轻松监视和发送邮件和会议邀请。
在Outlook 网页版中，共享邮箱可以在与用户主邮箱相同的面板中打开，也可以在单独的浏览器选项卡或窗口中打开。 有关指导，请参阅在 Outlook 网页版 中打开和使用共享邮箱。
注意
在 Outlook 网页版中，如果使用“打开其他邮箱”选项在单独的浏览器选项卡或窗口中打开共享邮箱，则从邮箱访问加载项时可能会遇到问题。 建议改为在主邮箱所在的同一面板中打开邮箱。 这可确保外接程序在共享邮箱中按预期工作。
如果希望使用“ 打开另一个邮箱 ”选项打开共享邮箱，我们建议将加载项部署到主要用户和共享邮箱。
在新 Outlook on Windows 中，共享邮箱将添加到文件夹窗格的 “与我共享 ”部分。 有关指导，请参阅 在 Outlook 中打开和使用共享邮箱。
若要详细了解加载项一般在何处执行和不激活，请参阅 Outlook 外接程序概述页的 “可用于加载项的邮箱项目 ”部分。
配置清单
若要在外接程序中实现共享文件夹和共享邮箱方案，必须先在清单中配置对该功能的支持。 标记因外接程序使用的清单类型而异。
将其他对象添加到“authorization.permissions.resourceSpecific”数组，并将其“name”属性设置为“Mailbox.SharedFolder”。
"authorization": {
"permissions": {
"resourceSpecific": [
...
{
"name": "Mailbox.SharedFolder",
"type": "Delegated"
},
]
}
},
确定文件夹或邮箱是否共享
在共享文件夹或共享文件夹邮箱中运行操作之前，必须先确定当前文件夹或邮箱是共享的。 若要确定这一点，请在撰写或阅读模式下对邮件或约会调用 Office.context.mailbox.item.getSharedPropertiesAsync 。 如果项目位于共享文件夹或共享邮箱中，该方法将返回一个 SharedProperties 对象，该对象提供用户的权限、所有者的电子邮件地址、REST API 的基 URL 和目标邮箱的位置。
以下示例调用 getSharedPropertiesAsync 方法以标识邮箱的所有者以及委托或共享邮箱用户的权限。
Office.context.mailbox.item.getSharedPropertiesAsync((result) => {
if (result.status === Office.AsyncResultStatus.Failed) {
console.error("The current folder or mailbox isn't shared.");
return;
}
const sharedProperties = result.value;
console.log(`Owner: ${sharedProperties.owner}`);
console.log(`Permissions: ${sharedProperties.delegatePermissions} `);
});
支持的权限
下表描述了支持代理和共享邮箱用户的权限 getSharedPropertiesAsync 。
| 权限 | 值 | 说明 |
|---|---|---|
| 阅读 | 1 (000001) | 可以读取项。 |
| 写入 | 2 (000010) | 可以创建项。 |
| DeleteOwn | 4 (000100) | 只能删除他们创建的项。 |
| DeleteAll | 8 (001000) | 可以删除任何项目。 |
| EditOwn | 16 (010000) | 只能编辑他们创建的项。 |
| EditAll | 32 (100000) | 可以编辑任何项目。 |
注意
目前，API 支持获取现有权限，但不支持设置权限。
delegatePermissions 属性返回的 DelegatePermissions 枚举是使用位掩码来指示权限来实现的。 位掩码中的每个位置都表示一个特定权限，如果将其设置为 1，则用户具有相应的权限。 例如，如果右侧的第二位是 1，则用户具有 写入 权限。
以代理人或共享邮箱用户身份执行操作
确定当前邮件项目位于共享文件夹或共享文件夹邮箱中后，加载项就可以对共享环境中的项目执行必要的操作。 若要对共享上下文中的项运行操作，必须先在清单中配置加载项的权限。 然后，使用 Microsoft Graph 完成操作。
注意
共享文件夹和共享邮箱方案中不支持 Exchange Web Services (EWS) 。
配置加载项的权限
若要使用 Microsoft Graph 服务，外接程序必须在其清单中配置 读/写邮箱 权限。 标记因外接程序使用的清单类型而异。
- Microsoft 365 的统一清单：将“authorization.permissions.resourceSpecific”数组中对象的“name”属性设置为“Mailbox.ReadWrite.User”。
- 仅外接程序清单：将 Permissions 元素设置为 ReadWriteMailbox。
使用 Microsoft Graph
若要实现共享文件夹和共享邮箱方案，请使用 Microsoft Graph 访问其他邮箱信息和资源。 例如，可以使用 Microsoft Graph 获取 Outlook 邮件的内容，该邮件附加到 用户具有代理访问权限的邮箱中的邮件。 有关如何使用 Microsoft Graph 的指南，请参阅 Microsoft Graph 中的 Microsoft Graph 和 Outlook 邮件 API 概述。
提示
若要从外接程序访问 Microsoft Graph API，请使用 MSAL.js 嵌套应用身份验证 (NAA) 。 若要了解详细信息，请参阅 使用嵌套应用身份验证在 Office 外接程序中启用 SSO (预览版) 。
限制
根据加载项的方案，在处理共享文件夹或共享邮箱情况时，需要考虑一些限制。
消息Compose模式
在消息Compose模式下，Outlook 网页版或 Windows (新) 和经典) 不支持 getSharedPropertiesAsync，除非满足以下条件。
委托访问权限/共享文件夹
- 邮箱所有者启动邮件。 这可以是新邮件、答复或转发。
- 他们保存邮件，然后将其从自己的 Drafts 文件夹移动到与委托共享的文件夹。
- 委托从共享文件夹中打开草稿，然后继续撰写。
共享邮箱 (仅适用于经典 Outlook on Windows)
- 共享邮箱用户启动邮件。 这可以是新邮件、答复或转发。
- 他们保存邮件，然后将其从自己的 Drafts 文件夹移动到共享邮箱中的文件夹。
- 另一个共享邮箱用户打开共享邮箱中的草稿，然后继续撰写。
满足这些条件后，该消息将在共享上下文中可用，支持这些共享方案的加载项可以获取项目的共享属性。 邮件发送后，通常位于发件人个人邮箱的 “已发送邮件” 文件夹中。
地址列表中隐藏的用户或共享邮箱
如果管理员从地址列表（例如全局地址列表 (GAL) ）中隐藏了用户或共享邮箱地址，则邮箱中打开的受影响邮件项目将报告 Office.context.mailbox.item 为 null。 例如，如果用户在共享邮箱中打开一个对 GAL 隐藏的邮件项目， Office.context.mailbox.item 则表示该邮件项为 null。
跨共享文件夹客户端同步
代理对所有者邮箱的更新通常会立即跨邮箱同步。 但是，如果使用 Microsoft Graph 操作来设置项目上的扩展属性，则此类更改可能需要一些时间才能同步。为了避免延迟，建议改用 CustomProperties 对象和相关 API。 若要了解详细信息，请参阅 获取和设置 Outlook 外接程序中的元数据的“邮箱中每个项目的自定义数据：自定义属性”部分。