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

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

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

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

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

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

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

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

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

...
<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 поддерживаются для делегатов и пользователей общих почтовых ящиков.

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

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

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

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

Чтобы использовать службы 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.

Поддержка надстроек в сценариях с общими папками и общими почтовыми ящиками

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

Надстройки в сценариях с общими папками

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

Надстройки в сценариях с общим почтовым ящиком

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

Ограничения

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

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

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

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

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

• Общий почтовый ящик открыт на той же панели, что и основной почтовый ящик пользователя (веб-, классическая версия Windows) или общий почтовый ящик, который не был повышен до полной учетной записи (новая windows)

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

  Примечание.

  Метод getSharedPropertiesAsync поддерживается на следующих платформах без дополнительных условий.

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

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

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

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

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

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

См. также

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