Share via

Реализация интегрированной надстройки отчетов о нежелательной почты

  • Статья

С ростом числа незапрошенных сообщений электронной почты безопасность находится на переднем крае использования надстроек. В настоящее время партнерские надстройки, сообщая о спаме, добавляются на ленту Outlook, но обычно они отображаются в конце ленты или в меню переполнения. Это затрудняет поиск надстройки, чтобы сообщить о нежелательных сообщениях электронной почты. В дополнение к настройке обработки сообщений при их отправке разработчикам также необходимо выполнить дополнительные задачи, чтобы показать пользователю диалоговые окна обработки или дополнительные сведения.

Встроенная функция создания отчетов о спаме упрощает задачу разработки отдельных компонентов надстроек с нуля. Что еще важнее, надстройка отображается в видном месте на ленте Outlook, что упрощает пользователям ее поиск и отправку сообщений нежелательной почты. Реализуйте эту функцию в надстройке, чтобы:

  • Улучшение отслеживания незапрошенных сообщений.
  • Предоставление пользователям более качественных рекомендаций о том, как сообщать о подозрительных сообщениях.
  • Позволить центру управления безопасностью организации (SOC) или ИТ-администраторам легко выполнять имитацию спама и фишинга в образовательных целях.

Примечание.

Интегрированные отчеты о нежелательной почте появились в наборе обязательных для почтовых ящиков 1.14. Сведения о поддержке клиентов для этой функции см. в разделе Поддерживаемые клиенты.

Поддерживаемые клиенты

В следующей таблице показано, какие клиенты Outlook поддерживают встроенную функцию создания отчетов о спаме.

Клиент Состояние
Outlook в Интернете Поддерживается
новый Outlook в Windows (предварительная версия) Поддерживается
классический Outlook в Windows
Версия 2404 (сборка 17530.15000)		 Поддерживается
Outlook для Mac
Версия 16.81.1217.0 или более поздняя		 Предварительная версия (см . раздел Предварительный просмотр встроенной функции создания отчетов о нежелательной почте в Outlook на Mac)
Outlook для Android Недоступно
Outlook для iOS Недоступно

Предварительная версия встроенной функции создания отчетов о нежелательной почте в Outlook на Mac

Чтобы просмотреть встроенную функцию отчетов о спаме в Outlook на Mac, необходимо установить версию 16.81.1217.0 или более позднюю. Затем присоединитесь к программе предварительной оценки Microsoft 365 и выберите параметр Канал бета-версии , чтобы получить доступ к бета-сборкам Office.

Настройка среды

Совет

Чтобы немедленно опробовать готовое решение для создания отчетов о спаме, см. пример сообщения о спаме или фишинге в Outlook .

Выполните краткое руководство по Outlook, в котором создается проект надстройки с генератором Yeoman для надстроек Office.

Настройка манифеста

Примечание.

Интегрированные отчеты о спаме пока не поддерживаются для единого манифеста Microsoft 365.

