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

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

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

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

Клиент Exchange Online Exchange 2019 на месте
(Накопительное обновление 1 или более позднее)
Exchange 2016
(Накопительное обновление 6 или более позднее)
Exchange 2013
Windows:
версия 1910 (сборка 12130.20272) или более поздней версии
Да Нет Нет Нет
Mac:
сборка 16.47 или более поздней
Да Да Да Да
Веб-браузер:
современный Outlook пользовательского интерфейса
Да Неприменимо Неприменимо Неприменимо
Веб-браузер:
классический Outlook пользовательского интерфейса
Неприменимо Нет Нет Нет

Важно!

Поддержка этой функции была представлена в наборе требований 1.8 (подробные сведения см. в отношении клиентов и платформ). Однако обратите внимание, что матрица поддержки функции является суперсетью набора требований.

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

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

Общие папки

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

Важно!

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

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

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

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

В следующем примере показан элемент, установленный 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 selected extension point -->
          </ExtensionPoint>

          <!-- You can define more than one ExtensionPoint element as needed -->

        </DesktopFormFactor>
      </Host>
    </Hosts>
    ...
  </VersionOverrides>
</VersionOverrides>
...

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

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

В следующем примере показано, как получить общие свойства сообщения или встречи, проверить, есть ли у делегата или общего пользователя почтового ящика разрешение на запись, и сделать вызов 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 для элемента, является ли этот элемент общим, вы можете использовать API, чтобы определить, является ли элемент getSharedPropertiesAsync общим. После этого можно создать 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 is not a shared item, so construct the REST URL using info from the Call REST APIs article:
  // https://docs.microsoft.com/office/dev/add-ins/outlook/use-rest-api

  // Perform operation for non-shared item.
}

Ограничения

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

Режим композитации сообщений

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

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

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

b. Общий почтовый ящик

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

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

REST и EWS

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

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

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

См. также