实现集成的垃圾邮件报告外接程序 (预览)

项目
05/03/2024

随着未经请求的电子邮件数量的增加，安全性一直处于加载项使用的最前沿。目前，合作伙伴垃圾邮件报告加载项已添加到 Outlook 功能区，但它们通常显示在功能区末尾或溢出菜单中。这使得用户更难找到加载项来报告未经请求的电子邮件。除了配置在报告消息时处理消息的方式外，开发人员还需要完成其他任务，以便向用户显示处理对话或补充信息。

集成的垃圾邮件报告功能简化了从头开始开发单个外接程序组件的任务。更重要的是，它会在 Outlook 功能区上的醒目位置显示加载项，使用户更容易找到它并报告垃圾邮件。在加载项中实现此功能，以便：

改进主动邮件的跟踪方式。
为用户提供有关如何报告可疑邮件的更好指导。
使组织的安全运营中心 (SOC) 或 IT 管理员轻松执行垃圾邮件和网络钓鱼模拟以用于教育目的。

重要

集成的垃圾邮件报告功能目前在经典 Outlook on Windows 和 Outlook on Mac 中处于预览状态。 Outlook 网页版和新的 Outlook on Windows (预览版) 中此功能的预览支持目前正在推出。

不应在生产加载项中使用预览版功能。我们邀请你在测试或开发环境中试用此功能，并欢迎通过 GitHub 提供有关体验的反馈 (请参阅本页末尾的反馈部分) 。

预览集成的垃圾邮件报告功能

若要预览集成的垃圾邮件报告功能，必须具有以下受支持的客户端之一。

经典 Outlook on Windows 版本 2307 (内部版本 16626.10000) 或更高版本。必须加入 Microsoft 365 预览体验计划，并选择 “Beta 频道 ”选项才能访问 Office beta 版本。
Outlook on Mac 版本 16.81.1217.0 或更高版本。必须加入 Microsoft 365 预览体验计划，并选择 “Beta 频道 ”选项才能访问 Office beta 版本。

注意

当前正在推出对 Outlook 网页版中集成垃圾邮件报告功能的预览支持，以及新的 Windows 版 Outlook (预览版) 。推出预览版后，必须在 Microsoft 365 租户上配置目标版本才能访问 Office beta 版本。

提示

如果无法在 Windows 上的 Outlook 客户端中选择频道，请参阅让用户选择要在 Windows 设备上安装的 Microsoft 365 预览体验成员频道。

设置环境

提示

若要立即试用已完成的垃圾邮件报告加载项解决方案，请参阅在 Outlook (预览版中报告垃圾邮件或钓鱼电子邮件) 示例。

完成 Outlook 快速入门，使用 Office 加载项的 Yeoman 生成器创建加载项项目。

配置清单

注意

Microsoft 365 的统一清单尚不支持集成垃圾邮件报告。

若要在外接程序中实现集成的垃圾邮件报告功能，必须相应地配置清单的 VersionOverridesV1_1 节点。

在 Outlook 网页版和 Mac 以及新的 Outlook on Windows 中，实现集成垃圾邮件报告功能的加载项在浏览器运行时中运行。必须在 Runtime 元素的属性中resid指定引用或包含用于处理垃圾邮件报告事件的代码的 HTML 文件。
在经典 Outlook on Windows 中，实现集成垃圾邮件报告功能的加载项在仅限 JavaScript 的运行时中运行。因此，必须指定 JavaScript 文件，该文件包含用于在 Runtime> 元素的 Override 子元素<中处理垃圾邮件报告事件的代码。
若要在 Outlook 功能区中激活加载项并阻止其显示在功能区末尾或溢出部分中，请将 ExtensionPoint> 元素的< 属性设置为 xsi:typeReportPhishingCommandSurface。
若要自定义功能区按钮和预处理对话框，必须定义 ReportPhishingCustomization 节点。
- 用户通过功能区中的加载项按钮报告未经请求的消息。若要配置功能区按钮，请将 Control 元素的属性设置为 Buttonxsi:type 。然后，将 xsi:typeAction 子元素的属性设置为 ExecuteFunction ，并在其 <FunctionName> 子元素中指定垃圾邮件报告事件处理程序的名称。垃圾邮件报告加载项只能实现函数命令。
  
  下面是垃圾邮件报告加载项按钮在 Windows 上的 Outlook 客户端功能区上的显示方式的示例。功能区 UI 可能因运行用户的 Outlook 客户端的平台而异。
