Реализация общих папок и сценариев общих почтовых ящиков в надстройке 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 в Windows

Общие папки

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

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

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

  • Владелец почтового ящика может настроить доступ через классический Outlook в Windows. Дополнительные сведения см. в статье Разрешение другим пользователям управлять почтой и календарем.

  • Администратор может настроить доступ через Центр администрирования Microsoft 365. Дополнительные сведения см. в статье Предоставление разрешений на почтовый ящик другому пользователю Microsoft 365.

  • Администратор может настроить доступ через Центр администрирования Exchange. Дополнительные сведения см. в статье Управление разрешениями для получателей.

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

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

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

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

Примечание.

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

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

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

Windows (классическая версия)

Общие папки

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

• Настройте делегированный доступ из почтового ящика в классической версии Outlook в Windows. Дополнительные сведения см. в статье Разрешение другим пользователям управлять почтой и календарем.

• Настройте делегированный доступ из Центр администрирования Microsoft 365. Этот параметр может быть выполнен только администраторами. Дополнительные сведения см. в статье Предоставление разрешений на почтовый ящик другому пользователю Microsoft 365.

• Настройте делегированный доступ из Центра администрирования Exchange. Этот параметр может быть выполнен только администраторами. Дополнительные сведения см. в статье Управление разрешениями для получателей.

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

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

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

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

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

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

Mac

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

Общий почтовый ящик позволяет группе пользователей легко отслеживать и отправлять сообщения и приглашения на собрания с помощью общего адреса электронной почты. Инструкции по доступу к общему почтовому ящику, на который у вас есть разрешения в Outlook на Mac, см. в разделе "Открытие общего или делегированного почтового ящика" статьи Открытие общей папки "Почта", "Календарь" или Люди в Outlook для Mac.

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

Общие папки

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

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

Локальный общий календарь (новая модель)

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

Удаленный общий календарь (предыдущая модель)

Если владелец календаря предоставил широкий доступ к своему календарю (например, сделал его редактируемым для определенного DL или всей организации), пользователи могут иметь косвенное или неявное разрешение, а надстройки будут доступны для пользователей в режимах чтения и создания встреч.

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

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

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

Унифицированный манифест для Microsoft 365

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

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

Манифест только надстройки

В родительском <элементе DesktopFormFactor> задайте для элемента SupportsSharedFolders значение true. В настоящее время другие форм-факторы не поддерживаются.

...
<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides" xsi:type="VersionOverridesV1_0">
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1" xsi:type="VersionOverridesV1_1">
    ...
    <Hosts>
      <Host xsi:type="MailHost">
        <DesktopFormFactor>
          <SupportsSharedFolders>true</SupportsSharedFolders>
          <FunctionFile resid="residDesktopFuncUrl" />
          <ExtensionPoint xsi:type="MessageReadCommandSurface">
            <!-- Configure the extension point. -->
          </ExtensionPoint>
          ...
        </DesktopFormFactor>
      </Host>
    </Hosts>
    ...
  </VersionOverrides>
</VersionOverrides>
...

Определение общего доступа к папке или почтовому ящику

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

В следующем примере вызывается 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)	Может изменять только созданные элементы.
Изменитьвсе	32 (100000)	Может изменять любые элементы.

Примечание.

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

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

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

После того как вы определили, что текущий почтовый элемент находится в общей папке или общем почтовом ящике, надстройка может выполнить необходимые операции с элементом в общей среде. Чтобы выполнить операции с элементом в общем контексте, необходимо сначала настроить разрешение надстройки в манифесте. Затем используйте Microsoft Graph для завершения операций.

Примечание.

Веб-службы Exchange (EWS) не поддерживаются в сценариях с общими папками и общими почтовыми ящиками.

Настройка разрешений надстройки

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

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

Использование Microsoft Graph

Чтобы реализовать сценарии использования общих папок и общих почтовых ящиков, используйте Microsoft Graph для доступа к дополнительным сведениям и ресурсам почтового ящика. Например, с помощью Microsoft Graph можно получить содержимое сообщения Outlook, присоединенного к сообщению в почтовом ящике, в котором пользователь имеет делегированный доступ. Инструкции по использованию Microsoft Graph см. в статье Обзор Microsoft Graph и API почты Outlook в Microsoft Graph.

Совет

Чтобы получить доступ к API Microsoft Graph из надстройки, используйте MSAL.js проверку подлинности вложенного приложения (NAA). Дополнительные сведения см. в статье Включение единого входа в надстройке Office с помощью проверки подлинности вложенного приложения (предварительная версия).

Ограничения

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

Режим Compose сообщений

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

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

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

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

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

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

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

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

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

Обновления делегата в почтовом ящике владельца обычно синхронизируются между почтовыми ящиками немедленно. Однако если для задания расширенного свойства элемента использовались операции Microsoft Graph, синхронизация таких изменений может занять некоторое время. Чтобы избежать задержки, рекомендуется использовать объект CustomProperties и связанные API. Дополнительные сведения см. в разделе "Пользовательские данные для элемента в почтовом ящике: пользовательские свойства" статьи Получение и настройка метаданных в надстройке Outlook.

См. также

• Предоставление другому пользователю разрешения на управление вашей почтой и календарем
• Общий доступ к календарю в Microsoft 365
• Добавление общего почтового ящика в Outlook
• Обзор Microsoft Graph