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

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

Важно!

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

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

Хотя надстройки могут использовать службу REST до 2025 года, мы настоятельно рекомендуем перенести надстройки на использование Microsoft Graph. Рекомендации см. в статье Сравнение конечных точек REST API Microsoft Graph и Outlook.

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

Интерфейсам 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.
  });
}

См. также

• Пример вызова REST API из надстроек Outlook: command-demo на сайте GitHub.
• REST API Outlook также доступны через конечную точку Microsoft Graph, но с некоторыми важными отличиями, включая способ получения надстройкой маркера доступа. Дополнительные сведения см. в разделе REST API Outlook через Microsoft Graph.