- 当用户选择加载项按钮时，预处理对话框会显示给用户。它是通过清单的 PreProcessingDialog 元素配置的。虽然对话框必须具有标题和说明，但可以选择包含以下元素。
  - 多选选项列表，可帮助用户识别他们报告的邮件类型。若要了解如何配置这些报告选项，请参阅 ReportingOptions 元素。
  - 一个文本框，供用户提供有关他们正在报告的邮件的其他信息。若要了解如何实现文本框，请参阅 FreeTextLabel 元素。
  - 用于向用户提供信息资源的自定义文本和 URL。若要了解如何个性化这些元素，请参阅 MoreInfo 元素。
  当用户从对话框中选择“ 报告 ”时，将激活 SpamReporting 事件，然后由 JavaScript 事件处理程序处理。
  
  下面是 Outlook on Windows 中的预处理对话框的示例。请注意，对话框的外观可能因运行用户的 Outlook 客户端的平台而异。

下面是为垃圾邮件报告配置的 VersionOverrides> 节点的示例<。

在首选代码编辑器中，打开创建的外接程序项目。
打开位于项目根目录处的 manifest.xml 文件。

选择整个 <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.13">
        <bt:Set Name="Mailbox"/>
      </bt:Sets>
    </Requirements>
    <Hosts>
      <Host xsi:type="MailHost">
        <Runtimes>
            <!-- References the HTML file that links to the spam-reporting event handler.
                 This is used by Outlook on the web and on the new Mac UI, and new Outlook on Windows (preview). -->
          <Runtime resid="WebViewRuntime.Url">
            <!-- References the JavaScript file that contains the spam-reporting event handler. This is used by classic Outlook on Windows. -->
            <Override type="javascript" resid="JSRuntime.Url"/>
          </Runtime>
        </Runtimes>
        <DesktopFormFactor>
          <FunctionFile resid="WebViewRuntime.Url"/>
          <!-- Implements the integrated spam-reporting feature in the add-in. -->
          <ExtensionPoint xsi:type="ReportPhishingCommandSurface">
            <ReportPhishingCustomization>
              <!-- Configures the ribbon button. -->
              <Control xsi:type="Button" id="spamReportingButton">
                <Label resid="spamButton.Label"/>
                <Supertip>
                  <Title resid="spamButton.Label"/>
                  <Description resid="spamSuperTip.Text"/>
                </Supertip>
                <Icon>
                  <bt:Image size="16" resid="Icon.16x16"/>
                  <bt:Image size="32" resid="Icon.32x32"/>
                  <bt:Image size="80" resid="Icon.80x80"/>
                </Icon>
                <Action xsi:type="ExecuteFunction">
                  <FunctionName>onSpamReport</FunctionName>
                </Action>
              </Control>
              <!-- Configures the preprocessing dialog. -->
              <PreProcessingDialog>
                <Title resid="PreProcessingDialog.Label"/>
                <Description resid="PreProcessingDialog.Text"/>
                <ReportingOptions>
                  <Title resid="OptionsTitle.Label"/>
                  <Option resid="Option1.Label"/>
                  <Option resid="Option2.Label"/>
                  <Option resid="Option3.Label"/>
                </ReportingOptions>
                <FreeTextLabel resid="FreeText.Label"/>
                <MoreInfo>
                  <MoreInfoText resid="MoreInfo.Label"/>
                  <MoreInfoUrl resid="MoreInfo.Url"/>
                </MoreInfo>
              </PreProcessingDialog>
             <!-- Identifies the runtime to be used. This is also referenced by the Runtime element. -->
              <SourceLocation resid="WebViewRuntime.Url"/>
            </ReportPhishingCustomization> 
          </ExtensionPoint>
        </DesktopFormFactor>
      </Host>
    </Hosts>
    <Resources>
      <bt:Images>
        <bt:Image id="Icon.16x16" DefaultValue="https://localhost:3000/assets/icon-16.png"/>
        <bt:Image id="Icon.32x32" DefaultValue="https://localhost:3000/assets/icon-32.png"/>
        <bt:Image id="Icon.80x80" DefaultValue="https://localhost:3000/assets/icon-80.png"/>
      </bt:Images>
      <bt:Urls>
        <bt:Url id="WebViewRuntime.Url" DefaultValue="https://localhost:3000/commands.html"/>
        <bt:Url id="JSRuntime.Url" DefaultValue="https://localhost:3000/spamreporting.js"/>
        <bt:Url id="MoreInfo.Url" DefaultValue="https://www.contoso.com/spamreporting"/>
      </bt:Urls>
      <bt:ShortStrings>
        <bt:String id="spamButton.Label" DefaultValue="Report Spam Message"/>
        <bt:String id="PreProcessingDialog.Label" DefaultValue="Report Spam Message"/>
        <bt:String id="OptionsTitle.Label" DefaultValue="Why are you reporting this email?"/>
        <bt:String id="FreeText.Label" DefaultValue="Provide additional information, if any:"/>
        <bt:String id="MoreInfo.Label" DefaultValue="To learn more about reporting unsolicited messages, see "/>
        <bt:String id="Option1.Label" DefaultValue="Received spam email."/>
        <bt:String id="Option2.Label" DefaultValue="Received a phishing email."/>
        <bt:String id="Option3.Label" DefaultValue="I'm not sure this is a legitimate email."/>
      </bt:ShortStrings>
      <bt:LongStrings>
        <bt:String id="spamSuperTip.Text" DefaultValue="Report an unsolicited message."/>
        <bt:String id="PreProcessingDialog.Text" DefaultValue="Thank you for reporting this message."/>
      </bt:LongStrings>
    </Resources>
  </VersionOverrides>
