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

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

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://video2.skills-academy.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.