イベントを使用してアドインをアクティブ化する

イベント ベースのアクティブ化では、アドインを明示的に起動せずにタスクを完了するために、アドインが自動的にトリガーされます。 これにより、アドインは手動操作なしで重要なコンテンツを検証、挿入、または更新できます。 ユーザーが中断されないように、アドインがバックグラウンドで開かれます。 イベント ベースのアクティブ化を作業ウィンドウと関数コマンドと統合することもできます。

概要

アドインにイベント ベースの機能を追加する特定の手順はプラットフォームとマニフェストの種類によって異なりますが、一般的なフローは次のとおりです。

1. イベントの拡張機能を使用してマニフェストを更新します。
2. マニフェスト内のイベントを JavaScript 関数に接続して、イベントを処理します。
3. イベント ハンドラー関数にアクションを実行し、完了したら event.completed を呼び出します。
4. Office.actions.associate を呼び出して、マニフェストで指定された ID にイベント ハンドラー関数を接続します。

イベント ベースのアクティブ化を試す

イベント ベースのアクティブ化を使用してワークフローを合理化し、ユーザー エクスペリエンスを向上させる方法について説明します。 サンプルを試して、動作している機能を確認してください。

Outlook のサンプル

• 新しいメッセージまたは予定の件名を自動的に設定する
• メッセージが送信される前に添付ファイルを自動的にチェックする
• メール アカウントを切り替えるときに署名を自動的に更新する
• Outlook イベント ベースのアクティブ化を使用して、添付ファイルを暗号化し、会議出席依頼の出席者を処理し、予定の日付/時刻の変更に対応する
• Outlook イベント ベースのアクティブ化を使用して署名を設定する
• Outlook イベント ベースのアクティブ化を使用して外部受信者を識別してタグ付けする
• スマート アラートを使用して送信される前に、メッセージまたは予定の色のカテゴリを確認する
• メッセージの秘密度ラベルを確認する

Wordサンプル

• ドキュメントが開いたときにヘッダーを追加する

サポートされるイベント

次の表に、現在使用可能なイベントと、各イベントでサポートされているクライアントを示します。 イベントが発生すると、ハンドラーはイベントの種類に固有の詳細を含む event オブジェクトを受け取ります。 [説明] 列には、該当する場合は関連オブジェクトへのリンクが含まれます。

Excel、PowerPoint、Word イベント

Outlook イベント

Outlook のこの機能のサポートは 要件セット 1.10 で導入され、後続の要件セットで追加のイベントを使用できるようになりました。 次の表に、各イベントの最小要件セットと、それをサポートするクライアントとプラットフォームを示します。 Outlook クライアントとそれらがサポートする要件セットの詳細については、「 Exchange サーバーと Outlook クライアントでサポートされる要件セット」を参照してください。

モバイル デバイスでの Outlook でのイベント ベースのアクティブ化

Outlook on mobile では、メールボックス要件セット 1.5 までの API がサポートされています。 ただし、 OnNewMessageCompose イベントなど、後の要件セットで導入された追加の API と機能のサポートが有効になりました。 詳細については、「 Outlook モバイル アドインでイベント ベースのアクティブ化を実装する」を参照してください。

動作と制限事項

イベント ベースのアドインを開発するときは、次の機能の動作と制限事項に注意してください。

• イベント ベースのアドインは、管理者によってデプロイされた場合にのみ機能します。 ユーザーが AppSource または Office ストアから直接インストールした場合、自動的には起動されません (AppSource の制限事項の回避策については、「 イベント ベースのアドインの AppSource 登録情報オプション」を参照してください)。 管理デプロイは、マニフェストをMicrosoft 365 管理センターにアップロードすることによって行われます。

• UI 要素または表示 UI 要素と対話する API は、Windows 上のWord、PowerPoint、Excel ではサポートされていません。 これは、イベント ハンドラーが JavaScript 専用ランタイムで実行されるためです。 詳細については、「 Office アドインのランタイム」を参照してください。

• イベント ベースのアドインでは、特定のイベントが発生したときにインターネット接続を起動できる必要があります。 アドイン イベント ハンドラーは、実行時間が短く、軽量で、可能な限り非侵襲的である必要があります。 アクティブ化後、アドインは約 300 秒以内にタイムアウトします。これは、イベント ベースのアドインの実行に許可される最大時間です。アドインが起動イベントの処理を完了したことを通知するには、関連付けられているイベント ハンドラーが event.completed メソッドを呼び出す必要があります。 ( event.completed ステートメントの後に含まれるコードは、実行が保証されていないことに注意してください)。アドインが処理するイベントがトリガーされるたびに、アドインが再アクティブ化され、関連するイベント ハンドラーが実行され、タイムアウト ウィンドウがリセットされます。 アドインは、タイムアウト後に終了するか、ユーザーが作成ウィンドウを閉じるか、アイテムを送信します。

• 同じイベントをサブスクライブする複数のアドインの動作は決定的ではありません。 Outlook は、特定の順序でアドインを起動します。 Excel、PowerPoint、およびWordの場合、1 つのランダム アドインのみがアクティブになります。 たとえば、OnDocumentOpenedを処理する複数のWord アドインの場合、それらのハンドラーの 1 つだけが実行されます。

• 現時点では、アクティブに実行できるイベント ベースのアドインは 5 つだけです。

