Использование веб-служб Exchange (EWS) из надстройки Outlook

Надстройка Outlook может использовать веб-службы Exchange (EWS) из среды, в которой выполняется Exchange Server (локально). EWS — это веб-служба, доступная на сервере, которая предоставляет исходное расположение для пользовательского интерфейса надстройки. В этой статье приведен пример того, как надстройка Outlook может запрашивать данные из EWS.

Важно!

Устаревшие токены Exchange устарели. Начиная с февраля 2025 г. мы начнем отключать устаревшие удостоверения пользователя Exchange и маркеры обратного вызова для Exchange Online клиентов. Временная шкала и подробные сведения см. на странице часто задаваемых вопросов. Это часть инициативы Майкрософт по обеспечению безопасности в будущем, которая предоставляет организациям средства, необходимые для реагирования на текущую среду угроз. Маркеры удостоверений пользователей Exchange по-прежнему будут работать в локальной среде Exchange. Проверка подлинности вложенных приложений — это рекомендуемый подход к токенам в будущем.

Способ вызова веб-службы зависит от расположения веб-службы. В следующих таблицах перечислены различные способы вызова веб-службы в зависимости от расположения.

Расположение веб-службы	Способ вызова веб-службы
Сервер Exchange, на котором размещен почтовый ящик клиента	Используйте метод makeEwsRequestAsync для вызова операций EWS, поддерживаемых надстройками. Сервер Exchange Server, на котором размещен почтовый ящик, также предоставляет доступ к EWS.
Веб-сервер, предоставляющий исходное расположение для пользовательского интерфейса надстроек.	Вызывайте веб-службу с помощью стандартных методик JavaScript. Код JavaScript в пределах пользовательского интерфейса работает в контексте веб-сервера, предоставляющего пользовательский интерфейс. Поэтому он сможет вызывать веб-службы на этом сервере, не создавая ошибки межсайтового скрипта.
Все другие расположения	Создайте прокси для веб-службы на веб-сервере, предоставляющем исходное расположение для пользовательского интерфейса. Если не указать прокси-сервер, ошибки межсайтовых сценариев помешают запуску надстройки. Один из способов указать такой прокси — это использовать JSON/P. Дополнительные сведения см. в разделе Конфиденциальность и безопасность надстроек Office.

Получение доступа к операциям веб-служб Exchange с помощью метода makeEwsRequestAsync

Важно!

Вызовы и операции EWS не поддерживаются в надстройках, работающих в Outlook в Android и iOS.

Метод mailbox.makeEwsRequestAsync можно использовать для выполнения запроса EWS к локальному серверу Exchange, на котором размещен почтовый ящик пользователя.

EWS поддерживает различные операции на сервере Exchange Server; например, операции на уровне элемента для копирования, поиска, обновления или отправки элемента, а также операции на уровне папки для создания, получения или обновления папки. Чтобы выполнить операцию EWS, создайте xml-запрос SOAP для этой операции. После завершения операции вы получите XML-ответ SOAP, содержащий данные, относящиеся к операции. Запросы и ответы EWS SOAP соответствуют схеме, определенной в файле Messages.xsd . Как и другие файлы схемы EWS, файл Message.xsd находится в виртуальном каталоге IIS, где размещается EWS.

Чтобы использовать makeEwsRequestAsync метод для запуска операции EWS, укажите следующее:

• XML-код для запроса SOAP для этой операции EWS в качестве аргумента параметра данных .

• Функция обратного вызова (в качестве аргумента обратного вызова ).

• Любые необязательные входные данные для этой функции обратного вызова (в качестве аргумента userContext ).

После завершения запроса SOAP EWS Outlook вызывает функцию обратного вызова с одним аргументом, который является объектом AsyncResult . Функция обратного вызова может получить доступ к двум свойствам AsyncResult объекта: свойству value , которое содержит XML-ответ SOAP операции EWS, и, при необходимости, к свойству asyncContext , которое содержит все данные, переданные в userContext качестве параметра. Как правило, функция обратного вызова анализирует XML-код в ответе SOAP, чтобы получить все соответствующие сведения и обработает эти сведения соответствующим образом.

Советы по анализу ответов веб-служб Exchange

