从 Outlook 加载项使用 Outlook REST API

项目
02/12/2024

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

重要

弃用 Outlook REST v2.0 和 beta 终结点

Outlook REST v2.0 和 beta 终结点将于 2024 年 3 月 31 日完全弃用。但是，在 2025 年 10 月 14 日 Outlook 2019 的扩展支持结束之前，私下发布的加载项和 AppSource 托管的加载项可以使用 REST 服务。将自动标识来自这些加载项的流量以免除。此豁免也适用于在停用日期之后开发的新加载项。

尽管加载项能够在 2025 年之前使用 REST 服务，但我们强烈建议你迁移加载项以使用 Microsoft Graph。有关指导，请参阅比较 Microsoft Graph 和 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 来获取当前消息。

重要

对于本地 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.
  });
}

另请参阅

有关从 Outlook 加载项调用 REST API 的示例，请参阅 GitHub 上的 command-demo。
Outlook REST API 也可通过 Microsoft Graph 终结点获得，但存在一些关键区别，包括加载项如何获取访问令牌。有关详细信息，请参阅通过 Microsoft Graph 使用的 Outlook REST API。