Поделиться через

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

  • Статья

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

Примечание.

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

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

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

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

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

Примечание.

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

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

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

Общие папки

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

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

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

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

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

Примечание.

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

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

В новом Outlook в Windows общий почтовый ящик добавляется в раздел Мне предоставлен общий доступ на панели папок. Инструкции см. в статье Открытие и использование общего почтового ящика в Outlook.

Дополнительные сведения о том, где надстройки выполняются и не активируются в целом, см. в разделе Элементы почтовых ящиков, доступные для надстроек , на странице обзора надстроек 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 от делегата надстройка должна запросить разрешение на чтение и запись почтового ящика . Разметка зависит от типа манифеста.

  • Манифест только надстройки<. Задайте для элемента 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 к почтовому ящику владельца или к общему почтовому ящику, если применимо, надстройка должна запросить разрешение на чтение и запись почтового ящика в манифесте. Разметка зависит от типа манифеста.

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

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

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

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

См. также