統合スパムレポートアドインを実装する (プレビュー)

[アーティクル]
05/03/2024

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

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

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

重要

統合されたスパムレポート機能は、現在、従来の Outlook on Windows と Outlook on Mac でプレビュー段階にあります。 Outlook on the webおよび新しい Outlook on Windows (プレビュー) の機能のプレビューサポートが現在ロールアウトされています。

プレビューの機能は、運用環境のアドインでは使用しないでください。テスト環境または開発環境でこの機能を試し、GitHub を通じたエクスペリエンスに関するフィードバックを歓迎することをお勧めします (このページの最後にある 「フィードバック 」セクションを参照してください)。

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

統合されたスパムレポート機能をプレビューするには、次のいずれかのサポートされているクライアントが必要です。

Windows バージョン 2307 (ビルド 16626.10000) 以降のクラシック Outlook。 Microsoft 365 Insider プログラムに参加し、[ベータチャネル] オプションを選択して Office ベータビルドにアクセスする必要があります。
Outlook on Mac バージョン 16.81.1217.0 以降。 Microsoft 365 Insider プログラムに参加し、[ベータチャネル] オプションを選択して Office ベータビルドにアクセスする必要があります。

注:

Outlook on the webおよび新しい Outlook on Windows (プレビュー) の統合スパムレポート機能のプレビューサポートが現在ロールアウトされています。プレビューが可能になったら、Office ベータ版ビルドにアクセスするには、Microsoft 365 テナントでターゲットリリースを構成する必要があります。

ヒント

Windows 上の Outlook クライアントでチャネルを選択できない場合は、「Windows デバイスにインストールする Microsoft 365 Insider チャネルをユーザーが選択できるようにする」を参照してください。

環境を設定する

ヒント

完了したスパムレポートアドインソリューションをすぐに試すには、 Outlook (プレビュー) でスパムまたはフィッシングメールを報告するサンプルを参照してください。

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

マニフェストを構成する

注:

統合スパムレポートは、 Microsoft 365 の統合マニフェストではまだサポートされていません。

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

Outlook on the webと Mac および新しい Outlook on Windows では、統合されたスパムレポート機能を実装するアドインがブラウザーランタイムで実行されます。 Runtime 要素の属性でresidスパム報告イベントを処理するには、コードを参照または含む HTML ファイルを指定する必要があります。
従来の Outlook on Windows では、統合されたスパムレポート機能を実装するアドインが JavaScript 専用ランタイムで実行されます。そのため、Runtime> 要素の Override 子要素でスパム報告イベントを処理するコードを含む JavaScript ファイルを指定する<必要があります。
Outlook リボンでアドインをアクティブ化し、リボンの末尾またはオーバーフローセクションに表示されないようにするには、ExtensionPoint> 要素の<属性を ReportPhishingCommandSurface に設定xsi:typeします。
リボンボタンと前処理ダイアログをカスタマイズするには、 ReportPhishingCustomization ノードを定義する必要があります。
- ユーザーは、リボンのアドインのボタンを使用して、未承諾のメッセージを報告します。リボンボタンを構成するには、Control 要素の属性を xsi:type にButton設定します。次にxsi:type、Action 子要素の属性をにExecuteFunction設定し、その FunctionName> 子要素でスパム報告イベントハンドラーの名前を<指定します。スパム報告アドインは、関数コマンドのみを実装できます。
  
  Windows 上の Outlook クライアントのリボンにスパムレポートアドインのボタンが表示される例を次に示します。リボン UI は、ユーザーの Outlook クライアントが実行されているプラットフォームによって異なる場合があります。
- 前処理ダイアログは、アドインボタンを選択するとユーザーに表示されます。マニフェストの PreProcessingDialog 要素を使用して構成されます。ダイアログにはタイトルと説明が必要ですが、必要に応じて次の要素を含めることができます。
  - ユーザーがレポートしているメッセージの種類を識別するのに役立つ選択肢の複数選択リスト。これらのレポートオプションを構成する方法については、「 ReportingOptions 要素」を参照してください。
  - ユーザーが報告しているメッセージに関する追加情報を提供するためのテキストボックス。テキストボックスを実装する方法については、「 FreeTextLabel 要素」を参照してください。
  - ユーザーに情報リソースを提供するためのカスタムテキストと URL。これらの要素をカスタマイズする方法については、「 MoreInfo 要素」を参照してください。
  ユーザーがダイアログから [レポート ] を選択すると、 SpamReporting イベントがアクティブになり、JavaScript イベントハンドラーによって処理されます。
  
  Outlook on Windows の前処理ダイアログの例を次に示します。ダイアログの外観は、ユーザーの Outlook クライアントが実行されているプラットフォームによって異なる場合があることに注意してください。

