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

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

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

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

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

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

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

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

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

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

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

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

• Среда выполнения, используемая надстройкой. В классической версии Outlook в Windows надстройка, сообщающая о спаме, выполняется в среде выполнения, доступной только для JavaScript. В Outlook в Интернете и на Mac, а также в новом Outlook для Windows надстройка со сведениями о спаме запускается в среде выполнения браузера. Дополнительные сведения см. в разделе Среды выполнения в надстройках Office.

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

  

• Диалоговое окно предварительной обработки. Когда пользователь нажимает кнопку надстройки, появляется диалоговое окно с параметрами Отчет и Не отчеты . В этом диалоговом окне можно поделиться информацией о процессе создания отчетов или реализовать входные параметры для получения сведений о сообщении. Параметры ввода включают флажки, переключатели и текстовое поле. Когда пользователь выбирает отчет в диалоговом окне, событие SpamReporting активируется, а затем обрабатывается обработчиком событий JavaScript. Ниже приведен пример диалогового окна предварительной обработки в Outlook в Windows. Обратите внимание, что внешний вид диалогового окна может отличаться в зависимости от платформы, на которую работает клиент Outlook пользователя.

  

Выберите вкладку для типа манифеста, который вы используете.

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

Когда надстройка используется для отправки сообщения, она создает 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 в обработчике событий. При этом будет получено сообщение в формате 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 Outlook, remember to map the event handler name specified in the manifest to its JavaScript counterpart.
   Office.actions.associate("onSpamReport", onSpamReport);
   

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

Сигнал, когда событие было обработано

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

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

Список свойств, которые можно включить в объект JSON для передачи в качестве параметра методу, см. в event.completed разделе Office.SpamReportingEventCompletedOptions.

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

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

Ниже приведен пример диалогового окна постобработки, показанного пользователю после завершения обработки сообщаемого сообщения в Outlook в Windows. Обратите внимание, что внешний вид диалогового окна может отличаться в зависимости от платформы, на которую работает клиент 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. (Необязательно) В диалоговом окне постобработки нажмите кнопку ОК.

Подавление диалогового окна предварительной обработки

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

Чтобы реализовать это в надстройке, необходимо указать элемент NeverShowAgainOption в манифесте и задать для него значение true. Ниже приведен код в качестве примера.

...
    <PreProcessingDialog>
      <Title resid="PreProcessingDialog.Label"/>
      <Description resid="PreProcessingDialog.Text"/>
      <NeverShowAgainOption>true</NeverShowAgainOption>
      <MoreInfo>
        <MoreInfoText resid="MoreInfo.Label"/>
        <MoreInfoUrl resid="MoreInfo.Url"/>
      </MoreInfo>
    </PreProcessingDialog>
...

Обратите внимание на следующее поведение при реализации этого параметра в надстройке.

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

• Параметр для подавления диалогового окна предварительной обработки применяется для каждого компьютера и для каждой платформы.

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

  

  Примечание.

  Если вы реализуете параметр "Не показывать мне это сообщение снова" без настройки диалогового окна постобработки, после обработки пользователю будет показано диалоговое окно со следующим универсальным сообщением: "Спасибо, что сообщили об этом сообщении". Рекомендуется настроить после обработки сообщения после обработки диалоговое окно постобработки.

Повторное добавление диалогового окна предварительной обработки

Чтобы повторно включить диалоговое окно предварительной обработки в классическом Outlook в Windows после выбора параметра "Больше не показывать мне это сообщение", выполните следующие действия.

1. Откройте Редактор реестра с правами администратора.
2. Перейдите к HKEY_CURRENT_USER\Software\Microsoft\Office\16.0\Outlook\Options\WebExt\SpamDialog.
3. Найдите надстройку со сведениями о нежелательной почте, используя ее идентификатор, указанный в манифесте.
4. Удалите запись надстройки из реестра.

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

Открытие области задач после сообщения

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

Чтобы настроить открытие области задач после сообщения, необходимо указать идентификатор области задач в параметре event.completedcommandId вызова. Идентификатор должен соответствовать значению, указанному в атрибуте id элемента Control , представляющего область задач в манифесте.

Если необходимо передать сведения в область задач, укажите любые данные JSON в параметреevent.completed contextData вызова. Чтобы получить значение contextData параметра, необходимо вызвать Office.context.mailbox.item.getInitializationContextAsync в реализации JavaScript области задач.

Ниже приведен код в качестве примера.

...
    event.completed({
      commandId: "msgReadOpenPaneButton",
      contextData: JSON.stringify({ a: "aValue", b: "bValue" }),
      moveItemTo: Office.MailboxEnums.MoveSpamItemTo.NoMove
    });

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

Обзор поведения и ограничений функций

При разработке и тестировании встроенной функции создания отчетов о спаме в надстройке учитывайте ее характеристики и ограничения.

• В Outlook в Интернете и в Windows (новая и классическая) встроенная надстройка со сведениями о спаме заменяет встроенную кнопку "Отчет" на ленте Outlook. Если установлено несколько надстроек со сведениями о нежелательной почте, все они будут отображаться в разделе Отчет на ленте.

  

• Надстройка со сведениями о спаме может работать не более пяти минут после активации. Любая обработка, которая выполняется за пять минут, приведет к истечении времени ожидания надстройки. Если время ожидания надстройки истекает, пользователю будет показано диалоговое окно с уведомлением об этом.

  

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

• Одновременно можно сообщить только одно сообщение. Если выбрать несколько сообщений для отчета, кнопка надстройки со сведениями о нежелательной почте станет недоступной.

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

  

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

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

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

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

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

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

  • Манифест только надстройки: включите элемент Action в манифест и задайте для его xsi:type атрибута значение ShowTaskpane.
  • Унифицированный манифест для Microsoft 365: настройка объекта области задач в массивах extensions.runtimes и extensions.ribbons. Инструкции см. в разделе "Добавление команды области задач" статьи Создание команд надстроек с помощью унифицированного манифеста для Microsoft 365.

  Обратите внимание, что на ленту будет добавлена отдельная кнопка для активации области задач, но она не будет отображаться в выделенной области отчетов о спаме на ленте.

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

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

См. также

• Манифест надстроек Office
• Среды выполнения в надстройках Office
• Устранение неполадок надстроек на основе событий и отчетов о спаме
• Точка расширения ReportPhishingCommandSurface
• Office.MessageRead.getAsFileAsync
• Office.MailboxEnums.MoveSpamItemTo
• Office.SpamReportingEventArgs
• Office.SpamReportingEventCompletedOptions