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

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

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

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

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

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

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

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

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

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

Ограничения

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

Режим 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