Чтобы реализовать встроенную функцию отчетности о нежелательной почте в надстройке, необходимо соответствующим образом настроить VersionOverridesV1_1 узле манифеста.

  • В Outlook в Интернете и mac, а также в новом Outlook для Windows надстройка, реализующая встроенную функцию создания отчетов о спаме, запускается в среде выполнения браузера. Необходимо указать HTML-файл, который ссылается на или содержит код для обработки события нежелательной почты в resid атрибуте элемента Runtime .
  • В классической версии Outlook для Windows надстройка, реализующая встроенную функцию создания отчетов о спаме, выполняется в среде выполнения, доступной только для JavaScript. Таким образом, необходимо указать файл JavaScript, содержащий код для обработки события сообщения о нежелательной почты в дочернем элементе<Переопределения элемента Runtime> .
  • Чтобы активировать надстройку на ленте Outlook и запретить ее появление в конце ленты или в разделе переполнения, задайте xsi:type атрибуту <элемента ExtensionPoint>значение ReportPhishingCommandSurface.
  • Чтобы настроить кнопку ленты и диалоговое окно предварительной обработки, необходимо определить узел ReportPhishingCustomization .

    • Пользователь сообщает о непрошенном сообщении с помощью кнопки надстройки на ленте. Чтобы настроить кнопку ленты, присвойте xsi:type атрибуту элемента Control значение Button. Затем задайте атрибуту xsi:type дочернего элемента ExecuteFunctionAction значение и укажите имя обработчика событий, сообщающего о спаме, в его <дочернем элементе FunctionName>. Надстройка со сведениями о спаме может реализовывать только команды функции.

      Ниже приведен пример того, как кнопка надстройки, сообщающей о спаме, отображается на ленте клиента Outlook в Windows. Пользовательский интерфейс ленты может отличаться в зависимости от платформы, на которую работает клиент Outlook пользователя.

      Пример кнопки ленты надстройки, сообщающей о спаме.

    • Диалоговое окно предварительной обработки отображается пользователю при нажатии кнопки надстройки. Он настраивается с помощью элемента PreProcessingDialog манифеста. Хотя диалоговое окно должно содержать заголовок и описание, при необходимости можно включить следующие элементы.

      • Список вариантов с множественным выбором, помогающий пользователю определить тип сообщения, о который он сообщает. Сведения о настройке этих параметров отчетов см. в разделе Элемент ReportingOptions.
      • Текстовое поле, в которое пользователь может указать дополнительные сведения о сообщении, которое он сообщает. Сведения о реализации текстового поля см. в разделе Элемент FreeTextLabel.
      • Пользовательский текст и URL-адрес для предоставления пользователю информационных ресурсов. Сведения о том, как персонализировать эти элементы, см. в разделе Элемент MoreInfo.

      Когда пользователь выбирает отчет в диалоговом окне, событие SpamReporting активируется, а затем обрабатывается обработчиком событий JavaScript.

      Ниже приведен пример диалогового окна предварительной обработки в Outlook в Windows. Обратите внимание, что внешний вид диалогового окна может отличаться в зависимости от платформы, на которую работает клиент Outlook пользователя.

      Пример диалогового окна предварительной обработки надстройки, сообщающей о спаме.

Ниже приведен пример узла VersionOverrides, настроенного< для создания отчетов о нежелательной почте>.

  1. В предпочитаемом редакторе кода откройте созданный проект надстройки.

  2. Откройте файлmanifest.xml , расположенный в корне проекта.

  3. Выберите весь <узел VersionOverrides> (включая теги open и close) и замените его следующим кодом.

    <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.14">
        <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>

  4. Сохраните изменения.

Реализация обработчика событий

Когда надстройка используется для отправки сообщения, она создает событие SpamReporting , которое затем обрабатывается обработчиком событий в файле JavaScript надстройки. Чтобы сопоставить имя обработчика событий, указанного в элементе <FunctionName> манифеста, с его аналогом 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 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);
}

  4. Сохраните изменения.

Переадресация копии сообщения и получение ответов диалога предварительной обработки

Обработчик событий отвечает за обработку сообщаемого сообщения. Его можно настроить для пересылки информации, например копии сообщения или параметров, выбранных пользователем в диалоговом окне предварительной обработки, во внутреннюю систему для дальнейшего изучения.

Чтобы эффективно отправить копию сообщения, вызовите метод getAsFileAsync в обработчике событий. При этом будет получено сообщение в формате EML в кодировке Base64, которое затем можно перенаправить во внутреннюю систему.

Если необходимо отслеживать ответы пользователя на параметры и текстовое поле в диалоговом окне предварительной обработки, извлеките options значения и freeText из SpamReporting объекта события. Дополнительные сведения об этих свойствах см. в статье 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 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);
}

  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 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 для Windows версии 2308 (сборка 16724.10000) или более поздней версии, Outlook для Mac, Outlook в Интернете или новый Outlook для Windows (предварительная версия), необходимо использовать moveItemTo свойство в event.completed вызове, чтобы указать папку, в которую сообщение перемещается после обработки надстройкой. В более ранних версиях Outlook на платформе Windows, поддерживающей встроенную функцию создания отчетов о спаме postProcessingAction , необходимо использовать свойство .

  2. Сохраните изменения.

