Microsoft 365 の統合マニフェストで Office アドインの要件を指定する

[アーティクル]
04/12/2024

Microsoft 365 の統合マニフェストには、いくつかの "要件" プロパティがあります。 extensions.requirements プロパティは、アドインをインストールできる Office アプリケーションとバージョンを制御します。その他の "要件" プロパティは、特定の Office アプリケーションまたはバージョンでアドインの一部の機能を選択的に抑制するために使用されます。これらの機能は不要またはサポートされていません。詳細については、「フィルター機能」を参照してください。

extensions.requirements

"extensions.requirements" プロパティは、Microsoft 365 アドインのスコープ、フォームファクター、要件セットを指定します。Microsoft 365 バージョンで指定された要件がサポートされていない場合、拡張機能はインストールできません。ユーザーは、アドインを検索してインストールするために Office UI に表示されません。いくつかの例:

"requirements.capabilities.name" プロパティが "Mailbox" に設定され、"requirements.capabilities.minVersion" が "1.10" に設定されている場合、アドインは、バージョン 1.9 より大きい メールボックス 要件セットをサポートしていない古いバージョンの Office ではインストールできません。
"requirements.scopes" が "mail" に設定されている場合、アドインは Outlook にのみインストールできます。
"requirements.formFactors" が "desktop" のみに設定されている場合、アドインはモバイルデバイスで実行されている Office にインストールできません。

複数の機能オブジェクトを持つことができます。次の例は、モバイルデバイスではなく、2 つの異なる要件セットをサポートする Office のバージョンでのみアドインをインストールできるようにする方法を示しています。

"extensions": [
    ...
    "requirements": {
        "capabilities": [
            {
                "name": "Mailbox",
                "minVersion": "1.10"
            },
            {
                "name": "DialogAPI",
                "minVersion": "1.2"
            }
        ],
        "formFactors": [
            "desktop"
        ]
    }
]

フィルター機能

"拡張機能" の子孫オブジェクトの "requirements" プロパティは、アドインのインストールを引き続き許可しながら、アドインの一部の機能をブロックするために使用されます。このフィルター処理の実装は、インストール元 (AppSource や Microsoft 365 管理 Center など) で行われます。 Office のバージョンでこの機能に指定された要件がサポートされていない場合、その機能の JSON ノードは、Office アプリケーションにインストールされる前にマニフェストから削除されます。

extensions.alternates.requirements

"extensions.alternates" プロパティを使用すると、アドイン開発者は次の操作を実行できます。

統合マニフェストを使用するバージョンに加えて、古い拡張プラットフォーム (COM や VSTO アドインなど) または XML マニフェストを使用して構築されたアドインのバージョンを維持します。
古いテクノロジを使用するバージョンを非表示にするか、優先します。
統合マニフェストを直接サポートしていない Office バージョンにアドインの統合マニフェストバージョンをインストールできるようにするために必要なアイコンを指定します。

注:

Microsoft 365 の統合マニフェストを使用する Office アドインは、Office on the web、新しい Outlook on Windows (プレビュー)、および Microsoft 365 サブスクリプションバージョン 2304 (ビルド 16320.00000) 以降に接続されている Office on Windows で直接サポートされます。

統合マニフェストを含むアプリパッケージが AppSource または Microsoft 365 管理センターにデプロイされると、マニフェストに有効な "alternateIcons" プロパティがある場合は、統合マニフェストから XML マニフェストが生成され、格納されます。この XML マニフェストを使用すると、Office on Mac、Office on mobile、2304 より前の Office on Windows のサブスクリプションバージョン (ビルド 16320.00000)、および永続的なバージョンの Office on Windows など、統合マニフェストを直接サポートしていないプラットフォームにアドインをインストールできます。

詳細については、「 Office アドインの統合マニフェストと XML マニフェストバージョンの両方を管理する」を参照してください。

特定の要件が満たされている場合にのみ、"hide" または "prefer" サブプロパティを選択的に適用する "extensions.alternates" の "requirements" サブプロパティ。

たとえば、(アドインをインストールするための Office UI から) 古いバージョンのアドインを非表示にしたいが、 メールボックス 1.10 要件セットをサポートする Office バージョンでのみ非表示にする必要があるとします。これを行うには、次のようなマークアップを使用します。

"extensions": [
    ...
    {
        ...
        "alternates": [
            ...
            {
                ...
                "hide": {
                    "storeOfficeAddin": {
                        "officeAddinId": "b5a2794d-4aa5-4023-a84b-c60a3cbd33d4",
                        "assetId": "WA999999999"
                    }
                },
                "requirements": {
                    "capabilities": [
                        {
                            "name": "Mailbox",
                            "minVersion": "1.10"
                        }
                    ]
                }
            }
        ]
    }
]

