操作可能なメッセージからの Outlook アドインの呼び出し

[アーティクル]
04/08/2023

操作可能なメッセージにより、ユーザーは電子メールメッセージまたはコネクタカードで迅速にアクションを実行できます。また、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.
  }
});

リソース

Outlook-Add-In-Actionable-Message サンプルアドイン

操作可能なメッセージからの Outlook アドインの呼び出し

アドインの呼び出し

初期化データをアドインに渡す

初期化データをアドインで受け取る

リソース

その他のリソース