Ниже приведен пример диалогового окна постобработки, показанного пользователю после завершения обработки сообщаемого сообщения в Outlook в Windows. Обратите внимание, что внешний вид диалогового окна может отличаться в зависимости от платформы, на которую работает клиент Outlook пользователя.

Пример диалогового окна постобработки, показанного после обработки сообщаемого сообщения о нежелательной почте надстройкой.

Совет

При разработке надстройки со сведениями о спаме, которая будет выполняться в Outlook в Windows, помните следующее.

  • Импорт в настоящее время не поддерживается в файле JavaScript, который содержит код для обработки события со спамом.
  • Код, включенный Office.onReady() в функции и Office.initialize , не будет выполняться. Вместо этого в обработчики событий необходимо добавить любую логику запуска надстроек, например проверку версии Outlook пользователя.

Обновление HTML-файла команд

  1. В папке ./src/commands откройте commands.html.

  2. Непосредственно перед закрывающим тегом заголовка (</head>) добавьте следующую запись скрипта .

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

    Примечание.

    Встроенная функция создания отчетов о спаме в настоящее время доступна в предварительной версии в Outlook на Mac. При тестировании функции в этом клиенте необходимо включить ссылку на предварительную версию API JavaScript для Office в файлcommands.html .

    <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 отключена. Однако это не поддерживается в Outlook на Mac. В Outlook для Mac необходимо включить область чтения, чтобы использовать надстройку отчетов о нежелательной почте.

  • В классической версии Outlook в Windows одновременно можно сообщать только одно сообщение. Если пользователь пытается сообщить о другом сообщении во время обработки предыдущего сообщения, ему будет показано диалоговое окно с уведомлением об этом.

    Диалоговое окно, отображаемое, когда пользователь пытается сообщить о другом сообщении, пока предыдущее сообщение еще обрабатывается.

    Это не относится к Outlook на Mac или в Интернете, а также к новым Outlook в Windows (предварительная версия). В этих клиентах Outlook пользователь может сообщить о сообщении из области чтения и одновременно сообщать о каждом сообщении, открытом в отдельном окне.

  • Надстройка по-прежнему может обработать сообщение, даже если пользователь переходит от выбранного сообщения. В Outlook для Mac это поддерживается только в том случае, если пользователь сообщает сообщение, когда оно открыто в отдельном окне. Если пользователь сообщает о сообщении при просмотре его из области чтения, а затем удаляется от него, процесс создания отчетов завершается.

  • Кнопки, отображаемые в диалоговых окнах предварительной и последующей обработки, не настраивается. Кроме того, невозможно изменить текст и кнопки в диалоговых окнах времени ожидания и текущих отчетов.

  • Интегрированные функции создания отчетов о нежелательной почте и активации на основе событий должны использовать одну и ту же среду выполнения. Несколько сред выполнения в настоящее время не поддерживаются в Outlook. Дополнительные сведения о средах выполнения см. в статье Среды выполнения в надстройках Office.

  • Не удается назначить команду области задач кнопке сообщения о нежелательной почте на ленте. Если вы хотите реализовать область задач в надстройке, необходимо включить элемент Action в манифест и задать для его xsi:type атрибута значение ShowTaskpane. Обратите внимание, что на ленту будет добавлена отдельная кнопка для активации области задач, но она не будет отображаться в выделенной области отчетов о спаме на ленте.

Устранение неполадок с надстройкой

При разработке надстройки, сообщающей о спаме, может потребоваться устранить неполадки, например, если надстройка не загружается. Инструкции по устранению неполадок надстройки со сведениями о спаме см. в статье Устранение неполадок надстроек на основе событий и отчетов о нежелательной почте.

См. также