Microsoft 365 用の統合マニフェストを使用して Outlook アドインを構築する (プレビュー)

[アーティクル]
12/13/2023

Microsoft 365 の統合マニフェストを使用する Outlook アドインプロジェクトの作成に使用できるツールは 2 つあります。この記事では、Office 用 Yeoman ジェネレーター ("Yo Office" とも呼ばれます) で行う方法について説明します。または、「Teams Toolkit を使用して Office アドインプロジェクトを作成する (プレビュー)」で説明されているように、 Teams ツールキットを使用して Outlook アドインプロジェクトを作成することもできます。

この記事では、選択したメッセージのプロパティを表示し、閲覧ウィンドウで通知をトリガーし、作成ウィンドウのメッセージにテキストを挿入する Outlook 作業ウィンドウアドインを作成するプロセスについて説明します。このアドインでは、Teams 拡張機能 (カスタムタブやメッセージング拡張機能など) で使用される、統合された JSON 形式のマニフェストのプレビューバージョンが使用されます。このマニフェストの詳細については、「 Microsoft 365 の統合マニフェスト (プレビュー)」を参照してください。

注:

新しいマニフェストはプレビューで使用でき、Outlook for Windows でのみサポートされます。フィードバックに基づいて変更される場合があります。経験豊富なアドイン開発者には、それを試してみることをお勧めします。プレビューマニフェストは、運用環境のアドインでは使用しないでください。

プレビューは、Microsoft 365 サブスクリプションからダウンロードされ、Windows にインストールされている Office でのみサポートされています。

ヒント

XML マニフェストを使用して Outlook アドインを構築する場合は、「最初の Outlook アドインの構築」を参照してください。

アドインを作成する

統合マニフェストを使用して Office アドインを作成するには、 Office アドイン用 Yeoman ジェネレーターを使用します。Yeoman ジェネレーターは、Visual Studio Code またはその他のエディターで管理できる Node.js プロジェクトを作成します。

前提条件

Windows 用の .NET ランタイム。プレビューで使用されるツールの 1 つは、.NET で実行されます。

Node.js (最新 LTS バージョン)。 Node.js サイトにアクセスして、オペレーティングシステムに適したバージョンをダウンロードしてインストールします。
最新バージョンの Yeoman と Office アドイン用の Yeoman ジェネレーター。これらのツールをグローバルにインストールするには、コマンドプロンプトから次のコマンドを実行します。
```
npm install -g yo generator-office
```
注:

Yeomanのジェネレーターを過去に取付けている場合でも、npmからのパッケージを最新のバージョンにすることをお勧めします。
Microsoft 365 サブスクリプションに接続されている Office (Office for the web を含む)。

注:

まだ Office をお持ちでない場合は、Microsoft 365 開発者プログラムを通じてMicrosoft 365 E5開発者サブスクリプションを受ける資格があります。詳細については、FAQ を参照してください。または、 1 か月間の無料試用版にサインアップするか、 Microsoft 365 プランを購入することもできます。

Visual Studio Code (VS Code) またはお好みのコードエディター
Outlook on Windows (Microsoft 365 アカウントに接続)

アドインプロジェクトの作成

次のコマンドを実行し、Yeoman ジェネレーターを使用してアドインプロジェクトを作成します。プロジェクトを含むフォルダーが現在のディレクトリに追加されます。
```
yo office
```
注:

yo officeコマンドを実行すると、Yeoman のデータ収集ポリシーと Office アドイン CLI ツールに関するプロンプトが表示される場合があります。提供された情報を使用して、必要に応じてプロンプトに応答します。

プロンプトが表示されたら、以下の情報を入力してアドインプロジェクトを作成します。
- Choose a project type: (プロジェクトの種類を選択) - Outlook Add-in with unified Microsoft 365 Manifest (preview)
- What would you want to name your add-in? (アドインの名前を何にしますか) - Add-in with Unified Manifest
注:

このプレビューでは、アドイン名は 30 文字を超えることはできません。

ウィザードを完了すると、ジェネレーターによってプロジェクトが作成されて、サポートしているノードコンポーネントがインストールされます。

注:

バージョン 20.0.0 以降 Node.js 使用している場合は、ジェネレーターがインストールを実行するときに、サポートされていないエンジンがあることを示す警告が表示されることがあります。この問題の修正に取り組んでいます。その間、警告は生成するジェネレーターまたはプロジェクトに影響しないため、無視できます。

ヒント

アドインプロジェクトの作成後に Yeoman ジェネレーターが提供する次の手順ガイダンスは無視できます。この記事中の詳しい手順は、このチュートリアルを完了するために必要なすべてのガイダンスを提供します。
Web アプリケーションプロジェクトのルートフォルダーに移動します。
```
cd "Add-in with Unified Manifest"
```

プロジェクトを探究する

Yeomanジェネレーターで作成したアドインプロジェクトには、原型となる作業ペインアドインのサンプルコードが含まれています。

プロジェクトのルートディレクトリにある ./manifest/manifest.json ファイルで、アドインの機能と設定を定義します。
./src/taskpane/taskpane.htmlファイルには、作業ペイン用のHTMLマークアップが含まれています。
./src/taskpane/taskpane.cssファイルには、作業ペインのコンテンツに適用されるCSSが含まれています。
./src/taskpane/taskpane.ts ファイルには、Office JavaScript ライブラリを呼び出して、作業ウィンドウと Outlook の間の対話を容易にするコードが含まれています。
./src/command/command.html ファイルは、ビルド時に WebPack によって編集され、command.ts ファイルからトランスパイルされた JavaScript ファイルを読み込む HTML <script> タグが挿入されます。
./src/command/command.ts ファイルには、最初はほとんどコードが含まれていません。この記事の後半で、Office JavaScript ライブラリを呼び出し、カスタムリボンボタンが選択されたときに実行されるコードを追加します。

コードを更新する

VS Codeまたは任意のコードエディターでプロジェクトを開きます。

ヒント

Windows では、コマンドラインからプロジェクトのルートディレクトリに移動し、code . を入力して VS Code でそのフォルダーを開くことができます。

ファイル ./src/taskpane/taskpane.html を開き、メイン>要素全体< (body> 要素内) を<次のマークアップに置き換えます。この新しいマークアップは、./src/taskpane/taskpane.ts のスクリプトがデータを書き込む場所にラベルを追加します。

<main id="app-body" class="ms-welcome__main" style="display: none;">
    <h2 class="ms-font-xl"> Discover what Office Add-ins can do for you today! </h2>
    <p><label id="item-subject"></label></p>
    <div role="button" id="run" class="ms-welcome__action ms-Button ms-Button--hero ms-font-xl">
        <span class="ms-Button-label">Run</span>
    </div>
</main>

試してみる

注:

Office アドインでは、開発中でも HTTP ではなく HTTPS を使用する必要があります。次のいずれかのコマンドを実行した後に証明書のインストールを求められた場合は、Yeoman ジェネレーターが提供する証明書をインストールするプロンプトに同意します。変更を行うには、管理者としてコマンドプロンプトまたはターミナルを実行する必要がある場合もあります。

管理者としてコマンドプロンプトを開き、プロジェクトのルートディレクトリで次のコマンドを実行します。このコマンドを実行すると、ローカル Web サーバーが起動し、アドインがサイドロードされます。
```
npm start
```
注:

初めてコンピューターにアドインを作成した場合、または 1 か月を超えて初めてアドインを作成した場合は、セキュリティ証明書のインストールを求めるメッセージが表示されます。
Outlook でクラシックリボンを使用します。これらの手順の残りの部分は、これを前提としています。
閲覧ウィンドウでメッセージを表示するか、独自のウィンドウでメッセージを開きます。 Contoso アドインという名前の新しいコントロールグループが Outlook の [ホーム] タブ (または、新しいウィンドウでメッセージを開いた場合は [メッセージ] タブ) に表示されます。グループには、[作業ウィンドウの表示] という名前のボタンと [アクションの実行] という名前のボタンがあります。
[アクションの実行] ボタンを選択します。コマンドを実行して、メッセージヘッダーの下部、メッセージ本文のすぐ上に小さな情報通知を生成します。
WebView Stop On Load ダイアログボックスでプロンプトが表示されたら、[OK] を選択します。

注:

[キャンセル] を選択すると、このアドインのインスタンスの実行中はダイアログが表示されなくなります。ただし、アドインを再起動すると、ダイアログはもう一度表示されます。
アドインの作業ウィンドウを開くには、[作業ウィンドウの表示] を選択します。

注:

作業ウィンドウで、「このアドインを localhost から開くことはできません」というエラーが表示される場合は、「トラブルシューティングの記事」に記載されている手順に従ってください。
WebView Stop On Load ダイアログボックスでプロンプトが表示されたら、OK を選択します。

注:

[キャンセル] を選択すると、このアドインのインスタンスの実行中はダイアログが表示されなくなります。ただし、アドインを再起動すると、ダイアログはもう一度表示されます。
作業ウィンドウの一番下までスクロールし、[実行] リンクを選択して、メッセージの件名を作業ウィンドウにコピーします。
次のコマンドでデバッグセッションを終了します。
```
npm stop
```
重要

Web サーバーウィンドウを閉じても、Web サーバーが確実にシャットダウンされるわけではありません。適切にシャットダウンされていない場合、プロジェクトを変更して再実行するときに問題が発生します。
Outlook のすべてのインスタンスを閉じます。

リボンにカスタムボタンを追加する

メッセージ本文にテキストを挿入するカスタムボタンをリボンに追加します。

VS Code またはお好みのコードエディターでプロジェクトを開きます。

ヒント

Windows では、コマンドラインからプロジェクトのルートディレクトリに移動し、code . を入力して VS Code でそのフォルダーを開くことができます。

コードエディターで、ファイル ./src/command/command.ts を開き、ファイルの最後に次のコードを追加します。この関数は、メッセージ本文のカーソルポイントに Hello World を挿入します。

function insertHelloWorld(event: Office.AddinCommands.Event) {
    Office.context.mailbox.item.body.setSelectedDataAsync("Hello World", {coercionType: Office.CoercionType.Text});

    // Be sure to indicate when the add-in command function is complete
    event.completed();
}

// Register the function with Office
Office.actions.associate("insertHelloWorld", insertHelloWorld);

ファイル ./manifest/manifest.json を開きます。

注:

ネストされた JSON プロパティを参照する場合、この記事ではドット表記を使用します。配列内のアイテムが参照される場合、アイテムの括弧で囲まれたゼロベースの番号が使用されます。
メッセージに書き込むには、アドインのアクセス許可を上げる必要があります。プロパティ authorization.permissions.resourceSpecific[0].name までスクロールし、値を MailboxItem.ReadWrite.User に変更します。
アドインコマンドは、作業ウィンドウを開く代わりにコードを実行する場合、作業ウィンドウコードが実行される埋め込み Web ビューとは別のランタイムでコードを実行する必要があります。したがって、マニフェストは追加のランタイムを指定する必要があります。プロパティ extension.runtimes までスクロールし、次のオブジェクトを runtimes 配列に追加します。既に配列にあるオブジェクトの後には、必ずコンマを入れてください。このマークアップについて、次の情報にご注意ください。
- actions[0].id プロパティの値は、commands.ts ファイルに追加した関数の名前 (この場合は insertHelloWorld) と完全に同じである必要があります。後の手順で、この ID でアイテムを参照します。
```
{
    "id": "ComposeCommandsRuntime",
    "type": "general",
    "code": {
        "page": "https://localhost:3000/commands.html",
        "script": "https://localhost:3000/commands.js"
    },
    "lifetime": "short",
    "actions": [
        {
            "id": "insertHelloWorld",
            "type": "executeFunction",
            "displayName": "insertHelloWorld"
        }
    ]
}
```

[作業ウィンドウの表示] ボタンは、ユーザーがメールを読んでいるときに表示されますが、テキストを追加するためのボタンは、ユーザーが新しいメールを作成しているとき (または返信しているとき) にのみ表示されます。したがって、マニフェストは新しいリボンオブジェクトを指定する必要があります。プロパティ extension.ribbons までスクロールし、次のオブジェクトを ribbons 配列に追加します。既に配列にあるオブジェクトの後には、必ずコンマを入れてください。この JSON については、次の点に注意してください。