</VersionOverrides>

保存所做的更改。

实现事件处理程序

当外接程序用于报告邮件时，它会生成 SpamReporting 事件，然后由外接程序的 JavaScript 文件中的事件处理程序处理该事件。若要将清单的 <FunctionName> 元素中指定的事件处理程序的名称映射到其 JavaScript 对应项，必须在代码中调用 Office.actions.associate 。

在外接程序项目中，导航到 ./src 目录。然后，创建名为 spamreporting 的新文件夹。
在 ./src/spamreporting 文件夹中，创建一个名为 spamreporting.js的新文件。

打开新创建的 spamreporting.js 文件并添加以下 JavaScript 代码。

// Handles the SpamReporting event to process a reported message.
function onSpamReport(event) {
  // TODO - Send a copy of the reported message.

  // TODO - Get the user's responses.

  // TODO - Signal that the spam-reporting event has completed processing.
}

// IMPORTANT: To ensure your add-in is supported in the Outlook client on Windows, remember to map the event handler name specified in the manifest to its JavaScript counterpart.
if (Office.context.platform === Office.PlatformType.PC || Office.context.platform == null) {
  Office.actions.associate("onSpamReport", onSpamReport);
}

保存所做的更改。

转发消息的副本并获取预处理对话响应

事件处理程序负责处理报告的消息。可以将其配置为将信息（如邮件副本或用户在预处理对话框中选择的选项）转发到内部系统，以便进一步调查。

若要有效地发送报告的消息副本，请在事件处理程序中调用 getAsFileAsync 方法。这会获取消息的 Base64 编码 EML 格式，然后可以将其转发到内部系统。

重要

若要在 getAsFileAsync Outlook on Windows 中仍处于预览状态时测试该方法，必须配置计算机的注册表。

Windows 版 Outlook 包含 Office.js 的生产和 beta 版本的本地副本，而不是从内容分发网络加载 (CDN) 。默认情况下，将引用 API 的本地生产副本。若要引用 API 的本地 beta 版副本，必须按如下所示配置计算机的注册表：

在注册表中，导航到 HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Outlook\Options\WebExt\Developer。如果该键不存在，请创建它。
Create名为 EnableBetaAPIsInJavaScript 的条目，并将其值设置为 1。

