Включение общих папок и сценариев общих почтовых ящиков в надстройке Outlook

  • Статья

В этой статье описывается включение общих папок (также называемых делегированным доступом) и сценариев общего почтового ящика в надстройке Outlook, включая разрешения, поддерживаемые API JavaScript для Office.

Примечание.

Поддержка общих папок появилась в наборе требований 1.8, а поддержка общих почтовых ящиков появилась в наборе требований 1.13. Сведения о поддержке клиентов для этих функций см. в разделе Поддерживаемые клиенты и платформы.

Поддерживаемые клиенты и платформы

В следующей таблице показаны поддерживаемые сочетания клиента и сервера для этой функции, включая минимальное требуемое накопительное обновление, если применимо. Исключенные сочетания не поддерживаются.

Клиент Exchange Online. Локальная среда Exchange 2019
(Накопительный пакет обновления 1 или более поздней версии)		 Локальная среда Exchange 2016
(Накопительный пакет обновления 6 или более поздней версии)
Веб-браузер (современный пользовательский интерфейс Outlook) Поддерживается Неприменимо Неприменимо
Веб-браузер (классический пользовательский интерфейс Outlook) Неприменимо Неприменимо Неприменимо
Windows (классическая версия)
Общие папки: версия 1910 (сборка 12130.20272) или более поздняя

Общие почтовые ящики: версия 2304 (сборка 16327.20248) или более поздняя		 Поддерживается Поддерживается* Поддерживается*
Mac
Версия 16.47 или более поздняя		 Поддерживается Поддерживается Поддерживается

Примечание.

* Поддержка этой функции в локальной среде Exchange доступна, начиная с Outlook для Windows версии 2206 (сборка 15330.20000) для текущего канала и версии 2207 (сборка 15427.20000) для monthly Enterprise Channel.

Поддерживаемые настройки

В следующих разделах описаны поддерживаемые конфигурации для общих почтовых ящиков и общих папок. API-интерфейсы компонентов могут работать не так, как ожидалось в других конфигурациях. Выберите платформу, которую вы хотите узнать, как настроить.

Общие папки

Владелец почтового ящика должен сначала предоставить доступ к делегату с помощью одного из следующих параметров.

После предоставления доступа делегат должен выполнить инструкции, описанные в разделе "Добавление почтового ящика другого пользователя в профиль" статьи Управление элементами почты и календаря другого пользователя.

Общие почтовые ящики

Администраторы Exchange Server могут создавать общие почтовые ящики и управлять ими для наборов пользователей для доступа. поддерживаются Exchange Online и локальные среды Exchange.

Функция Exchange Server, известная как "автоматическое сопоставление", включена по умолчанию, что означает, что впоследствии общий почтовый ящик должен автоматически отображаться в приложении Outlook пользователя после закрытия и повторного открытия Outlook. Однако если администратор отключил автоматическое сопоставление, пользователь должен выполнить действия вручную, описанные в разделе "Добавление общего почтового ящика в Outlook" статьи Открытие и использование общего почтового ящика в Outlook.

Предупреждение

Не войдите в общий почтовый ящик с помощью пароля. В этом случае API-интерфейсы компонентов не будут работать.

Дополнительные сведения о том, где надстройки выполняются и не активируются в целом, см. в разделе Элементы почтовых ящиков, доступные для надстроек , на странице обзора надстроек Outlook.

Поддерживаемые разрешения

В следующей таблице описаны разрешения, которые API JavaScript для Office поддерживает для делегатов и пользователей общих почтовых ящиков.

Разрешение Значение Описание
Чтение 1 (000001) Может читать элементы.
Запись 2 (000010) Может создавать элементы.
DeleteOwn 4 (000100) Может удалять только созданные элементы.
DeleteAll 8 (001000) Может удалять любые элементы.
EditOwn 16 (010000) Может изменять только созданные элементы.
Изменитьвсе 32 (100000) Может изменять любые элементы.

Примечание.

В настоящее время API поддерживает получение существующих разрешений, но не настройку разрешений.

Объект DelegatePermissions реализуется с помощью битовой маски для указания разрешений. Каждая позиция в битовой маске представляет определенное разрешение, и если для нее задано значение 1 , пользователь имеет соответствующее разрешение. Например, если второй бит справа — 1, то пользователь имеет разрешение на запись . Пример проверка для определенного разрешения см. в разделе Выполнение операции в качестве пользователя-делегата или пользователя общего почтового ящика далее в этой статье.

Синхронизация между клиентами общих папок

Обновления делегата в почтовом ящике владельца обычно синхронизируются между почтовыми ящиками немедленно.

