送信時にメッセージまたは予定本文の前にコンテンツを追加または追加する

[アーティクル]
07/18/2024

送信前および追加送信機能を使用すると、Outlook アドインは、メールアイテムの送信時にメッセージまたは予定の本文にコンテンツを挿入できます。これらの機能により、次の機能を有効にすることで、ユーザーの生産性とセキュリティがさらに向上します。

アイテムの識別とorganizationを容易にするために、メッセージと予定に秘密度と分類ラベルを追加します。
法的な目的で免責事項を挿入します。
マーケティングとコミュニケーションの目的で標準化されたヘッダーを追加します。

このチュートリアルでは、ヘッダーの先頭に追加し、メッセージの送信時に免責事項を追加するアドインを開発します。

注:

追加送信機能のサポートは要件セット 1.9 で導入されましたが、要件セット 1.13 では送信前機能のサポートが導入されました。これらの要件セットをサポートするクライアントとプラットフォームを参照してください。

環境を設定する

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

マニフェストを構成する

マニフェストを構成するには、使用するマニフェストの種類のタブを選択します。

Microsoft 365 の統合マニフェスト
アドインのみのマニフェスト

次に、プレペンドオン送信機能と追加オン送信機能を有効にするように統合マニフェストを構成する方法を示します。

manifest.json ファイルを開きます。
"extensions.runtimes" 配列に次のオブジェクトを追加します。このコードについては、次の点に注意してください。
- メールボックス要件セットの "minVersion" は "1.13" に設定されているため、この機能がサポートされていないプラットフォームと Office バージョンにアドインをインストールすることはできません。
- ランタイムの "id" は、わかりやすい名前 "function_command_runtime" に設定されます。
- "code.page" プロパティは、関数コマンドを読み込む UI レス HTML ファイルの URL に設定されます。
- "lifetime" プロパティは "short" に設定されています。つまり、関数コマンドボタンを選択するとランタイムが起動し、関数が完了するとシャットダウンします。 (まれに、ハンドラーが完了する前にランタイムがシャットダウンする場合があります。「Office アドインのランタイム」を参照してください)。
- "prependHeaderOnSend" 関数と "appendDisclaimerOnSend" 関数を実行するために指定されたアクションがあります。これらの関数は、後の手順で作成します。
```
{
    "requirements": {
        "capabilities": [
            {
                "name": "Mailbox",
                "minVersion": "1.13"
            }
        ],
        "formFactors": [
            "desktop"
        ]
    },
    "id": "function_command_runtime",
    "type": "general",
    "code": {
        "page": "https://localhost:3000/commands.html"
    },
    "lifetime": "short",
    "actions": [
        {
            "id": "prependHeaderOnSend",
            "type": "executeFunction",
            "displayName": "prependHeaderOnSend"
        },
        {
            "id": "appendDisclaimerOnSend",
            "type": "executeFunction",
            "displayName": "appendDisclaimerOnSend"
        }
    ]
}
```

"extensions.ribbons" 配列に次のオブジェクトを追加します。このコードについては、次の点に注意してください。

"mailCompose" の値が "contexts" 配列に追加され、新規作成ウィンドウで prepend-on-send ボタンと append-on-send ボタンが表示されます。
"controls" オブジェクトは、prepend-on-send 関数と append-on-send 関数のボタンを作成して構成します。各オブジェクトの "actionId" プロパティには、"extensions.runtimes" オブジェクトの該当する "actions.id" プロパティで指定された値と同じ値が反映されている必要があります。

