通过

实现集成的垃圾邮件报告加载项

  • 项目

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

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

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

注意

邮箱要求集 1.14 中引入了集成垃圾邮件报告。 有关此功能的客户端支持的信息，请参阅 支持的客户端。

支持的客户端

下表标识了哪些 Outlook 客户端支持集成的垃圾邮件报告功能。

客户端 状态
Outlook Web 版 支持
新的 Outlook on Windows 支持
经典 Outlook on Windows
版本 2404 (内部版本 17530.15000) 		支持
Mac 版 Outlook
版本 16.81 (23121700) 或更高版本		 预览 (请参阅预览 Outlook on Mac) 中的集成垃圾邮件报告功能
Android 版 Outlook 不可用
iOS 版 Outlook 不可用

预览 Outlook on Mac 中的集成垃圾邮件报告功能

若要预览 Outlook on Mac 中的集成垃圾邮件报告功能，必须安装版本 16.81.1217.0 或更高版本。 然后，加入 Microsoft 365 预览体验计划 ，并选择 “Beta 频道” 选项以访问 Office beta 版本。

设置环境

提示

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

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

配置清单

若要在外接程序中实现集成的垃圾邮件报告功能，必须在清单中配置以下内容。

  • 加载项使用的运行时。 在经典 Outlook on Windows 中，垃圾邮件报告加载项在 仅限 JavaScript 的运行时中运行。 在 Outlook 网页版 和 Mac 以及新的 Outlook on Windows 中，垃圾邮件报告加载项在浏览器运行时中运行。 有关详细信息，请参阅 Office 外接程序中的运行时。

  • 始终显示在 Outlook 功能区上醒目的位置的垃圾邮件报告加载项的按钮。 下面是 Windows 上经典 Outlook 客户端的功能区上如何显示垃圾邮件报告加载项的按钮的示例。 功能区 UI 可能因运行用户的 Outlook 客户端的平台而异。

    垃圾邮件报告加载项的示例功能区按钮。

  • 预处理对话框。 当用户选择加载项按钮时，会显示此对话框。 在此对话框中，用户可以提供有关他们正在报告的消息的其他信息。 当用户从对话框中选择“ 报告 ”时，将激活 SpamReporting 事件，然后由 JavaScript 事件处理程序处理。 下面是 Outlook on Windows 中的预处理对话框的示例。 请注意，对话框的外观可能因运行用户的 Outlook 客户端的平台而异。

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

选择要使用的清单类型的选项卡。

注意

使用 Microsoft 365 的统一清单实现集成的垃圾邮件报告以公共开发人员预览版提供。 它目前只能在经典 Outlook on Windows 中使用。 不应在生产加载项中使用此功能。我们邀请你在测试或开发环境中试用。 有关详细信息，请参阅 公共开发人员预览版应用清单架构。

  1. 在首选代码编辑器中，打开创建的外接程序项目。

  2. 打开 manifest.json 文件。

  3. 将以下 对象添加到“extensions.runtimes”数组。 关于此标记，请注意以下几点。

    • 邮箱要求集的“minVersion”配置为“1.14”。 这是支持集成垃圾邮件报告功能的要求集的最低版本。
    • 运行时的“id”设置为唯一的描述性名称“spam_reporting_runtime”。
    • “code”属性具有设置为 HTML 文件的子“page”属性和设置为 JavaScript 文件的子“script”属性。 稍后的步骤将创建或编辑这些文件。
    • “lifetime”属性设置为“short”。 这意味着运行时在事件发生时启动， SpamReporting 并在事件处理程序完成时关闭。
    • “actions”对象指定在运行时中运行的事件处理程序函数。 你将在后面的步骤中创建此函数。
    {
    "requirements": {
        "capabilities": [
            {
                "name": "Mailbox",
                "minVersion": "1.14"
            }
        ]
    },
    "id": "spam_reporting_runtime",
    "type": "general",
    "code": {
        "page": "https://localhost:3000/commands.html",
        "script": "https://localhost:3000/spamreporting.js"
    },
    "lifetime": "short",
    "actions": [
        {
            "id": "onSpamReport",
            "type": "executeFunction"
        }
    ]
},

  4. 将以下 对象添加到“extensions.ribbons”数组。 关于此标记，请注意以下几点。

    • “contexts”数组包含“spamReportingOverride”字符串。 这可以防止加载项按钮显示在功能区的末尾或溢出部分中。
    • “fixedControls”数组包含一个 对象，该对象配置功能区上加载项按钮的外观和功能。 在“actionId”属性中指定的事件处理程序的名称必须与“actions”数组中对象的“id”属性中使用的值匹配。 虽然“enabled”属性必须在数组中指定，但其值不会影响垃圾邮件报告加载项的功能。
    • “spamPreProcessingDialog”对象指定预处理对话框中显示的信息和选项。 虽然必须为对话框指定“title”和“description”，但可以选择配置以下属性。
      • “spamReportingOptions”对象。 它提供最多包含五个选项的多选列表。 这有助于用户识别他们报告的消息类型。
      • “spamFreeTextSectionTitle”属性。 它为用户提供了一个文本框，用于添加有关他们正在报告的邮件的详细信息。
      • “spamMoreInfo”对象。 它在对话框中包含一个链接，用于向用户提供信息资源。
    {
    "contexts": [
        "spamReportingOverride"
    ],
    "fixedControls": [
        {
            "id": "spamReportingButton",
            "type": "button",
            "label": "Report Spam Message",
            "enabled": false,
            "icons": [
                {
                    "size": 16,
                    "url": "https://localhost:3000/assets/icon-16.png"
                },
                {
                    "size": 32,
                    "url": "https://localhost:3000/assets/icon-32.png"
                },
                {
                    "size": 80,
                    "url": "https://localhost:3000/assets/icon-80.png"
                }
            ],
            "supertip": {
                "title": "Report Spam Message",
                "description": "Report an unsolicited message."
            },
            "actionId": "onSpamReport"
        }
    ],
    "spamPreProcessingDialog": {
        "title": "Report Spam Message",
        "description": "Thank you for reporting this message.",
        "spamReportingOptions": {
            "title": "Why are you reporting this email?",
            "options": [
                "Received spam email.",
                "Received a phishing email.",
                "I'm not sure this is a legitimate email."
            ]
        },
        "spamFreeTextSectionTitle": "Provide additional information, if any:",
        "spamMoreInfo": {
            "text": "Reporting unsolicited messages",
            "url": "https://www.contoso.com/spamreporting"
        }
    }
},

  5. 保存所做的更改。

