创建加密 Outlook 外接程序 (预览版)

在 Outlook 外接程序中实现自定义加密和解密功能，以保护电子邮件通信。 该 OnMessageRead 事件允许加载项自动识别加密消息并处理解密、内容显示和错误通知。

加密和解密工作流概述

下表概述了 Outlook 加载项的加密和解密工作流。 它还标识步骤是否需要自定义解决方案或 Office JavaScript (Office.js) API 库支持。

使用基于事件的激活实现解密

必须实现自己的加密和解密协议。 加载项还必须配置为处理事件， OnMessageRead 以便方便地确定加载项何时可以解密消息并显示解密的内容。 若要实现事件 OnMessageRead ，必须：

1. 配置加载项的清单。
2. 实现事件处理。

支持的环境

消息OnMessageRead读取图面支持事件。 支持因客户端和 Exchange 环境而异，如下表所示。

预览经典 Outlook on Windows 中的解密 API

若要预览经典 Outlook on Windows 中的解密 API，请加入 Microsoft 365 预览体验计划，然后选择 Outlook 客户端中的 Beta 版频道。 客户端必须位于版本 2510 (内部版本 19312.20000) 或更高版本上。

经典 Outlook on Windows 包括 Office.js 的生产和 beta 版本的本地副本，而不是从内容分发网络加载 (CDN) 。 默认情况下，将引用 API 的本地生产副本。 若要引用 API 的本地 beta 版副本，必须配置计算机的注册表。 这将使您能够在经典 Outlook on Windows 中的事件处理程序中测试 预览功能 。

1. 在注册表中，导航到 HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Outlook\Options\WebExt\Developer。 如果该键不存在，请创建它。

2. 创建名为 的 EnableBetaAPIsInJavaScript 条目，并将其值设置为 1。

   

配置清单

若要在事件上 OnMessageRead 激活加载项，必须配置 <加载项manifest.xml> 文件的 VersionOverridesV1_1 节点，如下所示。

• 若要在经典 Outlook on Windows 中运行基于事件的外接程序，必须在 Runtime> 元素的 Override 子元素中指定包含事件处理程序的< JavaScript 文件。<>
• 在 OnMessageReadLaunchEvent> 元素的< 属性中Type指定 事件。 必须将事件处理程序的函数名称分配给 FunctionName 元素的 属性。 为了便于检查消息是否已由加载项加密，必须在 属性中 HeaderName 指定标头密钥。 同一标头将添加到由加载项加密的消息中。

下面是实现 OnMessageRead 事件的节点示例<VersionOverrides>。

<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides" xsi:type="VersionOverridesV1_0">
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1" xsi:type="VersionOverridesV1_1">
    <Requirements>
      <bt:Sets DefaultMinVersion="1.15">
        <bt:Set Name="Mailbox"/>
      </bt:Sets>
    </Requirements>
    <Hosts>
      <Host xsi:type="MailHost">
        <Runtimes>
            <!-- References the HTML file that links to the event handler. -->
          <Runtime resid="WebViewRuntime.Url">
            <!-- References the JavaScript file that contains the event handler. This is used by classic Outlook on Windows. -->
            <Override type="javascript" resid="JSRuntime.Url"/>
          </Runtime>
        </Runtimes>
        <DesktopFormFactor>
          <FunctionFile resid="WebViewRuntime.Url"/>
          <!-- Implements event-based activation. -->
          <ExtensionPoint xsi:type="LaunchEvent">
            <LaunchEvents>
              <LaunchEvent Type="OnMessageSend" FunctionName="onMessageSendHandler" SendMode="SoftBlock"/>
              <LaunchEvent Type="OnMessageRead" FunctionName="onMessageReadHandler" HeaderName="contoso-encrypted"/>
            </LaunchEvents>
            <!-- Identifies the runtime to be used (also referenced by the Runtime element). -->
            <SourceLocation resid="WebViewRuntime.Url"/>
        </ExtensionPoint>
        </DesktopFormFactor>
      </Host>
    </Hosts>
    <Resources>
      ...
      <bt:Urls>
        <bt:Url id="WebViewRuntime.Url" DefaultValue="https://www.contoso.com/launchevent.html"/>
        <bt:Url id="JSRuntime.Url" DefaultValue="https://www.contoso.com/launchevent.js"/>
      </bt:Urls>
      ...
    </Resources>
  </VersionOverrides>
</VersionOverrides>

实现事件处理

事件处理程序 OnMessageRead 用于运行解密作，并确定是否显示消息的解密内容。

