在 Outlook 加载项中启用共享文件夹和共享邮箱方案

  • 项目

本文介绍如何在 Outlook 外接程序中启用共享文件夹 (也称为委托访问) 和共享邮箱方案，包括 Office JavaScript API 支持的权限。

注意

要求集 1.8 中引入了共享文件夹支持，而要求集 1.13 中引入了共享邮箱支持。 有关这些功能的客户端支持的信息，请参阅 支持的客户端和平台。

支持的客户端和平台

下表显示了此功能支持的客户端-服务器组合，包括所需的最低累积更新（如果适用）。 不支持排除的组合。

客户端 Exchange Online Exchange 2019 本地
(累积更新 1 或更高版本) 		Exchange 2016 本地
(累积更新 6 或更高版本) 		Exchange 2013 本地
Windows
共享文件夹：版本 1910 (内部版本 12130.20272) 或更高版本

共享邮箱：版本 2304 (内部版本 16327.20248) 或更高版本		 支持 支持* 支持* 支持*
Mac
内部版本 16.47 或更高版本		 支持 支持 支持 支持
Web 浏览器 (新式 Outlook UI) 支持 不适用 不适用 不适用
Web 浏览器 (经典 Outlook UI) 不适用 不适用 不适用 不适用

注意

* 从 Outlook on Windows 版本 2206 (内部版本 15330.20000) 当前频道和版本 2207 (每月企业频道内部版本 15427.20000) 开始，在本地 Exchange 环境中支持此功能。

支持的设置

以下部分介绍共享邮箱和共享文件夹支持的配置。 功能 API 在其他配置中可能无法按预期工作。 选择要了解如何配置的平台。

共享文件夹

邮箱所有者必须首先使用以下选项之一提供对委托的访问权限。

提供访问权限后，代理人必须按照 管理其他人的邮件和日历项目一文的“将其他人的邮箱添加到个人资料”部分中概述的说明进行操作。

共享邮箱

Exchange 服务器管理员可以创建和管理共享邮箱，供用户组访问。 支持Exchange Online和本地 Exchange 环境。

默认情况下，称为“自动映射”的Exchange Server功能处于打开状态，这意味着共享邮箱随后应在关闭并重新打开 Outlook 后自动显示在用户的 Outlook 应用中。 但是，如果管理员关闭了自动映射，则用户必须按照 在 Outlook 中打开和使用共享邮箱一文的“将共享邮箱添加到 Outlook”部分中概述的手动步骤进行操作。

警告

请勿使用密码登录到共享邮箱。 在这种情况下，功能 API 将不起作用。

若要详细了解加载项一般在何处执行和不激活，请参阅 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 调用，加载项必须请求 读/写邮箱 权限。 标记因清单类型而异。

  • XML 清单：将 <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.
}

限制

根据加载项的方案，在处理共享文件夹或共享邮箱情况时，需要考虑一些限制。

邮件撰写模式

在消息撰写模式下，Outlook 网页版或 Windows 上不支持 getSharedPropertiesAsync，除非满足以下条件。

a. 委托访问权限/共享文件夹

  1. 邮箱所有者启动邮件。 这可以是新邮件、答复或转发。
  2. 他们保存邮件，然后将其从自己的 Drafts 文件夹移动到与委托共享的文件夹。
  3. 委托从共享文件夹中打开草稿，然后继续撰写。

b. 共享邮箱 (仅适用于 Windows 版 Outlook)

  1. 共享邮箱用户启动邮件。 这可以是新邮件、答复或转发。
  2. 他们保存邮件，然后将其从自己的 Drafts 文件夹移动到共享邮箱中的文件夹。
  3. 另一个共享邮箱用户打开共享邮箱中的草稿，然后继续撰写。

消息现在位于共享上下文中，支持这些共享方案的加载项可以获取项的共享属性。 邮件发送后，通常位于发件人的 “已发送邮件” 文件夹中。

REST 和 EWS

加载项可以使用 REST。 若要启用对所有者邮箱或共享邮箱（如果适用）的 REST 访问，外接程序必须在清单中请求 读/写邮箱 权限。 标记因清单类型而异。

  • XML 清单：将 <Permissions> 元素设置为 ReadWriteMailbox。
  • Microsoft 365 (预览版统一清单) ：将“authorization.permissions.resourceSpecific”数组中对象的“name”属性设置为“Mailbox.ReadWrite.User”。

不支持 EWS。

地址列表中隐藏的用户或共享邮箱

如果管理员从全局地址列表（如全局地址列表 (GAL) ）中隐藏了用户或共享邮箱地址，则邮箱中打开的受影响邮件项将 Office.context.mailbox.item 显示为 null。 例如，如果用户在共享邮箱中打开一个对 GAL 隐藏的邮件项目， Office.context.mailbox.item 则表示该邮件项为 null。

另请参阅