extensions.autoRunEvents.requirements

"extensions.autoRunEvents" プロパティは、指定したイベントに応答して指定されたコードを自動的に実行するようにアドインを構成します。 "requirements" サブプロパティは、一部のバージョンの Office でこの動作をブロックするために使用できます。

たとえば、 OnMailSend イベントに応答して Outlook アドインが自動起動するように構成されており、実行する関数のコードに Mailbox 1.13 要件セットが必要であるとします。ただし、アドインには、バージョン 1.12 のみをサポートする Office バージョンで役立つその他の機能があります。 1.12 をサポートするバージョンでアドインをインストールできるように、開発者は "extensions.requirements.capabilities" プロパティを 1.13 ではなく要件セット Mailbox 1.12 に設定できます。ただし、1.13 をサポートしていないバージョンの自動起動機能をブロックするために、開発者は メールボックス 1.13 を指定する "extensions.autoRunEvents.requirements.capabilities" プロパティを追加できます。次に例を示します。

"extensions": [
    ...
    {
        ...
        "autoRunEvents": [
            ...
            {
                ...
                "events": {
                    "type": "OnMailSend",
                    "actionId": "logOutgoingEmail",
                    "options": {
                        "sendMode": "promptUser"
                    }
                },
                "requirements": {
                    "capabilities": [
                        {
                            "name": "Mailbox",
                            "minVersion": "1.13"
                        }
                    ]
                }
            }
        ]
    }
]

extensions.ribbons.requirements

"extensions.ribbons" プロパティは、アドインのインストール時に Office アプリケーションリボンをカスタマイズするために使用されます。 "requirements" サブプロパティは、一部のバージョンの Office でのカスタマイズを防ぐために使用できます。

たとえば、Outlook アドインがリボンにカスタムボタンを追加するように構成されており、そのボタンで Mailbox 1.9 要件セットで導入されたコードを使用する関数が実行されるとします。ただし、アドインには、バージョン 1.8 のみをサポートする Office のバージョンで役立つその他の機能があります。 1.8 をサポートするバージョンでアドインをインストールできるように、開発者は "extensions.requirements.capabilities" プロパティを 1.9 ではなく要件セット Mailbox 1.8 に設定できます。ただし、1.9 をサポートしていないバージョンのリボンにカスタムボタンが表示されないようにするには、開発者は メールボックス 1.9 を指定する "extensions.ribbons.requirements.capabilities" プロパティを追加できます。次に例を示します。カスタムリボン構成の詳細については、「 Microsoft 365 用の統合マニフェストを使用してアドインコマンドを作成する」を参照してください。

"extensions": [
    ...
    {
        ...
        "ribbons": [
            ...
            {
                // Insert details of the ribbon configuration here.

                "requirements": {
                    "capabilities": [
                        {
                            "name": "Mailbox",
                            "minVersion": "1.9"
                        }
                    ]
                }
            }
        ]
    }
]

extensions.runtimes.requirements

"extensions.runtimes" プロパティは、各拡張ポイントで使用できるランタイムとアクションのセットを構成します。その使用方法の詳細については、「アドインコマンドの作成」、「作業ウィンドウのランタイムの構成」、および「関数コマンドのランタイムの構成」を参照してください。 Office アドインのランタイムの詳細については、「Office アドインのランタイム」を参照してください。

"要件" サブプロパティを使用すると、ランタイムが Office のバージョンや使用されない Office アプリケーションに含まれるのを防ぐことができます。

extensions.autoRunEvents.requirements に示されている前の例は、関数内のすべてのコードをサポートしていないバージョン (Mailbox 1.13 を必要とするコードを含む) でlogOutgoingEmail自動起動機能をブロックする方法を示しています。同じシナリオでは、"logOutgoingEmail" アクションをサポートするように構成された "ランタイム" オブジェクトが、他のアクションをサポートするように構成されていないとします。その場合、開発者は 、メールボックス 1.13 をサポートしていないバージョンではランタイムオブジェクトをブロックする必要があります。これは使用されないためです。次に例を示します。ランタイム構成の詳細については、「 Microsoft 365 用の統合マニフェストを使用してアドインコマンドを作成する」を参照してください。

"extensions": [
    ...
    {
        ...
        "runtimes": [
            ...
            {
                // Insert details of the runtime configuration here.

                "requirements": {
                    "capabilities": [
                        {
                            "name": "Mailbox",
                            "minVersion": "1.13"
                        }
                    ]
                }
            }
        ]
    }
]

同様に、 extensions.ribbons.requirements の例では、カスタムボタンにリンクされているアクションがランタイムオブジェクトで構成されている唯一のアクションである場合、リボンオブジェクトがブロックされているのと同じ状況でそのランタイムオブジェクトをブロックする必要があります。