スパムレポート用に構成された VersionOverrides> ノードの<例を次に示します。

任意のコードエディターで、作成したアドインプロジェクトを開きます。
プロジェクトのルートにある manifest.xml ファイルを開きます。

VersionOverrides> ノード全体< (開いているタグと閉じるタグを含む) を選択し、次のコードに置き換えます。

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

変更内容を保存します。

イベントハンドラを実装する

アドインを使用してメッセージを報告すると、 SpamReporting イベントが生成されます。このイベントは、アドインの JavaScript ファイル内のイベントハンドラーによって処理されます。マニフェストの FunctionName> 要素で<指定したイベントハンドラーの名前を、対応する JavaScript にマップするには、コードで Office.actions.associate を呼び出す必要があります。

アドインプロジェクトで、 ./src ディレクトリに移動します。次に、 spamreporting という名前の新しいフォルダーを作成します。
./src/spamreporting フォルダーで、という名前の新しいファイル spamreporting.js作成します。

新しく作成した 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);
}

変更内容を保存します。

メッセージのコピーを転送し、前処理ダイアログ応答を取得する

イベントハンドラーは、報告されたメッセージの処理を担当します。メッセージのコピーや前処理ダイアログでユーザーが選択したオプションなどの情報を内部システムに転送するように構成して、詳細な調査を行うことができます。

報告されたメッセージのコピーを効率的に送信するには、イベントハンドラーで getAsFileAsync メソッドを呼び出します。これにより、Base64 でエンコードされたメッセージの EML 形式が取得されます。これにより、内部システムに転送できます。

重要

Outlook on Windows のプレビュー段階でメソッドをテスト getAsFileAsync するには、コンピューターのレジストリを構成する必要があります。

Outlook on Windows には、コンテンツ配信ネットワーク (CDN) から読み込む代わりに、運用環境とベータ版の Office.js のローカルコピーが含まれています。既定では、API のローカル運用コピーが参照されます。 API のローカルベータコピーを参照するには、次のようにコンピューターのレジストリを構成する必要があります。

レジストリで、に移動します HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Outlook\Options\WebExt\Developer。キーが存在しない場合は、作成します。
という名前EnableBetaAPIsInJavaScriptのエントリをCreateし、その値をに1設定します。

前処理ダイアログのオプションとテキストボックスに対するユーザーの応答を追跡する必要がある場合は、イベントオブジェクトからと freeText の値をSpamReporting抽出optionsします。これらのプロパティの詳細については、「 Office.SpamReportingEventArgs」を参照してください。

メソッドを呼び出し getAsFileAsync 、イベントオブジェクトからユーザーの応答を取得するスパム報告イベントハンドラーの例を次に SpamReporting 示します。

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);
}

変更内容を保存します。

注:

スパムレポートアドインでシングルサインオン (SSO) またはクロスオリジンリソース共有 (CORS) を構成するには、アドインとその JavaScript ファイルを既知の URI に追加する必要があります。このリソースを構成する方法のガイダンスについては、「イベントベースまたはスパムレポートの Outlook アドインでシングルサインオン (SSO) またはクロスオリジンリソース共有 (CORS) を使用する」を参照してください。

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

イベントハンドラーは、メッセージの処理を完了したら、 event.completed メソッドを呼び出す必要があります。スパム報告イベントが処理されたことをアドインに通知するだけでなく、後処理ダイアログをカスタマイズしてユーザーに表示したり、 event.completed 受信トレイからメッセージを削除するなど、メッセージに対して追加の操作を実行したりすることもできます。メソッドにパラメーター event.completed として渡す JSON オブジェクトに含めることができるプロパティの一覧については、「 Office.SpamReportingEventCompletedOptions」を参照してください。

注:

呼び出し後に追加された event.completed コードは、実行が保証されません。

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

変更内容を保存します。

次に示すのは、アドインが Outlook on Windows で報告されたメッセージの処理を完了すると、ユーザーに表示される処理後のサンプルダイアログです。ダイアログの外観は、ユーザーの Outlook クライアントが実行されているプラットフォームによって異なる場合があることに注意してください。

