操作可能なメッセージからの Outlook アドインの呼び出し
アクション可能なメッセージを使用すると、ユーザーは電子メール メッセージに対して迅速なアクションを実行でき、Outlook アドインを使用すると、Outlook を拡張して新しい機能や操作を追加できます。
Action.InvokeAddInCommand アクションの種類を使用することにより、この 2 種類の統合を組み合わせ、さらに強力で優れたエクスペリエンスを実現することができるようになりました。 たとえば、次のように実行します。
- 新しいユーザーがサービスに新規登録した後、アドインを簡単にインストールして使い始められるようにするためのアクションが含まれるウェルカム メッセージを操作可能な電子メール メッセージとしてそのユーザーに送信します。
- 簡単なアクションの入力では十分でないシナリオについては、さらに複雑なアクション (ユーザーにフォームを表示するなど) のためのアドインを使用します。
- ユーザーに UI を表示する前に、アドインの UI 要素を事前設定します。
Action.InvokeAddInCommand アクションはユーザーによって既にインストールされたアドイン、またはインストールされていないアドインのどちらでも動作します。 必要なアドインがインストールされていない場合、ユーザーは、シングルクリックでアドインをインストールするように要求されます。
注:
必要なアドインのシングル クリック インストールは、アドインが AppSource で発行されている場合にのみサポートされます。
次の例は、アドインがインストールされていない場合にユーザーに表示されるプロンプトを示しています。
アドインの呼び出し
メッセージの Action.InvokeAddInCommand アクションを指定すると、操作可能なメッセージによってアドインが呼び出されます。 このアクションでは、呼び出すアドイン、および適切な作業ウィンドウを開くためのアドイン ボタンの識別子を指定します。
必要な情報は「アドイン マニフェスト」を参照してください。 最初に、ID 要素で指定されるアドインの識別子が必要です。
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OfficeApp
xmlns="http://schemas.microsoft.com/office/appforoffice/1.1"
xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
xmlns:bt="http://schemas.microsoft.com/office/officeappbasictypes/1.0"
xsi:type="MailApp">
<Id>527104a1-f1a5-475a-9199-7a968161c870</Id>
<Version>1.0.0.0</Version>
...
</OfficeApp>
このアドインの場合、アドインの識別子は 527104a1-f1a5-475a-9199-7a968161c870 です。
次に、適切な作業ウィンドウを開くアドイン ボタンを定義する Control 要素の id 属性が必要です。
Control 要素は、次の条件を満たしている必要があることに注意してください。
- MessageReadCommandSurface 拡張点の内部で定義されている
-
xsi:type属性がButtonに設定されている -
ShowTaskpaneの種類の Action 要素が含まれている
<ExtensionPoint xsi:type="MessageReadCommandSurface">
<OfficeTab id="TabDefault">
<Group id="msgReadCmdGroup">
<Label resid="groupLabel"/>
<Control xsi:type="Button" id="showInitContext">
<Label resid="readButtonLabel"/>
<Supertip>
<Title resid="readButtonTitle"/>
<Description resid="readButtonDesc"/>
</Supertip>
<Icon>
<bt:Image size="16" resid="icon-16"/>
<bt:Image size="32" resid="icon-32"/>
<bt:Image size="80" resid="icon-80"/>
</Icon>
<Action xsi:type="ShowTaskpane">
<SourceLocation resid="readPaneUrl"/>
<SupportsPinning>true</SupportsPinning>
</Action>
</Control>
</Group>
</OfficeTab>
</ExtensionPoint>
このアドイン ボタンの場合、ID は showInitContext です。
これら 2 つの情報を使用して、基本的な Action.InvokeAddInCommand アクションを次のように作成できます。
{
"type": "AdaptiveCard",
"version": "1.0",
"body": [
{
"type": "TextBlock",
"text": "Invoking an add-in command from an Actionable Message card",
"size": "large"
}
],
"actions": [
{
"type": "Action.InvokeAddInCommand",
"title": "Invoke \"View Initialization Context\"",
"addInId": "527104a1-f1a5-475a-9199-7a968161c870",
"desktopCommandId": "showInitContext"
}
]
}
初期化データをアドインに渡す
Action.InvokeAddInCommand アクションは、アドインに追加のコンテキストを提供することにより、アドインのアクティブ化以外のアクションも実行できるようにします。 たとえば、アクションによって、フォームの初期値を提供したり、アドインがバックエンド サービスの特定の項目に「ディープ リンク」するための情報を提供したりできます。
初期化データを渡すには、initializationContext プロパティを Action.InvokeAddInCommand アクションに含めます。
initializationContext プロパティにスキーマは設定されていないため、任意の有効な JSON オブジェクトを含めることができます。
たとえば、上記のサンプル アクションを拡張するには、次のようにアクションを変更します。
{
"type": "AdaptiveCard",
"version": "1.0",
"body": [
{
"type": "TextBlock",
"text": "Invoking an add-in command from an Actionable Message card",
"size": "large"
}
],
"actions": [
{
"type": "Action.InvokeAddInCommand",
"title": "Invoke \"View Initialization Context\"",
"addInId": "527104a1-f1a5-475a-9199-7a968161c870",
"desktopCommandId": "showInitContext",
"initializationContext": {
"property1": "Hello world",
"property2": 5,
"property3": true
}
}
]
}
初期化データをアドインで受け取る
初期化データを渡すアクションの場合、アドインはそれを受け取るための準備をする必要があります。 アドインは、Office.context.mailbox.item.getInitializationContextAsync メソッドを呼び出して、初期化データを取得できます。 これは、作業ウィンドウを開いたときや新しいメッセージを読み込んだときにはいつでも行う必要があります。
// Get the initialization context (if present).
Office.context.mailbox.item.getInitializationContextAsync((asyncResult) => {
if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
if (asyncResult.value.length > 0) {
// The value is a string, parse to an object.
const context = JSON.parse(asyncResult.value);
// Do something with context.
} else {
// Empty context, treat as no context.
}
} else {
// Handle the error.
}
});