{
    "contexts": [
        "mailCompose"
    ],
    "tabs": [
        {
            "builtInTabId": "TabDefault",
            "groups": [
                {
                    "id": "msgComposeGroup",
                    "label": "Contoso Add-in",
                    "icons": [
                        {
                            "size": 16,
                            "url" "https://localhost:3000/assets/icon-16.png"
                        },
                        {
                            "size": 32,
                            "url" "https://localhost:3000/assets/icon-32.png"
                        },
                        {
                            "size": 80,
                            "url" "https://localhost:3000/assets/icon-80.png"
                        }
                    ],
                    "controls": [
                        {
                            "id": "PrependButton",
                            "type": "button",
                            "label": "Prepend header",
                            "icons": [
                                {
                                    "size": 16,
                                    "url" "https://localhost:3000/assets/icon-16.png"
                                },
                                {
                                    "size": 32,
                                    "url" "https://localhost:3000/assets/icon-32.png"
                                },
                                {
                                    "size": 80,
                                    "url" "https://localhost:3000/assets/icon-80.png"
                                }
                            ],
                            "supertip": {
                                "title": "Prepend header on send",
                                "description": "Prepend the Contoso header on send."
                            },
                            "actionId": "prependHeaderOnSend"
                        },
                        {
                            "id": "AppendButton",
                            "type": "button",
                            "label": "Add disclaimer",
                            "icons": [
                                {
                                    "size": 16,
                                    "url" "https://localhost:3000/assets/icon-16.png"
                                },
                                {
                                    "size": 32,
                                    "url" "https://localhost:3000/assets/icon-32.png"
                                },
                                {
                                    "size": 80,
                                    "url" "https://localhost:3000/assets/icon-80.png"
                                }
                            ],
                            "supertip": {
                                "title": "Append disclaimer on send",
                                "description": "Append the Contoso disclaimer on send."
                            },
                            "actionId": "appendDisclaimerOnSend"
                        }
                    ]
                }
            ]
        }
    ]
}

"authorization.permissions.resourceSpecific" 配列に、次のオブジェクトを追加します。配列内の他のオブジェクトからコンマで区切っていることを確認します。
```
{
  "name": "Mailbox.AppendOnSend.User",
  "type": "Delegated"
}
```
変更内容を保存します。

アドインで送信前機能と追加送信機能を有効にするには、ExtendedPermissions のコレクションに AppendOnSend アクセス許可を含める必要があります。さらに、メッセージ本文の先頭にコンテンツを追加するように関数コマンドを構成します。

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

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

<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">
        <DesktopFormFactor>
          <FunctionFile resid="Commands.Url" />
          <ExtensionPoint xsi:type="MessageComposeCommandSurface">
            <OfficeTab id="TabDefault">
              <Group id="msgComposeGroup">
                <Label resid="GroupLabel" />
                <Control xsi:type="Button" id="msgComposeOpenPaneButton">
                  <Label resid="TaskpaneButton.Label" />
                  <Supertip>
                    <Title resid="TaskpaneButton.Label" />
                    <Description resid="TaskpaneButton.Tooltip" />
                  </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="ShowTaskpane">
                    <SourceLocation resid="Taskpane.Url" />
                  </Action>
                </Control>
                <!-- Configure the prepend-on-send function command. -->
                <Control xsi:type="Button" id="PrependButton">
                  <Label resid="PrependButton.Label"/>
                  <Supertip>
                    <Title resid="PrependButton.Label"/>
                    <Description resid="PrependButton.Tooltip"/>
                  </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>prependHeaderOnSend</FunctionName>
                  </Action>
                </Control>
                <!-- Configure the append-on-send function command. -->
                <Control xsi:type="Button" id="AppendButton">
                  <Label resid="AppendButton.Label"/>
                  <Supertip>
                    <Title resid="AppendButton.Label"/>
                    <Description resid="AppendButton.Tooltip"/>
                  </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>appendDisclaimerOnSend</FunctionName>
                  </Action>
                </Control>
              </Group>
            </OfficeTab>
          </ExtensionPoint>

          <!-- Append-on-send and prepend-on-send are supported in Message Compose and Appointment Organizer modes. 
          To support these features when creating a new appointment, configure the AppointmentOrganizerCommandSurface extension point. -->

        </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="Commands.Url" DefaultValue="https://localhost:3000/commands.html" />
        <bt:Url id="Taskpane.Url" DefaultValue="https://localhost:3000/taskpane.html" />
      </bt:Urls>
      <bt:ShortStrings>
        <bt:String id="GroupLabel" DefaultValue="Contoso Add-in"/>
        <bt:String id="TaskpaneButton.Label" DefaultValue="Show Taskpane"/>
        <bt:String id="PrependButton.Label" DefaultValue="Prepend header"/>
        <bt:String id="AppendButton.Label" DefaultValue="Add disclaimer"/>
      </bt:ShortStrings>
      <bt:LongStrings>
        <bt:String id="TaskpaneButton.Tooltip" DefaultValue="Opens a pane displaying all available properties."/>
        <bt:String id="PrependButton.Tooltip" DefaultValue="Prepend the Contoso header on send."/>
        <bt:String id="AppendButton.Tooltip" DefaultValue="Append the Contoso disclaimer on send."/>
      </bt:LongStrings>
    </Resources>
    <!-- Configures the prepend-on-send and append-on-send features. The same value, AppendOnSend, is used for both features. -->
    <ExtendedPermissions>
      <ExtendedPermission>AppendOnSend</ExtendedPermission>
    </ExtendedPermissions>
  </VersionOverrides>
