複数の Exchange アカウントを使用する場合のメッセージへの正しい署名の適用が、イベント ベースのアクティブ化機能にOnMessageFromChanged
イベントとOnAppointmentFromChanged
イベントを追加することで簡単になりました。
OnMessageFromChanged
イベントは、構成中のメッセージの From フィールドのアカウントが変更されたときに発生し、OnAppointmentFromChanged
イベントは、構成中の会議の開催者が変更されたときに発生します。 これらのイベントにより、署名アドインの機能がさらに拡張され、次の機能が可能になります。
- 各アカウントにカスタム署名を適用する利便性をユーザーに提供します。
- メールボックス代理人が複数のメールボックスからの送信メッセージと会議出席依頼をより正確かつ効率的に管理できるようにします。
- ユーザーのメッセージと予定が、organizationのコミュニケーションとマーケティング ポリシーを満たしていることを確認します。
次のセクションでは、[差出人] フィールドのメール アカウントが変更されたときにメッセージの署名を自動的に更新するように、OnMessageFromChanged
イベントを処理するイベント ベースのアドインを開発する方法について説明します。
注:
OnMessageFromChanged
イベントとOnAppointmentFromChanged
イベントは、要件セット 1.13 で導入されました。 これらのイベントのクライアント サポートについては、「 サポートされているクライアントとプラットフォーム」を参照してください。
サポートされているクライアントとプラットフォーム
次の表に、 OnMessageFromChanged
イベントと OnAppointmentFromChanged
イベントをサポートするクライアントとサーバーの組み合わせを示します。 該当するイベントのタブを選択します。
クライアント | Exchange Online | Exchange 2019 オンプレミス (累積的な更新プログラム 12 以降) | Exchange 2016 オンプレミス (累積的な更新プログラム 22 以降) |
---|---|---|---|
Web ブラウザー (モダン UI) 新しい Outlook on Windows |
サポート | × | 該当なし |
Windows (クラシック) バージョン 2304 (ビルド 16327.20248) 以降 |
サポート | サポート | サポート |
Mac バージョン 16.77 (23081600) 以降 |
サポート | × | 該当なし |
iOS バージョン 4.2502.0 |
サポート | × | 該当なし |
Android バージョン 4.2502.0 |
サポート | × | 該当なし |
前提条件
チュートリアルをテストするには、少なくとも 2 つの Exchange アカウントが必要です。
環境を設定する
Office アドイン用 Yeoman ジェネレーターを使用してアドイン プロジェクトを作成する Outlook クイック スタートを完了します。
マニフェストを構成する
manifest.json ファイルを開きます。
"authorization.permissions.resourceSpecific"
配列に移動します。 配列オブジェクトで、"name"
プロパティの値を"MailboxItem.ReadWrite.User"
に置き換えます。 これは、メッセージの署名を更新できるようにするためにアドインで必要です。... "authorization": { "permissions": { "resourceSpecific": [ { "name": "MailboxItem.ReadWrite.User", "type": "Delegated" } ] } }, ...
"extensions.runtimes"
配列に次のオブジェクトを追加します。 このマークアップについて、次の情報にご注意ください。メールボックス要件セットの
"minVersion"
は、OnMessageFromChanged
イベントをサポートする最小バージョンの要件セットであるため、"1.13"
として構成されます。 詳細については、「 イベント ベースのアクティブ化のために Outlook アドインを構成する」の「サポートされているイベント」の表を参照してください。ランタイムの
"id"
は、わかりやすい名前 ("autorun_runtime"
) に設定されます。"code"
プロパティには、子"page"
プロパティが HTML ファイルに設定され、子"script"
プロパティが JavaScript ファイルに設定されています。 これらのファイルは、後の手順で作成または編集します。 Office では、プラットフォームに応じてこれらの値のいずれかを使用します。- クラシック Outlook on Windows では、JavaScript 専用ランタイムでイベント ハンドラーが実行され、JavaScript ファイルが直接読み込まれます。
- Outlook on the webと Mac、および新しい Outlook on Windows では、ブラウザー ランタイムでハンドラーが実行され、HTML ファイルが読み込まれます。 HTML ファイルには、JavaScript ファイルを読み込む
<script>
タグが含まれています。
詳細については、「 Office アドインのランタイム」を参照してください。
"lifetime"
プロパティは"short"
に設定されています。 つまり、イベントが発生するとランタイムが起動し、ハンドラーが完了するとシャットダウンします。OnMessageFromChanged
イベントとOnNewMessageCompose
イベントのハンドラーを実行する"actions"
があります。 ハンドラーは、後の手順で作成します。
{ "requirements": { "capabilities": [ { "name": "Mailbox", "minVersion": "1.13" } ] }, "id": "autorun_runtime", "type": "general", "code": { "page": "https://localhost:3000/commands.html", "script": "https://localhost:3000/launchevent.js" }, "lifetime": "short", "actions": [ { "id": "onMessageFromChangedHandler", "type": "executeFunction", "displayName": "onMessageFromChangedHandler" }, { "id": "onNewMessageComposeHandler", "type": "executeFunction", "displayName": "onNewMessageComposeHandler" } ] }
"extensions"
配列内の オブジェクトのプロパティとして、"autoRunEvents"
配列を追加します。"autoRunEvents"
配列には、次のキー プロパティを持つ オブジェクトが含まれています。-
"events"
プロパティは、ハンドラーをOnMessageFromChanged
およびOnNewMessageCompose
イベントに割り当てます。 統合マニフェストで使用されるイベント名については、「イベント ベースのアクティブ化のために Outlook アドインを構成する」の「サポートされているイベント」の表を参照してください。 -
"actionId"
で指定する関数名は、前に構成した"actions"
配列内の対応するオブジェクトの"id"
プロパティと一致する必要があります。
"autoRunEvents": [ { "requirements": { "capabilities": [ { "name": "Mailbox", "minVersion": "1.13" } ], "scopes": [ "mail" ] }, "events": [ { "type": "messageFromChanged", "actionId": "onMessageFromChangedHandler" }, { "type": "newMessageComposeCreated", "actionId": "onNewMessageComposeHandler" } ] } ]
-
ヒント
- アドインのランタイムの詳細については、「 Office アドインのランタイム」を参照してください。
- Outlook アドインのマニフェストの詳細については、「 Office アドイン マニフェスト」を参照してください。
イベント ハンドラーを実装する
イベント ハンドラーは、 OnNewMessageCompose
イベントと OnMessageFromChanged
イベントに対して構成する必要があります。
onNewMessageComposeHandler
関数は、既定のメッセージがまだ現在のアカウントで構成されていない場合に、新しく作成されたメッセージに署名を追加します。
[From]\(元\) フィールドのアカウントが変更されると、onMessageFromChangedHandler
関数は、この新しく選択したアカウントに基づいて署名を更新します。
同じクイック スタート プロジェクトから ./src ディレクトリに移動し、 launchevent という名前の新しいフォルダーを作成します。
./src/launchevent フォルダーに、 という名前の新しいファイル launchevent.js作成します。
コード エディターで ./src/launchevent/launchevent.js ファイルを開き、次の JavaScript コードを追加します。
/* * Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license. * See LICENSE in the project root for license information. */ // The OnNewMessageCompose event handler that adds a signature to a new message. function onNewMessageComposeHandler(event) { const platform = Office.context.platform; const signature = "<i>This is a sample signature.</i>"; // On supported platforms, check if a default Outlook signature is already configured. if (platform !== Office.PlatformType.Android && platform !== Office.PlatformType.iOS) { Office.context.mailbox.item.isClientSignatureEnabledAsync({ asyncContext: { event: event, signature: signature } }, (result) => { if (result.status === Office.AsyncResultStatus.Failed) { console.log(result.error.message); return; } // Add a signature if there's no default Outlook signature configured. const signatureEnabled = result.value; if (signatureEnabled === false) { const event = result.asyncContext.event; const signature = result.asyncContext.signature; setSignature(signature, event); } }); } else { setSignature(signature, event); } } // The OnMessageFromChanged event handler that updates the signature when the email address in the From field is changed. function onMessageFromChangedHandler(event) { const item = Office.context.mailbox.item; const signatureIcon = "iVBORw0KGgoAAAANSUhEUgAAACcAAAAnCAMAAAC7faEHAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAzUExURQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAKMFRskAAAAQdFJOUwAQIDBAUGBwgI+fr7/P3+8jGoKKAAAACXBIWXMAAA7DAAAOwwHHb6hkAAABT0lEQVQ4T7XT2ZalIAwF0DAJhMH+/6+tJOQqot6X6joPiouNBo3w9/Hd6+hrYnUt6vhLcjEAJevVW0zJxABSlcunhERpjY+UKoNN5+ZgDGu2onNz0OngjP2FM1VdyBW1LtvGeYrBLs7U5I1PTXZt+zifcS3Icw2GcS3vxRY3Vn/iqx31hUyTnV515kdTfbaNhZLI30AceqDiIo4tyKEmJpKdP5M4um+nUwfDWxAXdzqMNKQ14jLdL5ntXzxcRF440mhS6yu882Kxa30RZcUIjTCJg7lscsR4VsMjfX9Q0Vuv/Wd3YosD1J4LuSRtaL7bzXGN1wx2cytUdncDuhA3fu6HPTiCvpQUIjZ3sCcHVbvLtbNTHlysx2w9/s27m9gEb+7CTri6hR1wcTf2gVf3wBRe3CMbcHYvTODkXhnD0+178K/pZ9+n/C1ru/2HAPwAo7YM1X4+tLMAAAAASUVORK5CYII="; // Get the currently selected From account. item.from.getAsync({ asyncContext: event }, (result) => { if (result.status === Office.AsyncResultStatus.Failed) { console.log(result.error.message); return; } // Create a signature based on the currently selected From account. const name = result.value.displayName; const options = { asyncContext: { event: result.asyncContext, name: name }, isInline: true }; item.addFileAttachmentFromBase64Async(signatureIcon, "signatureIcon.png", options, (result) => { if (result.status === Office.AsyncResultStatus.Failed) { console.log(result.error.message); return; } // Add the created signature to the mail item. const signature = "<img src='cid:signatureIcon.png'>" + result.asyncContext.name; const event = result.asyncContext.event; setSignature(signature, event); }); }); } // Sets the custom signature and adds it to the mail item. function setSignature(signature, event) { Office.context.mailbox.item.body.setSignatureAsync( signature, { asyncContext: event, coercionType: Office.CoercionType.Html }, (result) => { if (result.status === Office.AsyncResultStatus.Failed) { console.log(result.error.message); return; } console.log("Successfully added signature."); const event = result.asyncContext; event.completed(); } ); } // 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("onNewMessageComposeHandler", onNewMessageComposeHandler); Office.actions.associate("onMessageFromChangedHandler", onMessageFromChangedHandler);
重要
- クラシック Outlook on Windows では、イベント ベースのアクティブ化の処理を実装する JavaScript ファイルでは、インポートはサポートされていません。
- 従来の Outlook on Windows では、イベントを処理するためにマニフェストで指定された JavaScript 関数が実行されると、
Office.onReady()
およびOffice.initialize
のコードは実行されません。 代わりに、ユーザーの Outlook バージョンの確認など、イベント ハンドラーに必要なスタートアップ ロジックをイベント ハンドラーに追加することをお勧めします。 - イベントが発生したときにアドインが期待どおりに実行されるようにするには、ハンドラーが実装されている JavaScript ファイルで
Office.actions.associate
を呼び出します。 これにより、マニフェストで指定されたイベント ハンドラー名が、対応する JavaScript にマップされます。 マニフェスト内のハンドラー名の場所は、アドインで使用するマニフェストの種類によって異なります。-
Microsoft 365 の統合マニフェスト: 該当する
"autoRunEvents.events"
オブジェクトの"actionId"
プロパティで指定された値。 - アドインのみのマニフェスト: 該当する LaunchEvent 要素で指定された関数名。
-
Microsoft 365 の統合マニフェスト: 該当する
コマンド HTML ファイルを更新する
./src/commands フォルダーから、commands.htmlを開きます。
既存の スクリプト タグの下に次のコードを追加します。
<script type="text/javascript" src="../launchevent/launchevent.js"></script>
変更内容を保存します。
Webpackの機能設定を更新する
プロジェクトのルート ディレクトリから、 webpack.config.js ファイルを開きます。
config
オブジェクト内のplugins
配列を見つけて、配列の先頭に次の新しいオブジェクトを追加します。new CopyWebpackPlugin({ patterns: [ { from: "./src/launchevent/launchevent.js", to: "launchevent.js", }, ], }),
変更内容を保存します。
試してみる
プロジェクトのルート ディレクトリで次のコマンドを実行します。
npm start
を実行すると、ローカル Web サーバーが起動し (まだ実行されていない場合)、アドインがサイドロードされます。npm run build
npm start
注:
- Yeoman ジェネレーターを初めて使用して Office アドインを開発すると、既定のブラウザーでウィンドウが開き、Microsoft 365 アカウントにサインインするように求められます。 サインイン ウィンドウが表示されない場合、サイドローディングまたはログイン タイムアウト エラーが発生した場合は、
npm start
をもう一度実行する前に、atk auth login m365
を実行します。
アドインが自動的にサイドロードされなかった場合は、「 Outlook アドインをサイドロードしてテストする 」の手順に従って、Outlook でアドインを手動でサイドロードします。
- Yeoman ジェネレーターを初めて使用して Office アドインを開発すると、既定のブラウザーでウィンドウが開き、Microsoft 365 アカウントにサインインするように求められます。 サインイン ウィンドウが表示されない場合、サイドローディングまたはログイン タイムアウト エラーが発生した場合は、
任意の Outlook クライアントで、新しいメッセージを作成します。 既定の Outlook 署名が構成されていない場合は、アドインによって新しく作成されたメッセージに追加されます。 モバイル デバイスの Outlook では、既定の署名が構成されている場合でも、アドインによってサンプル署名が追加されます。
該当する場合は、[ From ] フィールドを有効にします。 有効にする方法のガイダンスについては、「 メール メッセージの送信に使用するアカウントを変更する」の「From ボタンが表示されない理由」セクションを参照してください。
[ 元] を選択し、別の Exchange アカウントを選択します。 または、[差出人>その他のEmailアドレス] を選択して、Exchange メール アドレスを手動で入力します。 更新された署名がメッセージに追加され、前の署名が置き換えられます。
ローカル Web サーバーを停止してアドインをアンインストールする場合は、該当する手順に従います。
サーバーを停止するには、次のコマンドを実行します。
npm start
を使用した場合は、次のコマンドもアドインをアンインストールする必要があります。npm stop
アドインを手動でサイドロードした場合は、「 サイドロードされたアドインを削除する」を参照してください。
アドインのトラブルシューティング
イベント ベースのアクティブ化アドインのトラブルシューティング方法のガイダンスについては、「 イベント ベースおよびスパムレポート アドインのトラブルシューティング」を参照してください。
ユーザーにデプロイする
他のイベント ベースのアドインと同様に、OnMessageFromChanged
イベントとOnAppointmentFromChanged
イベントを使用するアドインは、organizationの管理者が展開する必要があります。 Microsoft 365 管理センターを使用してアドインを展開する方法のガイダンスについては、「イベント ベースのアクティブ化のために Outlook アドインを構成する」の「ユーザーに展開する」セクションを参照してください。
イベントの動作と制限事項
OnMessageFromChanged
イベントとOnAppointmentFromChanged
イベントはイベント ベースのアクティブ化機能を通じてサポートされるため、このイベントの結果としてアクティブ化するアドインにも同じ動作と制限が適用されます。 詳細については、「 イベント ベースのアクティブ化の動作と制限事項」を参照してください。
これらの特性に加えて、アドインがこれらのイベントに対してアクティブ化する場合にも、次の側面が適用されます。
-
OnMessageFromChanged
イベントはメッセージ作成モードでのみサポートされますが、OnAppointmentFromChanged
イベントは予定作成モードでのみサポートされます。 - Outlook on the web、Windows (新規およびクラシック)、モバイル デバイスでは、
OnMessageFromChanged
イベントのみがサポートされます。 -
OnMessageFromChanged
イベントとOnAppointmentFromChanged
イベントでは、Exchange アカウントのみがサポートされます。 ユーザーが [From or organizer]\(元または開催者\) フィールドで Exchange 以外のアカウントに切り替えた場合、Outlook クライアントは、以前に選択したアカウントによって設定された署名を自動的にクリアします。 - Outlook クライアントに応じて、構成中のメッセージでは、[ 差 出人] フィールドドロップダウン リストから Exchange アカウントが選択されるか、フィールドに手動で入力されます。 モバイル デバイス上の Outlook では、[ From ] フィールド ドロップダウン リストからのアカウントの選択のみがサポートされます。 構成中の予定では、開催者フィールドのドロップダウン リストから Exchange アカウントが選択されます。
- Outlook on the web、Windows (新規およびクラシック) と Mac では、
OnMessageFromChanged
イベントとOnAppointmentFromChanged
イベントは、代理人と共有メールボックスのシナリオをサポートします。 これらのシナリオは、モバイル デバイスの Outlook ではサポートされていません。 -
OnAppointmentFromChanged
イベントは、Microsoft 365 グループの予定表ではサポートされていません。 ユーザーが Exchange アカウントから開催者フィールドの Microsoft 365 グループ予定表アカウントに切り替えた場合、Outlook クライアントは Exchange アカウントによって設定された署名を自動的にクリアします。 -
[開始] または [開催者] フィールドで別の Exchange アカウントに切り替えると、以前に選択したアカウントのアドイン (存在する場合) が終了し、新しく選択したアカウントに関連付けられているアドインが読み込まれると、
OnMessageFromChanged
またはOnAppointmentFromChanged
イベントが開始されます。 - Outlook on the web、Windows (新規およびクラシック) と Mac では、メール アカウントエイリアスがサポートされます。 現在のアカウントのエイリアスが [From or organizer]\(元またはオーガナイザー\) フィールドで選択されている場合、アカウントのアドインを再読み込みせずに、
OnMessageFromChanged
またはOnAppointmentFromChanged
イベントが発生します。Emailアカウントエイリアスは、モバイル デバイスの Outlook ではサポートされていません。 -
[From]\(開始\) または [開催者] フィールドドロップダウン リストが誤って開かれた場合、または [開始] または [開催者] フィールドに表示されるのと同じアカウントが再選択されると、
OnMessageFromChanged
またはOnAppointmentFromChanged
イベントが発生しますが、アカウントのアドインは終了または再読み込みされません。
関連項目
Office Add-ins