Outlook アドインの API

Outlook アドインでメッセージ データの読み取り、アイテムの更新、外部サービスの呼び出しを行う前に、Office.js ライブラリ、宣言された要件セット、適切なアクセス許可への参照が必要です。 この記事では、これらの各構成要素を構成する方法と 、Mailbox オブジェクトを使用して Outlook API にアクセスする方法について説明します。

Office.js ライブラリ

Outlook アドイン API と対話するには、Office.js で JavaScript API を使用する必要があります。 ライブラリのコンテンツ配信ネットワーク (CDN) が https://appsforoffice.microsoft.com/lib/1/hosted/Office.js。 Microsoft Marketplace に送信されるアドインは、この CDN によって Office.js を参照する必要があります。ローカル参照を使用することはできません。

アドインの UI を実行する Web ページ (.html、.aspx、.php のファイル) の <head> タグの中の <script> タグの中で CDN を参照します。

<script src="https://appsforoffice.microsoft.com/lib/1/hosted/Office.js" type="text/javascript"></script>

新しい API が追加されても、Office.js への URL は同じままになります。 URL のバージョンは、既存の API の動作を中断した場合にのみ変更します。

重要

Office クライアント アプリケーション用のアドインを開発するときは、ページの <head> セクション内から Office JavaScript API を参照してください。 これにより、あらゆる body 要素の前に API が完全に初期化されます。

要件セット

すべての Outlook API は 、メールボックス要件セットに属しています。 Mailbox の要件セットにはバージョンがあり、リリースされる新しい API の各セットは、新しいバージョンのセットに属しています。 すべての Outlook クライアントがリリース時に最新の API セットをサポートするわけではありませんが、Outlook クライアントが要件セットのサポートを宣言した場合、その要件セット内のすべての API がサポートされます。

どの Outlook クライアントにアドインを表示するかを制御するには、最小の要件セットのバージョンをマニフェストで指定します。 たとえば、要件セットバージョン 1.3 を指定した場合、最小バージョン 1.3 をサポートしていない Outlook クライアントにはアドインは表示されません。

要件セットを指定しても、そのバージョンの API にアドインを限定することにはなりません。 要件セット v1.1 を指定しているアドインが、v1.3 をサポートする Outlook クライアントで実行されると、そのアドインは v1.3 の API を使用できます。 要件セットでは、どの Outlook クライアントにアドインを表示するかのみを制御します。

マニフェストで指定されたものより大きい要件セットから API の可用性をチェックするには、標準の JavaScript を使用できます。 たとえば、次のコードでは、メールボックス要件セット 1.8 が必要な getItemIdAsyncを呼び出す前にチェックします。

// Check whether a Mailbox 1.8 API is available before calling it.
if (Office.context.mailbox.item.getItemIdAsync) {
    Office.context.mailbox.item.getItemIdAsync((result) => {
        if (result.status === Office.AsyncResultStatus.Succeeded) {
            console.log("Item ID:", result.value);
        }
    });
}

注:

このような確認は、マニフェストで指定された要件セットのバージョンに存在する API には必要ありません。

それなしではアドインの機能が機能しないような、シナリオに絶対必要な API のセットをサポートする最低限要件セットを指定します。 マニフェストで要件セットを指定します。 マークアップは、使用しているマニフェストによって異なります。

  • アドインのみのマニフェスト: <Requirements> 要素を使用します。 <Requirements>の<Methods>子要素は Outlook アドインではサポートされていないため、特定のメソッドのサポートを宣言することはできません。
  • Microsoft 365 の統合マニフェスト: "extensions.capabilities" プロパティを使用します。

詳細については、「 Office アドイン マニフェスト」および 「Outlook API 要件セットについて」を参照してください。

アクセス許可

アドインには、そのアドインが必要とする API を使用するための適切なアクセス許可が必要になります。 一般的には、アドインに必要な最低限のアクセス許可を指定する必要があります。

アクセス許可には、制限付き、読み取り項目、読み取り/書き込みアイテム、および読み取り/書き込みメールボックスの 4 つのレベルがあります。 詳細については、「Outlook アドインのアクセス許可モデルを理解する」を参照してください。

Mailbox オブジェクト

Outlook アドインでは、主に Mailbox オブジェクトにより公開されている API のサブセットを使用します。 作成モードまたは読み取りモードの Item オブジェクトなど、Outlook アドインで使用するオブジェクトとメンバーにアクセスするには、Context オブジェクトの mailbox プロパティを使用して Mailbox オブジェクトにアクセスします。 以下にコードの例を示します。

// Access the Item object.
const item = Office.context.mailbox.item;

重要

メッセージで Office.context.mailbox.item を呼び出すときは、Outlook クライアントの閲覧ウィンドウを有効にする必要があることに注意してください。 閲覧ウィンドウを構成する方法のガイダンスについては、「閲覧ウィンドウを 使用してメッセージをプレビューするように構成する」を参照してください。

さらに、Outlook アドインでは、次のオブジェクトを使用できます。

  • Office オブジェクト: 初期化に使用します。

  • Context オブジェクト: コンテンツおよび表示言語のプロパティへのアクセスに使用します。

Outlook アドインでの JavaScript の使用については、「 Outlook アドイン」を参照してください。Outlook JavaScript API を調べるには、 Outlook API リファレンス ページを参照してください。

関連項目

  • Last updated on