Однако если для задания расширенного свойства элемента использовались операции REST или веб-служб Exchange (EWS), синхронизация таких изменений может занять несколько часов. Вместо этого рекомендуется использовать объект CustomProperties и связанные API, чтобы избежать такой задержки. Дополнительные сведения см. в разделе пользовательских свойств статьи "Получение и настройка метаданных в надстройке Outlook".

Важно!

В сценарии делегирования нельзя использовать EWS с маркерами, которые в настоящее время предоставляются API office.js.

Настройка манифеста

Чтобы включить сценарии общих папок и общих почтовых ящиков в надстройке, необходимо включить необходимые разрешения в манифесте.

Во-первых, для поддержки вызовов REST от делегата надстройка должна запросить разрешение на чтение и запись почтового ящика . Разметка зависит от типа манифеста.

  • XML-манифест. Задайте для <элемента Permissions>значение ReadWriteMailbox.
  • Унифицированный манифест для Microsoft 365: задайте для свойства name объекта в массиве authorization.permissions.resourceSpecific значение Mailbox.ReadWrite.User.

Во-вторых, включите поддержку общих папок. Разметка зависит от типа манифеста.

Добавьте дополнительный объект в массив authorization.permissions.resourceSpecific и задайте для его свойства name значение Mailbox.SharedFolder.

"authorization": {
  "permissions": {
    "resourceSpecific": [
      ...
      {
        "name": "Mailbox.SharedFolder",
        "type": "Delegated"
      },
    ]
  }
},

Выполнение операции в качестве пользователя делегата или общего почтового ящика

Общие свойства элемента можно получить в режиме создания или чтения, вызвав метод item.getSharedPropertiesAsync . При этом возвращается объект SharedProperties , который в настоящее время предоставляет разрешения пользователя, адрес электронной почты владельца, базовый URL-адрес REST API и целевой почтовый ящик.

В следующем примере показано, как получить общие свойства сообщения или встречи, проверка, если пользователь делегата или общего почтового ящика имеет разрешение на запись, и выполнить вызов 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, чтобы определить, является ли элемент общим. После этого можно создать URL-адрес REST для операции с помощью соответствующего объекта.

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.
}

Ограничения

В зависимости от сценариев надстройки существует несколько ограничений, которые следует учитывать при обработке общих папок или общих почтовых ящиков.

Режим создания сообщений

В режиме создания сообщений метод getSharedPropertiesAsync не поддерживается в Outlook в Интернете или Windows, если не выполнены следующие условия.

А. Делегирование доступа или общие папки

  1. Владелец почтового ящика запускает сообщение. Это может быть новое сообщение, ответ или пересылка.
  2. Они сохраняют сообщение, а затем перемещают его из собственной папки Черновики в папку, к которой предоставлен общий доступ делегату.
  3. Делегат открывает черновик из общей папки, а затем продолжает создание.

Б. Общий почтовый ящик (применяется только к Outlook в Windows)

  1. Пользователь общего почтового ящика запускает сообщение. Это может быть новое сообщение, ответ или пересылка.
  2. Они сохраняют сообщение, а затем перемещают его из собственной папки Черновики в папку в общем почтовом ящике.
  3. Другой пользователь общего почтового ящика открывает черновик из общего почтового ящика, а затем продолжает создавать.

Теперь сообщение находится в общем контексте, и надстройки, поддерживающие эти общие сценарии, могут получить общие свойства элемента. После отправки сообщение обычно находится в папке Отправленные .

REST и EWS

Ваша надстройка может использовать REST. Чтобы разрешить доступ REST к почтовому ящику владельца или к общему почтовому ящику, если применимо, надстройка должна запросить разрешение на чтение и запись почтового ящика в манифесте. Разметка зависит от типа манифеста.

  • XML-манифест. Задайте для <элемента Permissions>значение ReadWriteMailbox.
  • Унифицированный манифест для Microsoft 365: задайте для свойства name объекта в массиве authorization.permissions.resourceSpecific значение Mailbox.ReadWrite.User.

EWS не поддерживается.

Пользователь или общий почтовый ящик, скрытый из списка адресов

Если администратор спрятал адрес пользователя или общего почтового ящика из списка адресов, например глобального списка адресов (GAL), затронутые почтовые элементы открываются в отчете Office.context.mailbox.item почтового ящика как null. Например, если пользователь открывает почтовый элемент в общем почтовом ящике, который скрыт от глобального списка адресов, Office.context.mailbox.item то этот почтовый элемент имеет значение NULL.

См. также