提示

若要了解有关 Outlook 外接程序清单的详细信息，请参阅 Office 外接程序清单。

实现事件处理程序

当外接程序用于报告消息时，它会生成一个 SpamReporting 事件，然后由外接程序的 JavaScript 文件中的事件处理程序进行处理。 若要将清单中指定的事件处理程序的名称映射到其 JavaScript 对应名称，必须在代码中调用 Office.actions.associate 。

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

  2. 在 ./src/spamreporting 文件夹中，创建一个名为 spamreporting.js的新文件。

  3. 打开新创建的 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 Outlook, remember to map the event handler name specified in the manifest to its JavaScript counterpart.
Office.actions.associate("onSpamReport", onSpamReport);

  4. 保存所做的更改。

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

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

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

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

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

  1. 在 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 Outlook, remember to map the event handler name specified in the manifest to its JavaScript counterpart.
Office.actions.associate("onSpamReport", onSpamReport);

  2. 保存所做的更改。

注意

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

处理事件时发出信号

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

注意

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

  1. 在 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 Outlook, remember to map the event handler name specified in the manifest to its JavaScript counterpart
Office.actions.associate("onSpamReport", onSpamReport);

    注意

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

  2. 保存所做的更改。

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

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

提示

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

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

更新命令 HTML 文件

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

  2. 紧接在) (</head> 结束头标记之前，添加以下脚本条目。

    <script type="text/javascript" src="../spamreporting/spamreporting.js"></script>

    注意

    集成垃圾邮件报告功能目前在 Outlook on Mac 中提供预览版。 如果要在此客户端中测试该功能，则必须在 commands.html 文件中包含对 Office JavaScript API 预览版的引用。

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

  3. 保存所做的更改。

更新 Webpack 配置设置

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

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

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

  3. 保存所做的更改。

测试和验证加载项

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

查看功能行为和限制

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

  • 在 Outlook 网页版 和 Windows (新的和经典) 中，集成的垃圾邮件报告加载项取代了 Outlook 功能区中的本机“报告”按钮。 如果安装了多个垃圾邮件报告加载项，它们都将显示在功能区的“ 报告 ”部分中。

    一个示例集成垃圾邮件报告加载项，用于替换 Outlook 功能区中的“报告”按钮。

  • 垃圾邮件报告加载项在激活后最多可以运行 5 分钟。 超过五分钟的任何处理都将导致加载项超时。如果加载项超时，则会向用户显示一个对话框，以通知他们这一点。

    垃圾邮件报告加载项超时时显示的对话框。

  • 在经典 Outlook on Windows 中，垃圾邮件报告加载项可用于报告邮件，即使 Outlook 客户端的阅读窗格已关闭。 在 Outlook 网页版、Mac 和新的 Outlook on Windows 中，如果“阅读窗格”处于打开状态或要报告的邮件在另一个窗口中打开，则可以使用垃圾邮件报告加载项。

  • 一次只能报告一条消息。 如果选择多条消息进行报告，则垃圾邮件报告加载项的按钮将不可用。

  • 在经典 Outlook on Windows 中，一次只能处理一条报告的邮件。 如果用户尝试在处理上一封邮件时报告另一封邮件，则会显示一个对话框来通知他们。

    当用户尝试报告另一封邮件时，仍在处理上一封邮件时显示的对话框。

    这不适用于 Outlook 网页版、Mac 或 Windows 上的新 Outlook。 在这些 Outlook 客户端中，用户可以从阅读窗格报告邮件，并且可以同时报告在单独的窗口中打开的每封邮件。

  • 即使用户离开所选邮件，外接程序仍可处理报告的消息。 在 Outlook on Mac 中，仅当用户在单独的窗口中打开邮件时报告邮件时，才支持此功能。 如果用户在从阅读窗格查看邮件时报告邮件，然后导航离开它，则报告过程将终止。

  • 预处理和后处理对话框中出现的按钮不可自定义。 此外，无法修改超时和正在进行的报告对话框中的文本和按钮。

  • 集成的垃圾邮件报告和 基于事件的激活 功能必须使用相同的运行时。 Outlook 目前不支持多个运行时。 若要了解有关运行时的详细信息，请参阅 Office 外接程序中的运行时。

  • 垃圾邮件报告加载项仅实现 函数命令。 无法将任务窗格命令分配给功能区上的垃圾邮件报告按钮。 如果要在外接程序中实现任务窗格，必须在清单中对其进行配置，如下所示：

    请注意，用于激活任务窗格的单独按钮将添加到功能区，但它不会显示在功能区的专用垃圾邮件报告区域中。

排查加载项问题

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

另请参阅