• サポートされているすべての Outlook クライアントで、アドインの実行を完了するには、アドインがアクティブ化された現在のメール アイテムにユーザーを残す必要があります。 現在の項目から移動すると (たとえば、別の新規作成ウィンドウやタブに切り替えるなど)、アドイン操作が終了します。 ただし、 OnMessageSend イベントでアクティブ化するアドインは、実行されている Outlook クライアントに応じて、アイテムの切り替えを異なる方法で処理します。 詳細については、「スマート アラートを使用して Outlook アドインで OnMessageSend イベントと OnAppointmentSend イベントを処理する」の「ユーザーが現在のメッセージから離れる」セクションを参照してください。

• アイテムの切り替えに加えて、ユーザーが作成しているメッセージまたは予定を送信すると、イベント ベースのアドインも操作を停止します。

新しい Outlook on Windows でのイベント ベースのアドインの制限事項

新しい Outlook on Windows では、アドインがメール アイテムを処理するために、クライアントのメイン ウィンドウを開いたままにする必要があります。 メイン ウィンドウが最小化されている場合、アドインは動作を一時停止または停止します。

Excel、PowerPoint、Word、クラシック Outlook on Windows でのイベント ベースのアドインの制限事項

Windows クライアントで実行するイベント ベースのアドインを開発する場合は、次の点に注意してください。

• イベント ベースのアクティブ化の処理を実装する JavaScript ファイルでは、インポートはサポートされていません。

• イベント ベースのアクティブ化では、マニフェストで参照されている JavaScript ファイルのみがサポートされます。 イベント処理 JavaScript コードをこの 1 つのファイルにバンドルする必要があります。 マニフェスト内の参照先の JavaScript ファイルの場所は、アドインで使用するマニフェストの種類によって異なります。

  • アドインのみのマニフェスト: <Runtime> ノードの子要素<Override>
  • Microsoft 365 の統合マニフェスト: "code" オブジェクトの "script" プロパティ

  大きな JavaScript バンドルでは、アドインのパフォーマンスに問題が発生する可能性があることに注意してください。 大量の操作を前処理して、イベント処理コードに含めないようにすることをお勧めします。

• イベントを処理するためにマニフェストで指定された JavaScript 関数が実行されると、 Office.onReady() と Office.initialize のコードは実行されません。 代わりに、ユーザーの Outlook バージョンの確認など、イベント ハンドラーに必要なスタートアップ ロジックをイベント ハンドラーに追加することをお勧めします。

Excel、PowerPoint、Wordでのイベント ベースのアドインの制限事項

次のプラットフォームまたは機能はまだサポートされていません。

• Office on Mac
• Microsoft 365 の統合マニフェスト

サポートされていない API

UI を変更または変更する一部の Office.js API は、イベント ベースのアドインからは許可されません。ブロックされた API を次に示します。

イベント ハンドラーのプレビュー機能 (従来の Outlook on Windows)

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

1. レジストリで、[ HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Outlook\Options\WebExt\Developer] に移動します。 キーが存在しない場合は、作成します。

2. EnableBetaAPIsInJavaScript という名前のエントリを作成し、その値を 1 に設定します。

   

シングル サインオン (SSO) を有効にする

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

外部データを要求する

外部データを要求するには 、Fetch などの API を使用するか、サーバーと対話するための HTTP 要求を発行する標準 Web API である XMLHttpRequest (XHR) を使用します。

XMLHttpRequest オブジェクトを使用する場合は、 同じ配信元ポリシー と CORS (クロスオリジン リソース共有) を必要とする追加のセキュリティ対策を使用する必要があることに注意してください。

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

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

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

アドインをデプロイする

イベント ベースのアドインは、AppSource から取得した場合でも、管理者が管理するデプロイにのみ制限されます。 ユーザーが AppSource またはアプリ内 Office ストアからアドインを取得した場合、アドインのイベント ベースの機能をアクティブ化することはできません。 AppSource でイベント ベースのアドインを一覧表示する方法の詳細については、 イベント ベースのアドインの AppSource 一覧表示オプションに関するページを参照してください。

管理デプロイは、マニフェストをMicrosoft 365 管理センターにアップロードすることによって行われます。 これを行うには、次の手順を実行します。

1. 管理ポータルで、ナビゲーション ウィンドウの [設定] セクションを展開し、[ 統合アプリ] を選択します。
2. [ 統合アプリ ] ページで、[ カスタム アプリのアップロード ] アクションを選択します。

アドインを展開する方法の詳細については、「Microsoft 365 管理センターでの Office アドインの展開と発行」を参照してください。

マニフェストの更新プログラムをデプロイする

イベント ベースのアドインは管理者によって展開されるため、マニフェストに対して行った変更には、Microsoft 365 管理センターによる管理者の同意が必要です。 管理者が変更を受け入れるまで、organizationのユーザーはアドインの使用をブロックされます。 管理者の同意プロセスの詳細については、「イベント ベースのアドインをインストールするための同意管理」を参照してください。

関連項目

• イベント ベースのアドインとスパム レポート アドインのトラブルシューティング
• イベント ベースのアドインとスパム レポート アドインをデバッグする
• イベント ベースのアドインの AppSource リスト オプション
• スマート アラートを使用して Outlook アドインで OnMessageSend イベントと OnAppointmentSend イベントを処理する