При анализе ответа SOAP от операции EWS обратите внимание на следующие проблемы, зависящие от браузера.

• Укажите префикс для имени тега при использовании метода getElementsByTagName DOM для включения поддержки интернет-Обозреватель и веб-представления Trident.

  getElementsByTagName поведение по-разному в зависимости от типа браузера. Например, ответ EWS может содержать следующий XML-код (отформатированный и сокращенный для отображения).

  <t:ExtendedProperty><t:ExtendedFieldURI PropertySetId="00000000-0000-0000-0000-000000000000" 
  PropertyName="MyProperty" 
  PropertyType="String"/>
  <t:Value>{
  ...
  }</t:Value></t:ExtendedProperty>
  

  Код, как показано ниже, будет работать в браузере, например Chrome, чтобы получить XML-код, заключенный в ExtendedProperty теги.

  const mailbox = Office.context.mailbox;
  mailbox.makeEwsRequestAsync(mailbox.item.itemId, (result) => {
       const response = $.parseXML(result.value);
       const extendedProps = response.getElementsByTagName("ExtendedProperty")
  });
  

  Для веб-представления Trident (Интернет-Обозреватель) необходимо включить t: префикс имени тега, как показано ниже.

  const mailbox = Office.context.mailbox;
  mailbox.makeEwsRequestAsync(mailbox.item.itemId, (result) => {
       const response = $.parseXML(result.value);
       const extendedProps = response.getElementsByTagName("t:ExtendedProperty")
  });
  

• Используйте свойство textContent DOM, чтобы получить содержимое тега в ответе EWS, как показано ниже.

  content = $.parseJSON(value.textContent);
  

  Другие свойства, innerHTML например, могут не работать в веб-представлении Trident (Интернет-Обозреватель) для некоторых тегов в ответе EWS.

Пример

В следующем примере вызывается makeEwsRequestAsync использование операции GetItem для получения темы элемента. Этот пример включает следующие три функции.

• getSubjectRequest — принимает идентификатор элемента в качестве входных данных и возвращает XML-код для запроса SOAP для вызова GetItem указанного элемента.

• sendRequest — вызывается getSubjectRequest для получения запроса SOAP для выбранного элемента, а затем передает запрос SOAP и функцию обратного вызова , callbackчтобы makeEwsRequestAsync получить тему указанного элемента.

• callback — обрабатывает ответ SOAP, который включает в себя любую тему и другие сведения о указанном элементе.

function getSubjectRequest(id) {
   // Return a GetItem operation request for the subject of the specified item. 
   const result = 
    '<?xml version="1.0" encoding="utf-8"?>' +
    '<soap:Envelope xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"' +
    '               xmlns:xsd="https://www.w3.org/2001/XMLSchema"' +
    '               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"' +
    '               xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">' +
    '  <soap:Header>' +
    '    <RequestServerVersion Version="Exchange2013" xmlns="http://schemas.microsoft.com/exchange/services/2006/types" soap:mustUnderstand="0" />' +
    '  </soap:Header>' +
    '  <soap:Body>' +
    '    <GetItem xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">' +
    '      <ItemShape>' +
    '        <t:BaseShape>IdOnly</t:BaseShape>' +
    '        <t:AdditionalProperties>' +
    '            <t:FieldURI FieldURI="item:Subject"/>' +
    '        </t:AdditionalProperties>' +
    '      </ItemShape>' +
    '      <ItemIds><t:ItemId Id="' + id + '"/></ItemIds>' +
    '    </GetItem>' +
    '  </soap:Body>' +
    '</soap:Envelope>';

   return result;
}

function sendRequest() {
   // Create a local variable that contains the mailbox.
   const mailbox = Office.context.mailbox;

   mailbox.makeEwsRequestAsync(getSubjectRequest(mailbox.item.itemId), callback);
}

function callback(asyncResult)  {
   const result = asyncResult.value;
   const context = asyncResult.context;

   // Process the returned response here.
}

Операции веб-служб Exchange, которые надстройки поддерживают

Надстройки Outlook могут получить доступ к подмножествию операций, доступных в EWS, с помощью makeEwsRequestAsync метода . Если вы не знакомы с операциями EWS и как использовать makeEwsRequestAsync метод для доступа к операции, начните с примера запроса SOAP для настройки аргумента данных .

