在 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 外接程序概述页的 “可用于加载项的邮箱项目 ”部分。
支持的权限
下表描述了 Office JavaScript API 支持对委托和共享邮箱用户的权限。
| 权限 | 值 | 说明 |
|---|---|---|
| 阅读 | 1 (000001) | 可以读取项。 |
| 写入 | 2 (000010) | 可以创建项。 |
| DeleteOwn | 4 (000100) | 只能删除他们创建的项。 |
| DeleteAll | 8 (001000) | 可以删除任何项目。 |
| EditOwn | 16 (010000) | 只能编辑他们创建的项。 |
| EditAll | 32 (100000) | 可以编辑任何项目。 |
注意
目前，API 支持获取现有权限，但不支持设置权限。
DelegatePermissions 对象使用位掩码实现，以指示权限。 位掩码中的每个位置都表示一个特定权限，如果将其设置为 1 ，则用户具有相应的权限。 例如，如果右侧的第二位是 1，则用户具有 写入 权限。 可以在本文后面的 以代理人或共享邮箱用户身份执行操作 部分查看如何检查特定权限的示例。
跨共享文件夹客户端同步
代理对所有者邮箱的更新通常会立即跨邮箱同步。
但是，如果使用 REST 或 Exchange Web Services (EWS) 操作来设置项目上的扩展属性，则此类更改可能需要几个小时才能同步。建议改用 CustomProperties 对象和相关 API 以避免此类延迟。 若要了解详细信息，请参阅“获取和设置 Outlook 外接程序中的元数据”一文中的 自定义属性部分 。
重要
在委托方案中，不能将 EWS 与 office.js API 当前提供的令牌一起使用。
配置清单
若要在外接程序中启用共享文件夹和共享邮箱方案，必须在清单中启用所需的权限。
首先，若要支持来自委托的 REST 调用，加载项必须请求 读/写邮箱 权限。 标记因清单类型而异。
- 仅外接程序清单：将 <Permissions> 元素设置为 ReadWriteMailbox。
- Microsoft 365 的统一清单：将“authorization.permissions.resourceSpecific”数组中对象的“name”属性设置为“Mailbox.ReadWrite.User”。
其次，启用对共享文件夹的支持。 标记因清单类型而异。
将其他对象添加到“authorization.permissions.resourceSpecific”数组，并将其“name”属性设置为“Mailbox.SharedFolder”。
"authorization": {
"permissions": {
"resourceSpecific": [
...
{
"name": "Mailbox.SharedFolder",
"type": "Delegated"
},
]
}
},
以委托或共享邮箱用户身份执行操作
可以通过调用 item.getSharedPropertiesAsync 方法，在 Compose 或 Read 模式下获取项目的共享属性。 这将返回一个 SharedProperties 对象，该对象当前提供用户的权限、所有者的电子邮件地址、REST API 的基 URL 和目标邮箱。
以下示例演示如何获取邮件或约会的共享属性，检查代理人或共享邮箱用户是否具有 写入 权限，以及如何进行 REST 调用。
function performOperation() {
Office.context.mailbox.getCallbackTokenAsync({
isRest: true
},
function (asyncResult) {
if (asyncResult.status === Office.AsyncResultStatus.Succeeded && asyncResult.value !== "") {
Office.context.mailbox.item.getSharedPropertiesAsync({
// Pass auth token along.
asyncContext: asyncResult.value
},
function (asyncResult1) {
let sharedProperties = asyncResult1.value;
let delegatePermissions = sharedProperties.delegatePermissions;
// Determine if user can do the expected operation.
// E.g., do they have Write permission?
if ((delegatePermissions & Office.MailboxEnums.DelegatePermissions.Write) != 0) {
// Construct REST URL for your operation.
// Update <version> placeholder with actual Outlook REST API version e.g. "v2.0".
// Update <operation> placeholder with actual operation.
let rest_url = sharedProperties.targetRestUrl + "/<version>/users/" + sharedProperties.targetMailbox + "/<operation>";
$.ajax({
url: rest_url,
dataType: 'json',
headers:
{
"Authorization": "Bearer " + asyncResult1.asyncContext
}
}
).done(
function (response) {
console.log("success");
}
).fail(
function (error) {
console.log("error message");
}
);
}
}
);
}
}
);
}
提示
作为代理人，您可以使用 REST 获取附加到 Outlook 项目或组帖子的 Outlook 邮件的内容。
处理对共享项和非共享项的 REST 调用
如果要对项调用 REST 操作，无论该项是否共享，都可以使用 getSharedPropertiesAsync API 来确定该项是否共享。 之后，可以使用相应的 对象构造操作的 REST URL。
if (item.getSharedPropertiesAsync) {
// In Windows, Mac, and the web client, this indicates a shared item so use SharedProperties properties to construct the REST URL.
// Add-ins don't activate on shared items in mobile so no need to handle.
// Perform operation for shared item.
} else {
// In general, this isn't a shared item, so construct the REST URL using info from the Call REST APIs article:
// https://learn.microsoft.com/office/dev/add-ins/outlook/use-rest-api
// Perform operation for non-shared item.
}
限制
根据加载项的方案，在处理共享文件夹或共享邮箱情况时，需要考虑一些限制。
邮件撰写模式
在邮件撰写模式下，Web 版或 Windows 版 Outlook 不支持 getSharedPropertiesAsync ，除非满足以下条件。
a. 委托访问权限/共享文件夹
- 邮箱所有者启动邮件。 这可以是新邮件、答复或转发。
- 他们保存邮件，然后将其从自己的 Drafts 文件夹移动到与委托共享的文件夹。
- 委托从共享文件夹中打开草稿，然后继续撰写。
b. 共享邮箱 (仅适用于经典 Outlook on Windows)
- 共享邮箱用户启动邮件。 这可以是新邮件、答复或转发。
- 他们保存邮件，然后将其从自己的 Drafts 文件夹移动到共享邮箱中的文件夹。
- 另一个共享邮箱用户打开共享邮箱中的草稿，然后继续撰写。
消息现在位于共享上下文中，支持这些共享方案的加载项可以获取项的共享属性。 邮件发送后，通常位于发件人的 “已发送邮件” 文件夹中。
REST 和 EWS
加载项可以使用 REST。 若要启用对所有者邮箱或共享邮箱（如果适用）的 REST 访问，外接程序必须在清单中请求 读/写邮箱 权限。 标记因清单类型而异。
- 仅外接程序清单：将 <Permissions> 元素设置为 ReadWriteMailbox。
- Microsoft 365 的统一清单：将“authorization.permissions.resourceSpecific”数组中对象的“name”属性设置为“Mailbox.ReadWrite.User”。
不支持 EWS。
地址列表中隐藏的用户或共享邮箱
如果管理员从全局地址列表（如全局地址列表 (GAL) ）中隐藏了用户或共享邮箱地址，则邮箱中打开的受影响邮件项将 Office.context.mailbox.item 显示为 null。 例如，如果用户在共享邮箱中打开一个对 GAL 隐藏的邮件项目， Office.context.mailbox.item 则表示该邮件项为 null。