アドインでの API 使用についてアクセス許可を要求する

  • [アーティクル]

この記事では、アドインの機能のために必要となる JavaScript API アクセスのレベルを指定するために、コンテンツ アドインまたは作業ウィンドウ アドインのマニフェストで宣言できるさまざまなアクセス許可レベルについて説明します。

注:

メール (Outlook) アドインのアクセス許可レベルについては、「 Outlook のアクセス許可モデル」を参照してください。

アクセス許可モデル

5 レベルの JavaScript API アクセス許可モデルは、コンテンツ アドインと作業ウィンドウ アドインでのユーザーのプライバシーとセキュリティの基礎となります。図 1 に、アドイン マニフェストで宣言できる 5 レベルの API アクセス許可を示します。

図 1. コンテンツ アドインと作業ウィンドウ アドインの 5 レベル アクセス許可モデル

作業ウィンドウ アプリのアクセス許可のレベル。

これらのアクセス許可は、アドイン ランタイム がコンテンツまたは作業ウィンドウ アドインがユーザーの挿入時に使用できるようにする API のサブセットを指定し、アドインをアクティブ化 (信頼) します。 コンテンツ アドインまたは作業ウィンドウ アドインに必要なアクセス許可レベルを宣言するには、アドインのマニフェストの Permissions 要素に、いずれかのアクセス許可テキスト値を指定します。 以下の例では、ドキュメントに書き込みができる (しかし読み取りはできない) メソッドだけを許可する、 WriteDocument アクセス許可を要求します。

<Permissions>WriteDocument</Permissions>

ベスト プラクティスとして、最小特権の原則に基づいてアクセス許可を要求します。 つまり、アドインが正しく機能するために必要な最小限の API サブセットにのみアクセスする許可を要求します。 たとえば、ユーザーのドキュメントのデータさえ読み込めばアドインが正しく機能する場合、ReadDocument 以外のアクセス許可を要求しません。

各レベルのアクセス許可で使用可能になる JavaScript API のサブセットを次の表に示します。

アクセス許可 使用可能な API のサブセット
制限付き Settings オブジェクトのメソッドと Document.getActiveViewAsync メソッド。 これは、コンテンツ アドインまたは作業ウィンドウ アドインで要求することができる、最小のアクセス許可レベルです。
ReadDocument Restricted アクセス許可によって使用可能となる API に加えて、ドキュメントの読み取りとバインディングの管理に必要な API メンバーへのアクセス権を追加します。 これには以下の使用が含まれます。

  • 選択されたテキスト、HTML (Word のみ)、または表形式のデータは取得するが、ドキュメント内のすべてのデータを含んでいる基礎となる Open Office XML (OOXML) コードは取得しない、Document.getSelectedDataAsync メソッド。

  • ドキュメント内のすべてのテキストを取得するが、基礎となるドキュメントの OOXML バイナリ コピーは取得しない、Document.getFileAsync メソッド。

  • ドキュメント内のバインドされたデータを読み取るための Binding.getDataAsync メソッド。

  • ドキュメントでバインディングを作成するための Bindings オブジェクトの addFromNamedItemAsync、addFromPromptAsync、addFromSelectionAsync の各メソッド。

  • ドキュメントでバインディングにアクセスしてそれを削除するための Bindings オブジェクトの getAllAsync、getByIdAsync、および releaseByIdAsync の各メソッド。

  • ドキュメントの URL など、ドキュメント ファイルのプロパティにアクセスするための Document.getFilePropertiesAsync メソッド。

  • ドキュメント内で名前付きオブジェクトや場所に移動するための Document.goToByIdAsync メソッド。

  • Project 用の作業ウィンドウ アドインについては、ProjectDocument オブジェクトのすべての "get" メソッド。

ReadAllDocument 制限付きアクセス許可と ReadDocument アクセス許可によって許可される API に加えて、ドキュメント データへの次の追加アクセスが許可されます。

  • Document.getSelectedDataAsync メソッドおよび Document.getFileAsync メソッドは、ドキュメント (テキストだけでなく、書式設定、リンク、埋め込まれたグラフィックス、コメント、リビジョンなど) の基礎となる OOXML コードにアクセスできます。
WriteDocument 制限付きアクセス許可によって許可される API に加えて、次の API メンバーへのアクセスを追加します。
ReadWriteDocument Restricted、ReadDocument、ReadAllDocument、および WriteDocument アクセス許可によって使用可能になる API に加えて、イベントを購読するメソッドなど、コンテンツ アドインと作業ウィンドウ アドインによってサポートされる他のすべての API へのアクセスを含みます。 これらの追加の API メンバーにアクセスするには ReadWriteDocument アクセス許可を宣言する必要があります。

関連項目