報告されたスパムメッセージがアドインによって処理された後処理ダイアログのサンプル。

ヒント

Outlook on Windows で実行されるスパムレポートアドインを開発するときは、次の点に注意してください。

インポートは、スパムレポートイベントを処理するコードを含む JavaScript ファイルでは現在サポートされていません。
関数と Office.initialize 関数にOffice.onReady()含まれるコードは実行されません。代わりに、ユーザーの Outlook バージョンの確認など、アドインのスタートアップロジックをイベントハンドラーに追加する必要があります。

コマンド HTML ファイルを更新する

./src/commands フォルダーで、 commands.htmlを開きます。

終了 ヘッド タグ (</head>) の直前に、既存のスクリプトエントリを次のコードに置き換えます。

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

変更内容を保存します。

webpack 構成設定を更新する

アドインプロジェクトのルートディレクトリから、 webpack.config.js ファイルを開きます。

オブジェクト内の plugins 配列を config 見つけて、この新しいオブジェクトを配列の先頭に追加します。

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

変更内容を保存します。

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

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

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

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

スパムレポートアドインは、アクティブ化されると最大 5 分間実行できます。 5 分を超える処理が発生すると、アドインはタイムアウトになります。アドインがタイムアウトすると、ユーザーにこの旨を通知するダイアログが表示されます。
Outlook クライアントの閲覧ウィンドウがオフになっている場合でも、スパム報告アドインを使用してメッセージを報告できます。ただし、これは Outlook on Mac ではサポートされていません。 Outlook on Mac では、スパムレポートアドインを使用するには閲覧ウィンドウを有効にする必要があります。
クラシック Outlook on Windows では、一度に報告できるメッセージは 1 つだけです。前のメッセージがまだ処理中にユーザーが別のメッセージを報告しようとすると、そのメッセージを通知するダイアログが表示されます。

これは、Outlook on Mac または Web、または新しい Outlook on Windows (プレビュー) には適用されません。これらの Outlook クライアントでは、ユーザーは閲覧ウィンドウからメッセージを報告し、別のウィンドウで開いている各メッセージを同時に報告できます。
ユーザーが選択したメッセージから離れた場合でも、アドインは報告されたメッセージを処理できます。 Outlook on Mac では、これは、別のウィンドウで開いている間にユーザーがメッセージを報告する場合にのみサポートされます。閲覧ウィンドウから閲覧中にユーザーがメッセージを報告し、そのメッセージから離れた場合、レポートプロセスは終了します。
前処理ダイアログと後処理ダイアログに表示されるボタンはカスタマイズできません。さらに、タイムアウトおよび進行中のレポートダイアログのテキストとボタンは変更できません。
統合されたスパムレポート機能とイベントベースのアクティブ化機能では、同じランタイムを使用する必要があります。現在、Outlook では複数のランタイムはサポートされていません。ランタイムの詳細については、「 Office アドインのランタイム」を参照してください。
作業ウィンドウコマンドをリボンの [スパムレポート] ボタンに割り当てることはできません。アドインに作業ウィンドウを実装する場合は、マニフェストに Action 要素を含め、その xsi:type 属性をに設定する ShowTaskpane必要があります。作業ウィンドウをアクティブにする別のボタンはリボンに追加されますが、リボンの専用スパム報告領域には表示されません。

アドインのトラブルシューティング

スパムレポートアドインを開発するときに、アドインが読み込まれていないなどの問題のトラブルシューティングが必要になる場合があります。スパムレポートアドインのトラブルシューティング方法のガイダンスについては、「イベントベースおよびスパムレポートアドインのトラブルシューティング」を参照してください。

統合スパムレポートアドインを実装する (プレビュー)

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

環境を設定する

マニフェストを構成する

イベントハンドラを実装する

メッセージのコピーを転送し、前処理ダイアログ応答を取得する

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

コマンド HTML ファイルを更新する

webpack 構成設定を更新する

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

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

アドインのトラブルシューティング

関連項目

フィードバック

その他のリソース

統合スパムレポート アドインを実装する (プレビュー)

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

環境を設定する

マニフェストを構成する

イベント ハンドラを実装する

メッセージのコピーを転送し、前処理ダイアログ応答を取得する

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

コマンド HTML ファイルを更新する

webpack 構成設定を更新する

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

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

アドインのトラブルシューティング

関連項目

フィードバック

その他のリソース

統合スパムレポートアドインを実装する (プレビュー)

イベントハンドラを実装する