</VersionOverrides>

変更内容を保存します。

ヒント

ユーザーは、作業ウィンドウまたは関数コマンドボタンを使用して、送信前および追加オン送信機能をアクティブにする必要があります。ユーザーからの追加アクションなしで送信時にコンテンツの先頭または追加を行う場合は、イベントベースのアクティブ化アドインでこれらの機能を実装できます。
Outlook アドインのマニフェストの詳細については、「 Office アドインマニフェスト」を参照してください。

送信前ハンドラーを実装する

このセクションでは、JavaScript コードを実装して、送信時にサンプル企業ヘッダーの前にメールアイテムを追加します。

プロジェクトの ./src/commands フォルダーに移動し、 commands.js ファイルを開きます。

ファイルの末尾に次の関数を挿入します。

function prependHeaderOnSend(event) {
  // It's recommended to call the getTypeAsync method and pass its returned value to the options.coercionType parameter of the prependOnSendAsync call.
  Office.context.mailbox.item.body.getTypeAsync(
    {
      asyncContext: event
    },
    (asyncResult) => {
      if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.log(asyncResult.error.message);
        return;
      }

      // Sets the header to be prepended to the body of the message on send.
      const bodyFormat = asyncResult.value;
      // Because of the various ways in which HTML text can be formatted, the content may render differently when it's prepended to the mail item body.
      // In this scenario, a <br> tag is added to the end of the HTML string to preserve its format.
      const header = '<div style="border:3px solid #000;padding:15px;"><h1 style="text-align:center;">Contoso Limited</h1></div><br>';

      Office.context.mailbox.item.body.prependOnSendAsync(
        header,
        {
          asyncContext: asyncResult.asyncContext,
          coercionType: bodyFormat
        },
        (asyncResult) => {
          if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            console.log(asyncResult.error.message);
            return;
          }

          console.log("The header will be prepended when the mail item is sent.");
          asyncResult.asyncContext.completed();
        }
      );
  });
}

変更内容を保存します。

append-on-send ハンドラーを実装する

このセクションでは、JavaScript コードを実装して、送信時にサンプル企業の免責事項をメールアイテムに追加します。

同じ commands.js ファイルで、 prependHeaderOnSend 関数の後に次の関数を挿入します。

function appendDisclaimerOnSend(event) { 
  // Calls the getTypeAsync method and passes its returned value to the options.coercionType parameter of the appendOnSendAsync call.
  Office.context.mailbox.item.body.getTypeAsync(
    {
      asyncContext: event
    }, 
    (asyncResult) => {
      if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.log(asyncResult.error.message);
        return;
    }

    // Sets the disclaimer to be appended to the body of the message on send.
    const bodyFormat = asyncResult.value;
    const disclaimer =
      '<p style = "color:blue"> <i>This and subsequent emails on the same topic are for discussion and information purposes only. Only those matters set out in a fully executed agreement are legally binding. This email may contain confidential information and should not be shared with any third party without the prior written agreement of Contoso. If you are not the intended recipient, take no action and contact the sender immediately.<br><br>Contoso Limited (company number 01624297) is a company registered in England and Wales whose registered office is at Contoso Campus, Thames Valley Park, Reading RG6 1WG</i></p>';  

    Office.context.mailbox.item.body.appendOnSendAsync(
      disclaimer,
      {
        asyncContext: asyncResult.asyncContext,
        coercionType: bodyFormat
      },
      (asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
          console.log(asyncResult.error.message);
          return;
        }

        console.log("The disclaimer will be appended when the mail item is sent.");
        asyncResult.asyncContext.completed();
      }
    );
  });
}

変更内容を保存します。

JavaScript 関数を登録する

同じ commands.js ファイルで、 appendDisclaimerOnSend 関数の後に次を挿入します。これらの呼び出しは、マニフェストで指定された関数名を、対応する JavaScript にマップします。マニフェスト内の関数名の場所は、アドインで使用するマニフェストの種類によって異なります。