contexts 配列の唯一の値は "mailCompose" であるため、ボタンは作成 (または返信) ウィンドウに表示されますが、[作業ウィンドウの表示] および [アクションの実行] ボタンが表示されるメッセージ読み取りウィンドウには表示されません。この値を、値が ["mailRead"] である既存のリボンオブジェクトの contexts 配列と比較します。
tabs[0].groups[0].controls[0].actionId の値は、前の手順で作成したランタイムオブジェクトの actions[0].id プロパティの値と完全に同じである必要があります。

{
    "contexts": ["mailCompose"],
    "tabs": [
        {
            "builtInTabId": "TabDefault",
            "groups": [
                {
                    "id": "msgWriteGroup",
                    "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": "HelloWorldButton",
                            "type": "button",
                            "label": "Insert text",
                            "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": "Insert text",
                                "description": "Inserts some text."
                            },
                            "actionId": "insertHelloWorld"
                        }                  
                    ]
                }
            ]
        }
    ]
}

更新されたアドインを試してください

管理者としてコマンドプロンプトを開き、プロジェクトのルートディレクトリで次のコマンドを実行します。
```
npm start
```
Outlook で、新しいメッセージウィンドウを開きます (または既存のメッセージに返信します)。 Contoso アドインという名前の新しいコントロールグループが Outlook の [メッセージ] タブに表示されます。グループには、[テキストの挿入] という名前のボタンがあります。
メッセージ本文の任意の場所にカーソルを置き、[テキストの挿入] ボタンを選択します。
WebView Stop On Load ダイアログボックスでプロンプトが表示されたら、[OK] を選択します。

注:

[キャンセル] を選択すると、このアドインのインスタンスの実行中はダイアログが表示されなくなります。ただし、アドインを再起動すると、ダイアログはもう一度表示されます。

"Hello World" という語句がカーソルに挿入されます。
次のコマンドでデバッグセッションを終了します。
```
npm stop
```

トラブルシューティング

「開発環境のセットアップ」の手順に従って、環境が Office 開発の準備ができていることを確認します。
Yo Office が実行する自動 npm install ステップが失敗する可能性があります。を実行 npm startしようとしたときにエラーが表示された場合は、コマンドプロンプトで新しく作成されたプロジェクトフォルダーに移動し、を手動で実行 npm installします。 Yo Office の詳細については、「 Yeoman ジェネレーターを使用して Office アドインプロジェクトを作成する」を参照してください。
アドインにエラーが表示された場合 (たとえば、"このアドインを開始できませんでした。このダイアログを閉じて問題を無視するか、[再起動] をクリックしてやり直してください。)F5 キーを押すか、[デバッグ] [Visual Studio でのデバッグ>の開始] の順に選択すると、その他のデバッグオプションについては、「Visual Studio での Office アドインのデバッグ」を参照してください。
一部のサンプルコードでは、ES6 JavaScript を使用しています。これは、Trident (インターネットエクスプローラー 11) ブラウザーエンジンを使用する古いバージョンの Office と互換性がありません。アドインでこれらのプラットフォームをサポートする方法については、「古い Microsoft Webview と Office バージョンをサポートする」を参照してください。開発に使用する Microsoft 365 サブスクリプションがまだない場合は、Microsoft 365 開発者プログラムを通じてMicrosoft 365 E5開発者サブスクリプションを受ける資格があります。詳細については、FAQ を参照してください。または、 1 か月間の無料試用版にサインアップするか、 Microsoft 365 プランを購入することもできます。

Microsoft 365 用の統合マニフェストを使用して Outlook アドインを構築する (プレビュー)

アドインを作成する

前提条件

アドインプロジェクトの作成

プロジェクトを探究する

コードを更新する

試してみる

リボンにカスタムボタンを追加する

更新されたアドインを試してください

トラブルシューティング

関連項目

フィードバック

その他のリソース

Microsoft 365 用の統合マニフェストを使用して Outlook アドインを構築する (プレビュー)

アドインを作成する

前提条件

アドイン プロジェクトの作成

プロジェクトを探究する

コードを更新する

試してみる

リボンにカスタム ボタンを追加する

更新されたアドインを試してください

トラブルシューティング

関連項目

フィードバック

その他のリソース

アドインプロジェクトの作成

リボンにカスタムボタンを追加する