• 若要确保处理程序在事件发生时 OnMessageRead 运行，请在实现处理程序的 JavaScript 文件中调用 Office.actions.associate 。 这会将清单中 元素的 <LaunchEvent> 属性中指定的FunctionName处理程序名称映射到其 JavaScript 对应名称。
• 解密作完成后，必须调用 event.completed 以向客户端发出信号，指出加载项已完成事件处理 OnMessageRead 。 若要显示邮件及其附件的解密内容，请将 MessageDecryptEventCompletedOptions 对象传递给调用， event.completed 并将其 allowEvent 属性设置为 true。 然后，在对象的 emailBody 和 附件 属性中指定邮件的解密内容。 还可以在 contextData 属性中指定加载项可能需要处理的任何数据。 例如，可以存储自定义 Internet 标头，以在答复和转发方案中解密消息。

下面是事件处理程序的示例 OnMessageRead 。

function onMessageReadHandler(event) {
    // Your code to decrypt the contents of a message would appear here.
    ...

    // Use the results from your decryption process to display the decrypted contents of the message body and attachments.
    const decryptedBodyContent = "<p>Please find attached the recent report and its supporting documentation.</p>";
    const decryptedBody = {
        coercionType: Office.CoercionType.Html,
        content: decryptedBodyContent
    };

    // Decrypted content and properties of a file attachment.
    const decryptedPdfFile = "JVBERi0xLjQKJeLjz9MKNCAwIG9i...";
    const pdfFileName = "Fabrikam_Report_202509";

    // Decrypted content and properties of a mail item.
    const decryptedEmailFile = "VGhpcyBpcyBhIHRleHQgZmlsZS4=...";
    const emailFileName = "Fabrikam_Report_202508.eml";

    // Decrypted properties of a cloud attachment.
    const cloudFilePath = "https://contosostorage.com/reports/weekly_forecast.xlsx";
    const cloudFileName = "weekly_forecast.xlsx";

    // Decrypted content and properties of an inline image.
    const decryptedImageFile = "iVBORw0KGgoAAAANSUhEUgAA...";
    const imageFileName = "banner.png";
    const imageContentId = "image001.png@01DC1DD9.1A4AA300";

    const decryptedAttachments = [
      {
        attachmentType: Office.MailboxEnums.AttachmentType.File,
            content: decryptedPdfFile,
            isInline: false,
            name: pdfFileName
        },
        {
          attachmentType: Office.MailboxEnums.AttachmentType.Item,
            content: decryptedEmailFile,
            isInline: false,
            name: emailFileName
        },
        {
          attachmentType: Office.MailboxEnums.AttachmentType.Cloud,
            isInline: false,
            name: cloudFileName,
            path: cloudFilePath
        },
        {
          attachmentType: Office.MailboxEnums.AttachmentType.File,
            content: decryptedImageFile,
            contentId: imageContentId,
            isInline: true,
            name: imageFileName
        }
    ];

    event.completed({
        allowEvent: true,
        emailBody: decryptedBody,
        attachments: decryptedAttachments,
        contextData: { messageType: "ReplyFromDecryptedMessage" }
    });
}

// IMPORTANT: To ensure your add-in is supported in Outlook, remember to map the event handler name specified in the manifest to its JavaScript counterpart.
Office.actions.associate("onMessageReadHandler", onMessageReadHandler);

行为和限制

• 请注意基于事件的加载项的行为和限制。若要了解详细信息，请参阅 使用事件激活加载项。

• 由于每个外接程序都使用其自己的加密协议，因此消息只能由加密它的同一加载项解密。 如果用户未安装解密消息所需的加载项，则会发出通知，提醒他们消息已加密。 若要引导用户完成解密过程，请为加密邮件的正文自定义占位符消息。 占位符消息可以包含有关如何安装加载项的信息。 若要在加密过程中设置邮件正文，请调用 Office.context.mailbox.item.body.setAsync。

  

• 为确保数据安全性和机密性，已解密的内容不会存储在 Outlook 客户端上。 每次用户打开加密邮件时，都会解密该邮件的内容。

• 必须先解密加密邮件，然后用户才能答复或转发该邮件。 在解密加密邮件时，用户无法回复或转发该邮件。

• 如果用户在解密加密邮件时导航到另一个邮件项，则解密过程将停止运行。 用户必须再次选择或打开邮件才能激活解密过程。

• 答复或转发加密邮件时，草稿以未加密的方式保存在 “草稿 ”文件夹中。

解密通知

处理 OnMessageRead 事件的加载项在某些解密方案中自动显示通知，如下表所述。

另请参阅

• Office 加载项的隐私和安全性
• 使用事件激活加载项
• 排查基于事件的加载项和垃圾邮件报告加载项的问题
• 获取和设置 Outlook 加载项中邮件的 Internet 标头
• 在撰写模式下管理邮件或约会的敏感度标签