アドインのみのマニフェスト: <FunctionName> 要素で指定された関数名。
Microsoft 365 の統合マニフェスト: "extensions.runtimes.actions" 配列内のオブジェクトの "id" プロパティに指定された関数名。
```
Office.actions.associate("prependHeaderOnSend", prependHeaderOnSend);
Office.actions.associate("appendDisclaimerOnSend", appendDisclaimerOnSend);
```

変更内容を保存します。

試してみる

プロジェクトのルートディレクトリから次のコマンドを実行します。このコマンドを実行すると、ローカル Web サーバーがまだ実行されていない場合に起動し、アドインがサイドロードされます。
```
npm start
```
注:

アドインが自動的にサイドロードされなかった場合は、「 Outlook アドインをサイドロードしてテストする」の手順に従って、Outlook でアドインを手動でサイドロードします。
新しいメッセージを作成し、[ To ] 行に自分を追加します。
(省略可能)メッセージの本文にテキストを入力します。
リボンまたはオーバーフローメニューから、[ 先頭ヘッダー] を選択します。
リボンまたはオーバーフローメニューから、[免責事項の追加] を選択します。
メッセージを送信し、[ 受信トレイ] フォルダーまたは [送信済みアイテム] フォルダーからメッセージを開き、挿入されたコンテンツを表示します。

ヒント

コンテンツはメッセージが送信された後にのみ先頭または追加されるため、送信者は 受信トレイ または送信済み アイテム フォルダーから追加されたコンテンツのみを表示できます。メッセージが送信される前に送信者に追加されたコンテンツの表示を要求する場合は、「 Outlook で予定またはメッセージを作成するときに本文にデータを挿入する」を参照してください。
ローカル Web サーバーを停止してアドインをアンインストールする場合は、該当する手順に従います。
- サーバーを停止するには、次のコマンドを実行します。 npm startを使用した場合は、次のコマンドもアドインをアンインストールする必要があります。
```
npm stop
```
- アドインを手動でサイドロードした場合は、「サイドロードされたアドインを削除する」を参照してください。

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

アドインで prepend-on-send と append-on-send を実装するときは、次の点に注意してください。

Prepend-on-send と append-on-send は、作成モードでのみサポートされます。
先頭または追加する文字列は、5,000 文字を超えてはなりません。
HTML を先頭に追加したり、メッセージや予定のプレーンテキスト本文に追加したりすることはできません。ただし、プレーンテキストは、メッセージまたは予定の HTML 形式の本文に追加できます。
先頭または追加されたコンテンツに適用される書式設定は、メールアイテムの本文の残りのスタイルには影響しません。
送信前と送信時の追加は、送信時機能を実装するのと同じアドインに実装できません。別の方法として、代わりにスマートアラートを実装することを検討してください。
同じアドインでスマートアラートを実装する場合、送信前操作と追加送信操作は、 OnMessageSend および OnAppointmentSend イベントハンドラー操作の前に実行されます。
複数のアクティブなアドインで prepend-on-send または append-on-send を使用する場合、挿入するコンテンツの順序は、アドインが実行された順序によって異なります。送信前に送信する場合、最後に実行されるアドインのコンテンツは、前に先頭に追加されたコンテンツの前のメールアイテム本文の上部に表示されます。追加オン送信の場合、最後に実行されるアドインのコンテンツは、前に追加したコンテンツの後のメールアイテム本文の下部に表示されます。
代理メールボックスと共有メールボックスのシナリオは、共有メールボックスまたは所有者のアカウントで、送信前または追加送信を実装するアドインが有効になっている限りサポートされます。

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

prepend-on-send および append-on-send 機能の実装中にエラーが発生した場合は、ガイダンスについては、次の表を参照してください。

エラー	説明	解決方法
`DataExceedsMaximumSize`	追加または先頭に追加するコンテンツが 5,000 文字を超えています。	`prependOnSendAsync`または`appendOnSendAsync`呼び出しの`data` パラメーターに渡す文字列を短くします。
`InvalidFormatError`	メッセージまたは予定の本文はプレーンテキスト形式ですが、`prependOnSendAsync` または `appendOnSendAsync` メソッドに渡される`coercionType`は `Office.CoercionType.Html` に設定されます。	プレーンテキストのみを、メッセージまたは予定のプレーンテキスト本文に挿入できます。構成されているメールアイテムの形式を確認するには、 `Office.context.mailbox.item.body.getTypeAsync`を呼び出し、返された値を `prependOnSendAsync` または `appendOnSendAsync` 呼び出しに渡します。

次の方法で共有