Ниже описано, как можно использовать makeEwsRequestAsync метод .

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

2. Добавьте запрос SOAP в качестве аргумента для параметра makeEwsRequestAsyncданных .

3. Укажите функцию обратного вызова и вызовите makeEwsRequestAsync.

4. В функции обратного вызова проверьте результаты операции в ответе SOAP.

5. Используйте результаты операции EWS в соответствии с вашими потребностями.

В следующей таблице указаны операции EWS, которые надстройки поддерживают. Чтобы просмотреть примеры SOAP-запросов и SOAP-ответов, выберите ссылку для каждой операции. Дополнительные сведения об операциях EWS см. в разделе Операции EWS в Exchange.

Операция EWS	Описание
Операция CopyItem	Копирует выбранные элементы и размещает новые элементы в выделенной папке в хранилище Exchange.
Операция CreateFolder	Создает папки в выбранном расположении в хранилище Exchange.
Операция CreateItem	Создает заданные элементы в хранилище Exchange.
Операция ExpandDL	Отображает полное членство списков рассылки.
Операция FindConversation	Перечисляет список бесед в определенной папке в хранилище Exchange.
Операция FindFolder	Ищет вложенные папки заданной папки и возвращает набор свойств, описывающих вложенные папки.
Операция FindItem	Определяет элементы, расположенные в определенной папке в хранилище Exchange.
Операция GetConversationItems	Получает один или несколько наборов элементов, упорядоченных в узлы в беседе.
Операция GetFolder	Получает определенные свойства и содержимое папок из хранилища Exchange.
Операция GetItem	Получает определенные свойства и содержимое элементов из хранилища Exchange.
Операция GetUserAvailability	Предоставляет подробные сведения о доступности наборов пользователей, помещений и ресурсов в рамках определенного периода времени.
Операция MarkAsJunk	Перемещает сообщения электронной почты в папку "Нежелательная почта" и соответствующим образом добавляет или удаляет отправителей сообщений в списке заблокированных отправителей.
Операция MoveItem	Перемещает элементы в одну целевую папку в хранилище Exchange.
Операция ResolveNames	Сопоставляет неоднозначные адреса электронной почты и отображает имена.
Операция SendItem	Отправляет сообщения электронной почты, расположенные в хранилище Exchange.
Операция UpdateFolder	Изменяет свойства существующих папок в хранилище Exchange.
Операция UpdateItem	Изменяет свойства существующих элементов в хранилище Exchange.

Примечание.

Элементы FAI (сведения, связанные с папками) не могут быть обновлены (или созданы) из надстройки. Эти скрытые сообщения находятся в папке и используются для хранения различных параметров и вспомогательных данных. При попытке использовать операцию UpdateItem возникнет ошибка ErrorAccessDenied: "У расширения Office нет разрешения на обновление такого элемента". В качестве альтернативы можно использовать управляемый API служб EWS для обновления этих элементов в клиентском или серверном приложении для Windows. Рекомендуем соблюдать осторожность, так как внутренние структуры данных для служб могут меняться и сделать решение неработоспособным.

Разрешения и проверка подлинности для makeEwsRequestAsync

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

Примечание.

Администратор сервера должен использовать командлет New-WebServicesVirtualDirectory или Set-WebServicesVirtualDirectory , чтобы задать параметру OAuthAuthentication значение true в каталоге EWS сервера клиентского доступа, чтобы разрешить makeEwsRequestAsync методу выполнять запросы EWS.

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

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

Сведения об использовании разрешения на чтение и запись почтового ящика см. в разделе Разрешение на чтение и запись почтового ящика.

См. также

• Конфиденциальность и безопасность надстроек для Office
• Работа с ограничениями по принципу одинакового источника в надстройках Office
• Справка по службам EWS для Exchange
• Приложения электронной почты для Outlook и служб EWS в Exchange

Сведения о создании внутренних служб для надстроек с помощью веб-API ASP.NET см. ниже.

• Создание веб-службы надстройки для Office с использованием веб-API ASP.NET
• Основы создания службы HTTP с использованием веб-API ASP.NET