如果需要跟踪用户对预处理对话框中选项和文本框的响应，请从SpamReporting事件对象中提取 options 和 freeText 值。有关这些属性的详细信息，请参阅 Office.SpamReportingEventArgs。

下面是垃圾邮件报告事件处理程序的示例，该处理程序调用 getAsFileAsync 方法并从事件对象获取用户的响应 SpamReporting 。

在 spamreporting.js 文件中，将其内容替换为以下代码。

// Handles the SpamReporting event to process a reported message.
function onSpamReport(event) {
  // Get the Base64-encoded EML format of a reported message.
  Office.context.mailbox.item.getAsFileAsync({ asyncContext: event }, (asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
      console.log(`Error encountered during message processing: ${asyncResult.error.message}`);
      return;
    }

    // Get the user's responses to the options and text box in the preprocessing dialog.
    const spamReportingEvent = asyncResult.asyncContext;
    const reportedOptions = spamReportingEvent.options;
    const additionalInfo = spamReportingEvent.freeText;

    // Run additional processing operations here.

    // TODO - Signal that the spam-reporting event has completed processing.
  });
}

// IMPORTANT: To ensure your add-in is supported in the Outlook client on Windows, remember to map the event handler name specified in the manifest to its JavaScript counterpart.
if (Office.context.platform === Office.PlatformType.PC || Office.context.platform == null) {
  Office.actions.associate("onSpamReport", onSpamReport);
}

保存所做的更改。

注意

若要在垃圾邮件报告外接程序中配置单一登录 (SSO) 或跨源资源共享 (CORS) ，必须将加载项及其 JavaScript 文件添加到已知 URI。有关如何配置此资源的指南，请参阅使用单一登录 (SSO) 或跨源资源共享 (CORS) 基于事件或垃圾邮件报告的 Outlook 外接程序。

处理事件时发出信号

事件处理程序完成消息处理后，必须调用 event.completed 方法。除了向加载项发出已处理垃圾邮件报告事件的信号外， event.completed 还可用于自定义后处理对话框，以便向用户显示或对邮件执行其他操作，例如从收件箱中删除邮件。有关可以包含在 JSON 对象中以参数 event.completed 形式传递给方法的属性列表，请参阅 Office.SpamReportingEventCompletedOptions。

注意

在调用后 event.completed 添加的代码不一定能够运行。

在 spamreporting.js 文件中，将其内容替换为以下代码。

// Handles the SpamReporting event to process a reported message.
function onSpamReport(event) {
  // Get the Base64-encoded EML format of a reported message.
  Office.context.mailbox.item.getAsFileAsync({ asyncContext: event }, (asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
      console.log(`Error encountered during message processing: ${asyncResult.error.message}`);
      return;
    }

    // Get the user's responses to the options and text box in the preprocessing dialog.
    const spamReportingEvent = asyncResult.asyncContext;
    const reportedOptions = spamReportingEvent.options;
    const additionalInfo = spamReportingEvent.freeText;

    // Run additional processing operations here.

    /**
     * Signals that the spam-reporting event has completed processing.
     * It then moves the reported message to the Junk Email folder of the mailbox, then
     * shows a post-processing dialog to the user. If an error occurs while the message
     * is being processed, the `onErrorDeleteItem` property determines whether the message
     * will be deleted.
     */
    const event = asyncResult.asyncContext;
    event.completed({
      onErrorDeleteItem: true,
      moveItemTo: Office.MailboxEnums.MoveSpamItemTo.JunkFolder,
      showPostProcessingDialog: {
        title: "Contoso Spam Reporting",
        description: "Thank you for reporting this message.",
      },
    });
  });
}

// IMPORTANT: To ensure your add-in is supported in the Outlook client on Windows, remember to map the event handler name specified in the manifest to its JavaScript counterpart
if (Office.context.platform === Office.PlatformType.PC || Office.context.platform == null) {
  Office.actions.associate("onSpamReport", onSpamReport);
}

注意

如果你使用的是经典 Outlook on Windows 版本 2308 (内部版本 16724.10000) 或更高版本、Mac 版 Outlook、Outlook 网页版版或 Windows 版新版 Outlook (预览版) ，则必须在moveItemTo调用中使用 event.completed 属性来指定在加载项处理报告邮件后将邮件移动到的文件夹。在支持集成垃圾邮件报告功能的 Windows 上的早期 Outlook 版本上，必须使用 postProcessingAction 属性。

