統合されたスパム報告アドインを実装する

迷惑メールの数が増加する中、セキュリティはアドインの使用の最前線にあります。 現在、パートナースパムレポートアドインは Outlook リボンに追加されますが、通常はリボンの末尾またはオーバーフロー メニューに表示されます。 これにより、ユーザーがアドインを見つけて迷惑メールを報告することが困難になります。 メッセージが報告されたときにメッセージを処理する方法を構成するだけでなく、開発者は、処理ダイアログや補足情報をユーザーに表示するために、追加のタスクを完了する必要もあります。

統合されたスパムレポート機能により、個々のアドイン コンポーネントをゼロから開発する作業が容易になります。 さらに重要なのは、Outlook リボンの目立つ場所にアドインが表示されるため、ユーザーが見つけやすく、スパム メッセージを報告しやすくなります。 アドインで次の機能を実装します。

• 一方的なメッセージの追跡方法を改善します。
• 疑わしいメッセージを報告する方法に関するユーザーに対して、より優れたガイダンスを提供します。
• organizationのセキュリティ オペレーション センター (SOC) または IT 管理者が、教育目的でスパムとフィッシングのシミュレーションを簡単に実行できるようにします。

サポートされるクライアント

次の表は、統合されたスパムレポート機能をサポートする Outlook クライアントを示しています。

Outlook on Mac で統合されたスパムレポート機能をプレビューする

Outlook on Mac で統合スパムレポート機能をプレビューするには、バージョン 16.81.1217.0 以降をインストールする必要があります。 次に、 Microsoft 365 Insider プログラム に参加し、[ ベータ チャネル ] オプションを選択して Office ベータ ビルドにアクセスします。

環境を設定する

Office アドイン用 Yeoman ジェネレーターを使用してアドイン プロジェクトを作成する Outlook クイック スタートを完了します。

マニフェストを構成する

アドインに統合スパムレポート機能を実装するには、マニフェストで次の機能を構成する必要があります。

• アドインによって使用されるランタイム。 従来の Outlook on Windows では、スパムレポート アドインは JavaScript 専用ランタイムで実行されます。 Outlook on the webと Mac および新しい Outlook on Windows では、ブラウザー ランタイムでスパムレポート アドインが実行されます。 詳細については、「 Office アドインのランタイム」を参照してください。

• Outlook リボンの目立つ場所に常に表示されるスパムレポート アドインのボタン。 Windows 上の従来の Outlook クライアントのリボンにスパムレポート アドインのボタンが表示される例を次に示します。 リボン UI は、ユーザーの Outlook クライアントが実行されているプラットフォームによって異なる場合があります。

  

• 前処理ダイアログ。 ユーザーがアドイン ボタンを選択すると、[レポート] オプションと [レポートしない] オプションが表示されたダイアログが表示されます。 このダイアログでは、レポート プロセスに関する情報を共有したり、入力オプションを実装して、報告されたメッセージに関する情報を取得したりできます。 入力オプションには、チェック ボックス、ラジオ ボタン、テキスト ボックスが含まれます。 ユーザーがダイアログから [レポート ] を選択すると、 SpamReporting イベントがアクティブになり、JavaScript イベント ハンドラーによって処理されます。 Outlook on 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 メソッドを呼び出します。 これにより、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. 変更内容を保存します。

イベントが処理されたことを通知する

イベント ハンドラーは、メッセージの処理を完了したら、 event.completed メソッドを呼び出す必要があります。 スパム報告イベントが処理されたことをアドインに通知するだけでなく、 event.completed を使用して次の操作を行うこともできます。

• ユーザーに表示する後処理ダイアログをカスタマイズします。
• 受信トレイからメッセージを削除するなど、メッセージに対して追加の操作を実行します。
• 作業ウィンドウを開き、情報を渡します。

event.completed メソッドにパラメーターとして渡す JSON オブジェクトに含めることができるプロパティの一覧については、「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 on Windows バージョン 2308 (ビルド 16724.10000) 以降、Outlook on Mac、Outlook on the web、または新しい Outlook on Windows の場合は、event.completed呼び出しで moveItemTo プロパティを使用して、報告されたメッセージがアドインによって処理された後に移動されるフォルダーを指定する必要があります。 統合されたスパムレポート機能をサポートする Windows 上の以前の Outlook ビルドでは、 postProcessingAction プロパティを使用する必要があります。

2. 変更内容を保存します。

次に示すのは、アドインが Outlook on Windows で報告されたメッセージの処理を完了すると、ユーザーに表示される処理後のサンプル ダイアログです。 ダイアログの外観は、ユーザーの 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. config オブジェクト内のplugins配列を見つけて、この新しいオブジェクトを配列の先頭に追加します。

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

