获取和设置 Outlook 加载项中邮件的 Internet 标头

项目
05/02/2024

背景

Outlook 外接程序开发中的一个常见要求是在不同级别存储与外接程序关联的自定义属性。目前，自定义属性存储在项目或邮箱级别。

项级别 - 对于应用于特定项的属性，请使用 CustomProperties 对象。例如，存储与发送电子邮件的人员关联的客户代码。
邮箱级别 - 对于应用于用户邮箱中所有邮件项的属性，请使用 RoamingSettings 对象。例如，存储用户的首选项，以在特定刻度中显示温度。

项目离开 Exchange 服务器后，不会保留这两种类型的属性，因此电子邮件收件人无法获取针对该项目设置的任何属性。因此，开发人员无法访问这些设置或其他多用途 Internet 邮件扩展 (MIME) 属性来实现更好的读取方案。

虽然可以通过 Exchange Web Services (EWS) 请求设置 Internet 标头，但在某些情况下，发出 EWS 请求不起作用。例如，在 Outlook 桌面版的“撰写”模式下，项目 ID 不会在缓存模式下 saveAsync 同步。

提示

若要详细了解如何使用这些选项，请参阅获取和设置 Outlook 加载项的外接程序元数据。

Internet 标头 API 的用途

在邮箱要求集 1.8 中引入的 Internet 标头 API 使开发人员能够：

在电子邮件上标记信息，该电子邮件在离开 Exchange 后保留在所有客户端上。
阅读电子邮件在电子邮件离开 Exchange 后在邮件读取方案中跨所有客户端保留的电子邮件的信息。
访问电子邮件的整个 MIME 标头。

Internet 标头示意图。文本：用户 1 发送电子邮件。加载项在用户撰写电子邮件时管理自定义 Internet 标头。用户 2 收到电子邮件。加载项从收到的电子邮件获取 Internet 标头，然后分析和使用自定义标头。

支持的客户端

若要在外接程序中使用 Internet 标头 API，Outlook 客户端必须支持要求集 1.8 或更高版本。有关支持的客户端的信息，请参阅 Outlook 客户端支持。

从版本 4.2405.0 开始，Android 版和 iOS 上也支持 Internet 标头 API。若要详细了解移动设备上的 Outlook 支持的功能，请参阅移动设备上的 Outlook 支持的 Outlook JavaScript API。

撰写邮件时设置 Internet 标头

使用 item.internetHeaders 属性可以管理在撰写模式下放置在当前邮件上的自定义 Internet 标头。

设置、获取和删除自定义 Internet 标头示例

以下示例演示如何设置、获取和删除自定义 Internet 标头。

// Set custom internet headers.
function setCustomHeaders() {
  Office.context.mailbox.item.internetHeaders.setAsync(
    { "preferred-fruit": "orange", "preferred-vegetable": "broccoli", "best-vegetable": "spinach" },
    setCallback
  );
}

function setCallback(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Successfully set headers");
  } else {
    console.log("Error setting headers: " + JSON.stringify(asyncResult.error));
  }
}

// Get custom internet headers.
function getSelectedCustomHeaders() {
  Office.context.mailbox.item.internetHeaders.getAsync(
    ["preferred-fruit", "preferred-vegetable", "best-vegetable", "nonexistent-header"],
    getCallback
  );
}

function getCallback(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Selected headers: " + JSON.stringify(asyncResult.value));
  } else {
    console.log("Error getting selected headers: " + JSON.stringify(asyncResult.error));
  }
}

// Remove custom internet headers.
function removeSelectedCustomHeaders() {
  Office.context.mailbox.item.internetHeaders.removeAsync(
    ["best-vegetable", "nonexistent-header"],
    removeCallback);
}

function removeCallback(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Successfully removed selected headers");
  } else {
    console.log("Error removing selected headers: " + JSON.stringify(asyncResult.error));
  }
}

setCustomHeaders();
getSelectedCustomHeaders();
removeSelectedCustomHeaders();
getSelectedCustomHeaders();

/* Sample output:
Successfully set headers
Selected headers: {"best-vegetable":"spinach","preferred-fruit":"orange","preferred-vegetable":"broccoli"}
Successfully removed selected headers
Selected headers: {"preferred-fruit":"orange","preferred-vegetable":"broccoli"}
*/

阅读邮件时获取 Internet 标头

调用 item.getAllInternetHeadersAsync 以在读取模式下获取当前邮件上的 Internet 标头。

从当前 MIME 标头示例获取发件人首选项

基于上一部分的示例，以下代码演示如何从当前电子邮件的 MIME 标头获取发件人的首选项。

Office.context.mailbox.item.getAllInternetHeadersAsync(getCallback);

function getCallback(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Sender's preferred fruit: " + asyncResult.value.match(/preferred-fruit:.*/gim)[0].slice(17));
    console.log("Sender's preferred vegetable: " + asyncResult.value.match(/preferred-vegetable:.*/gim)[0].slice(21));
  } else {
    console.log("Error getting preferences from header: " + JSON.stringify(asyncResult.error));
  }
}

/* Sample output:
Sender's preferred fruit: orange
Sender's preferred vegetable: broccoli
*/

重要

此示例适用于简单情况。对于更复杂的信息检索 (例如，如 RFC 2822) 中所述的多实例标头或折叠值，请尝试使用适当的 MIME 分析库。

建议的做法

目前，Internet 标头是用户邮箱上的有限资源。当配额用尽时，你无法在该邮箱上创建任何其他 Internet 标头，这可能会导致依赖此标头的客户端出现意外行为。

在外接程序中创建 Internet 标头时，请遵循以下准则。

Create所需的最小标头数。标头配额基于应用于消息的标头的总大小。在 Exchange Online 中，标头限制上限为 256 KB，而在 Exchange 本地环境中，该限制由组织的管理员确定。有关标头限制的详细信息，请参阅Exchange Online消息限制和Exchange Server消息限制。
命名标头，以便稍后可以重用和更新其值。因此，请避免以可变方式命名标头， (例如，基于用户输入、时间戳等 ) 。

另请参阅

获取和设置 Outlook 加载项的元数据

通过