Поделиться через

Использование REST API Outlook из надстройки Outlook

Пространство имен Office.context.mailbox.item предоставляет доступ ко множеству общих полей сообщений и встреч. Однако в некоторых сценариях надстройке может потребоваться доступ к данным, которые не предоставляются пространством имен. Например, надстройка может использовать настраиваемые свойства, заданные внешним приложением, или искать в почтовом ящике пользователя сообщения от одного отправителя. В таких случаях для получения сведений рекомендуется использовать интерфейсы REST API Outlook.

Важно!

Конечные точки REST Outlook версии 2.0 и бета-версии устарели

Конечные точки REST Outlook версии 2.0 и бета-версии теперь устарели. Однако частные и размещенные в AppSource надстройки по-прежнему могут использовать службу REST до окончания расширенной поддержки Outlook 2019 14 октября 2025 г. Трафик из этих надстроек автоматически определяется для исключения. Это исключение также применяется к новым надстройкам, разработанным после 31 марта 2024 г.

Хотя надстройки смогут использовать службу REST до октября 2025 г., настоятельно рекомендуется перенести надстройки на использование Microsoft Graph.

Получение токена доступа

Важно!

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

Интерфейсам REST API Outlook необходим токен носителя в заголовке Authorization. Как правило, приложения используют потоки OAuth2 для получения маркера. Однако надстройки могут получить маркер без реализации OAuth2 с помощью нового метода Office.context.mailbox.getCallbackTokenAsync , который появился в наборе обязательных для почтового ящика 1.5.

Задав для параметра isRest значение true, вы можете запросить маркер, совместимый с интерфейсами REST API.

Разрешения надстроек и область маркера

Важно учитывать уровень доступа через интерфейсы REST API, который потребуется надстройке. В большинстве случаев маркер, возвращенный методом getCallbackTokenAsync, предоставляет доступ только для чтения и только для текущего элемента. Это справедливо, даже если надстройка указывает уровень разрешений на чтение и запись элемента в манифесте.

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

Пример

Office.context.mailbox.getCallbackTokenAsync({isRest: true}, function(result){
  if (result.status === "succeeded") {
    const accessToken = result.value;

    // Use the access token.
    getCurrentItem(accessToken);
  } else {
    // Handle the error.
  }
});

Получение идентификатора элемента

Чтобы получить текущий элемент с помощью REST, надстройке потребуется его идентификатор, правильно отформатированный для службы REST. Его можно получить из свойства Office.context.mailbox.item.itemId, но необходимо выполнить некоторые проверки, чтобы убедиться, что идентификатор отформатирован для REST.

  • В Outlook на мобильных устройствах возвращаемое значение является идентификатором Office.context.mailbox.item.itemId в формате REST и может использоваться как есть.
  • В других клиентах Outlook свойство Office.context.mailbox.item.itemId возвращает идентификатор в формате EWS, который необходимо преобразовать с помощью метода Office.context.mailbox.convertToRestId.
  • Обратите внимание: чтобы использовать идентификатор вложения, его нужно преобразовать в идентификатор в формате REST. Это преобразование необходимо, потому что идентификаторы EWS могут содержать небезопасные в отношении URL-адресов значения, которые вызывают проблемы с REST.

Надстройка может определить, в каком клиенте Outlook она загружена, с помощью свойства Office.context.mailbox.diagnostics.hostName.

Пример

function getItemRestId() {
  if (Office.context.mailbox.diagnostics.hostName === 'OutlookIOS') {
    // itemId is already REST-formatted.
    return Office.context.mailbox.item.itemId;
  } else {
    // Convert to an item ID for API v2.0.
    return Office.context.mailbox.convertToRestId(
      Office.context.mailbox.item.itemId,
      Office.MailboxEnums.RestVersion.v2_0
    );
  }
}

Использование URL-адреса REST API

Последнее значение, необходимое надстройке для вызова REST API, — это имя узла, используемое для отправки запросов API. Оно содержится в свойстве Office.context.mailbox.restUrl.

Пример

// Example: https://outlook.office.com
const restHost = Office.context.mailbox.restUrl;

Вызов API

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

Важно!

Для локальных развертываний Exchange клиентские запросы, использующие AJAX или аналогичные библиотеки, завершаются ошибкой, так как CORS не поддерживается в этой установке сервера.

function getCurrentItem(accessToken) {
  // Get the item's REST ID.
  const itemId = getItemRestId();

  // Construct the REST URL to the current item.
  // Details for formatting the URL can be found at
  // https://learn.microsoft.com/previous-versions/office/office-365-api/api/version-2.0/mail-rest-operations#get-messages.
  const getMessageUrl = Office.context.mailbox.restUrl +
    '/v2.0/me/messages/' + itemId;

  $.ajax({
    url: getMessageUrl,
    dataType: 'json',
    headers: { 'Authorization': 'Bearer ' + accessToken }
  }).done(function(item){
    // Message is passed in `item`.
    const subject = item.Subject;
    ...
  }).fail(function(error){
    // Handle error.
  });
}

См. также