3. 変更内容を保存します。

アドインをテストして検証する

1. サポートされている Outlook クライアントでアドインをサイドロードします。
2. 受信トレイからメッセージを選択し、リボンからアドインのボタンを選択します。
3. 前処理ダイアログで、メッセージを報告する理由を選択し、構成されている場合はメッセージに関する情報を追加します。 次に、[ レポート] を選択します。
4. (省略可能)後処理ダイアログで、[ OK] を選択します。

前処理ダイアログを抑制する

シナリオによっては、ユーザーが報告しているメッセージに関する追加情報を提供する必要がない場合があります。 スパム レポート アドインの前処理ダイアログがユーザーにのみ情報を提供する場合は、ダイアログに [このメッセージを再度表示しない] オプションを含めることができます。

アドインでこれを実装するには、マニフェストで 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 on Windows で前処理ダイアログを再度有効にするには、次の手順を実行します。

1. レジストリ エディターを管理者として開きます。
2. [HKEY_CURRENT_USER\Software\Microsoft\Office\16.0\Outlook\Options\WebExt\SpamDialog] に移動します。
3. マニフェストで指定された ID を使用して、スパム報告アドインを見つけます。
4. レジストリからアドインのエントリを削除します。

次にメッセージが報告されると、前処理ダイアログが表示されます。

メッセージを報告した後で作業ウィンドウを開く

後処理ダイアログの代わりに、ユーザーがメッセージを報告した後に開く作業ウィンドウを実装できます。 たとえば、作業ウィンドウを使用して、前処理ダイアログでのユーザーの入力に基づいて追加情報を表示できます。 後処理ダイアログと同様に、作業ウィンドウはアドインの event.completed 呼び出しによって実装されます。

メッセージが報告された後に開く作業ウィンドウを構成するには、event.completed呼び出しの commandId オプションで作業ウィンドウの ID を指定する必要があります。 ID は、マニフェストの作業ウィンドウを表す Control 要素のid属性で指定された値と一致する必要があります。

作業ウィンドウに情報を渡す必要がある場合は、event.completed呼び出しの contextData オプションで任意の JSON データを指定します。 contextData オプションの値を取得するには、作業ウィンドウの JavaScript 実装で Office.context.mailbox.item.getInitializationContextAsync を呼び出す必要があります。

以下にコードの例を示します。

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

メッセージが報告された時点で別の作業ウィンドウが開いているかピン留めされている場合は、開いている作業ウィンドウが閉じられ、スパムレポート アドインの作業ウィンドウが表示されます。

機能の動作と制限事項を確認する

アドインで統合されたスパムレポート機能を開発してテストするときは、その特性と制限事項に留意してください。

• Outlook on the webと Windows (新規およびクラシック) では、統合されたスパムレポート アドインが Outlook リボンのネイティブレポートボタンに置き換えられます。 複数のスパム レポート アドインがインストールされている場合、それらはすべてリボンの [ レポート ] セクションに表示されます。

  

• スパムレポート アドインは、アクティブ化されると最大 5 分間実行できます。 5 分を超える処理が発生すると、アドインはタイムアウトになります。アドインがタイムアウトすると、ユーザーにこの旨を通知するダイアログが表示されます。

  

• 従来の Outlook on Windows では、Outlook クライアントの閲覧ウィンドウがオフになっている場合でも、スパムレポート アドインを使用してメッセージを報告できます。 Outlook on the web、Mac の場合、および新しい Outlook on Windows では、閲覧ウィンドウがオンになっているか、報告するメッセージが別のウィンドウで開いている場合に、スパム報告アドインを使用できます。

• 一度に報告できるメッセージは 1 つだけです。 レポートする複数のメッセージを選択すると、スパムレポート アドインのボタンが使用できなくなります。

• クラシック Outlook on Windows では、報告されたメッセージを一度に 1 つだけ処理できます。 前のメッセージがまだ処理中にユーザーが別のメッセージを報告しようとすると、そのメッセージを通知するダイアログが表示されます。

  

  これは、Outlook on the webまたは Mac、または新しい Outlook on Windows には適用されません。 これらの Outlook クライアントでは、ユーザーは閲覧ウィンドウからメッセージを報告し、別のウィンドウで開いている各メッセージを同時に報告できます。

• ユーザーが選択したメッセージから離れた場合でも、アドインは報告されたメッセージを処理できます。 Outlook on Mac では、これは、別のウィンドウで開いている間にユーザーがメッセージを報告する場合にのみサポートされます。 閲覧ウィンドウから閲覧中にユーザーがメッセージを報告し、そのメッセージから離れた場合、レポート プロセスは終了します。

• Outlook on the webと新しい Outlook on 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