从 Outlook 加载项使用 Outlook REST API

Office.context.mailbox.item 命名空间提供访问许多邮件和约会的公用字段的权限。 但是，在某些情况下，外接程序可能需要访问命名空间未公开的数据。 例如，外接程序可能依赖于外部应用设置的自定义属性，或需要搜索用户邮箱中来自同一发件人的邮件。 在这些方案中，Outlook REST API 是推荐的检索信息的方法。

获取访问令牌

Outlook REST API 需要 Authorization 标头中的持有者令牌。 通常情况下，应用使用 OAuth2 流来检索令牌。 但是，加载项可以使用邮箱要求集 1.5 中引入的新 Office.context.mailbox.getCallbackTokenAsync 方法，在不实现 OAuth2 的情况下检索令牌。

通过将 isRest 选项设置为 true，可以请求获取与 REST API 兼容的令牌。

外接程序权限和令牌范围

请务必考虑外接程序通过 REST API 所需要的访问级别。 在大多数情况下，由 getCallbackTokenAsync 返回的令牌将仅提供对当前项的只读访问权限。 即使加载项在其清单中指定 读/写项权限 级别，也是如此。

如果外接程序需要对用户邮箱中的当前项目或其他项目的写入访问权限，则外接程序必须指定 可读/写邮箱权限。 其清单中的 level。 在这种情况下，所返回的令牌将包含用户的邮件、事件和联系人的读取/写入访问权限。

示例

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.
  }
});

获取项 ID

加载项需要针对 REST 正确设置格式的项 ID，才能通过 REST 检索当前项。 这可从 Office.context.mailbox.item.itemId 属性获取，但应进行一些检查，以确保它是针对 REST 正确设置格式的 ID。

• 在移动设备上的 Outlook 中，返回 Office.context.mailbox.item.itemId 的值是 REST 格式的 ID，可以按原样使用。
• 在其他 Outlook 客户端中，由 Office.context.mailbox.item.itemId 返回的值是适用于 EWS 格式的 ID，且必须使用 Office.context.mailbox.convertToRestId 方法进行转换。
• 请注意，还必须将附件 ID 转换为带 REST 格式的 ID，才能使用它。 必须转换 ID 的原因是，EWS ID 可能包含非 URL 安全值，这会导致 REST 问题出现。

通过检查 Office.context.mailbox.diagnostics.hostName 属性，加载项可以确定它所加载的是哪个 Outlook 客户端。

示例

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
    );
  }
}

获取 REST API URL

外接程序调用 REST API 所需的最后一部分信息是其发送 API 请求应使用的主机名。 此信息在 Office.context.mailbox.restUrl 属性中。

示例

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

调用 API

有访问令牌、项 ID 和 REST API URL 后，加载项可以将这些信息传递到调用 REST API 的后端服务，也可以使用 AJAX 直接调用 API。 下面的示例展示了如何调用 Outlook 邮件 REST API 来获取当前消息。

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.
  });
}

另请参阅

• 外接程序命令示例
• 从 Outlook 加载项使用 Microsoft Graph REST API