保存所做的更改。

下面是加载项在 Windows 版 Outlook 中处理报告邮件后向用户显示的示例后处理对话框。请注意，对话框的外观可能因运行用户的 Outlook 客户端的平台而异。

加载项处理报告的垃圾邮件后显示后处理对话框的示例。

提示

开发将在 Outlook on Windows 中运行的垃圾邮件报告加载项时，请记住以下几点。

包含用于处理垃圾邮件报告事件的代码的 JavaScript 文件中当前不支持导入。
和 Office.initialize 函数中包含的Office.onReady()代码不会运行。必须改为将任何加载项启动逻辑（例如检查用户的 Outlook 版本）添加到事件处理程序。

更新命令 HTML 文件

在 ./src/commands 文件夹中，打开 commands.html。

紧接在关闭头标记 (</head>) 之前，将现有脚本条目替换为以下代码。

<script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/beta/hosted/office.js"></script>
<script type="text/javascript" src="../spamreporting/spamreporting.js"></script>

保存所做的更改。

更新 Webpack 配置设置

从外接程序项目的根目录中，打开 webpack.config.js 文件。

plugins在对象中找到数组，config并将此新对象添加到数组的开头。

new CopyWebpackPlugin({
  patterns: [
    {
      from: "./src/spamreporting/spamreporting.js",
      to: "spamreporting.js",
    },
  ],
}),

保存所做的更改。

测试和验证加载项

在支持的 Outlook 客户端中旁加载加载项。
从收件箱中选择一封邮件，然后从功能区中选择加载项的按钮。
在预处理对话框中，选择报告消息的原因，并添加有关消息的信息（如果已配置）。然后，选择“ 报表”。
(可选) 在后期处理对话框中，选择“ 确定”。

查看功能行为和限制

在加载项中开发和测试集成的垃圾邮件报告功能时，请注意其特征和限制。

垃圾邮件报告加载项在激活后最多可以运行 5 分钟。超过五分钟的任何处理都将导致加载项超时。如果加载项超时，则会向用户显示一个对话框，以通知他们这一点。
垃圾邮件报告加载项可用于报告邮件，即使 Outlook 客户端的阅读窗格已关闭。但是，Outlook on Mac 不支持此操作。在 Outlook on Mac 中，必须打开阅读窗格才能使用垃圾邮件报告加载项。
在经典 Outlook on Windows 中，一次只能报告一条消息。如果用户尝试在处理上一封邮件时报告另一封邮件，则会向他们显示一个对话框来通知他们。

这不适用于 Outlook on Mac 或 Web 版，也不适用于新的 Windows 版 Outlook (预览版) 。在这些 Outlook 客户端中，用户可以从阅读窗格报告邮件，并且可以同时报告在单独的窗口中打开的每封邮件。
即使用户离开所选邮件，外接程序仍可处理报告的消息。在 Outlook on Mac 中，仅当用户在单独的窗口中打开邮件时报告邮件时，才支持此功能。如果用户在从阅读窗格查看邮件时报告邮件，然后导航离开它，则报告过程将终止。
预处理和后处理对话框中出现的按钮不可自定义。此外，无法修改超时和正在进行的报告对话框中的文本和按钮。
集成的垃圾邮件报告和基于事件的激活功能必须使用相同的运行时。 Outlook 目前不支持多个运行时。若要了解有关运行时的详细信息，请参阅 Office 外接程序中的运行时。
无法将任务窗格命令分配给功能区上的垃圾邮件报告按钮。如果要在外接程序中实现任务窗格，则必须在清单中包含 Action 元素，并将其属性设置为 xsi:typeShowTaskpane。请注意，用于激活任务窗格的单独按钮将添加到功能区，但它不会显示在功能区的专用垃圾邮件报告区域中。

排查加载项问题

开发垃圾邮件报告加载项时，可能需要排查加载项未加载等问题。有关如何排查垃圾邮件报告加载项的指南，请参阅基于事件的加载项和垃圾邮件报告加载项疑难解答。