Поделиться через

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

  • Статья

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

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

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

Примечание.

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

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

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

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

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

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

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

Совет

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

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

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

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

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

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

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

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

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

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

Примечание.

Реализация интегрированных отчетов о спаме с унифицированным манифестом для Microsoft 365 доступна в общедоступной предварительной версии для разработчиков. В настоящее время его можно использовать только в классической версии Outlook в Windows. Его не следует использовать в рабочих надстройках. Мы приглашаем вас опробовать его в средах тестирования или разработки. Дополнительные сведения см. в статье Схема манифеста общедоступной предварительной версии приложения для разработчиков.

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

  2. Откройте файл manifest.json .

  3. Добавьте следующий объект в массив extensions.runtimes. Обратите внимание на следующие особенности этой разметки.

    • Для параметра minVersion набора обязательных для почтового ящика настроено значение "1.14". Это самая низкая версия набора требований, которая поддерживает встроенную функцию создания отчетов о нежелательной почте.
    • Для идентификатора среды выполнения задается уникальное описательное имя "spam_reporting_runtime".
    • Свойство code имеет дочернее свойство page, для которого задано значение HTML-файла, и дочернее свойство script, задается в файл JavaScript. Вы создадите или измените эти файлы на последующих шагах.
    • Свойство "время существования" имеет значение "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, должно соответствовать значению, используемому в свойстве id объекта в массиве actions. Хотя свойство "enabled" должно быть указано в массиве, его значение не влияет на функциональность надстройки, сообщающей о спаме.
    • Объект spamPreProcessingDialog указывает сведения и параметры, отображаемые в диалоговом окне предварительной обработки. Хотя для диалогового окна необходимо указать "заголовок" и "описание", при необходимости можно настроить следующие свойства.
      • Объект 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 в обработчике событий. При этом будет получено сообщение в формате 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. Сохраните изменения.

Примечание.

Чтобы настроить единый вход (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 для 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 в Интернете и в Windows (новая и классическая) встроенная надстройка со сведениями о спаме заменяет встроенную кнопку "Отчет" на ленте Outlook. Если установлено несколько надстроек со сведениями о нежелательной почте, все они будут отображаться в разделе Отчет на ленте.

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

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

    Диалоговое окно, отображаемое при истекшем времени ожидания надстройки, сообщающей о спаме.

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

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

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

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

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

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

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

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

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

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

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

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

См. также