コンテンツ アドインと作業ウィンドウ アドインでの API 使用についてアクセス許可を要求する

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

アクセス許可モデル

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

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

作業ウィンドウ アプリの権限レベル

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

<Permissions>WriteDocument</Permissions>

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

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

アクセス許可 使用可能な API のサブセット
Restricted Settings オブジェクトのメソッドと Document.getActiveViewAsync メソッド。これは、コンテンツ アドインまたは作業ウィンドウ アドインで要求することができる、最小のアクセス許可レベルです。
ReadDocument Restricted アクセス許可によって使用可能となる API に加えて、ドキュメントの読み取りとバインディングの管理に必要な API メンバーへのアクセス権を追加します。これには以下の使用が含まれます。
  • 選択されたテキスト、HTML (Word のみ)、または表形式のデータは取得するが、ドキュメント内のすべてのデータを含んでいる基礎となる Open Office XML (OOXML) コードは取得しない、Document.getSelectedDataAsync メソッド。

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

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

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

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

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

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

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

ReadAllDocument Restricted および ReadDocument アクセス許可によって使用可能になる API に加えて、ドキュメント データに対する以下の追加のアクセスも許可されます。
  • Document.getSelectedDataAsync メソッドおよび Document.getFileAsync メソッドは、ドキュメント (テキストだけでなく、書式設定、リンク、埋め込まれたグラフィックス、コメント、リビジョンなど) の基礎となる OOXML コードにアクセスできます。

WriteDocument Restricted アクセス許可によって使用可能になる API に加えて、以下の API メンバーに対するアクセス権も追加されます。
ReadWriteDocument RestrictedReadDocumentReadAllDocument、および WriteDocument アクセス許可によって使用可能になる API に加えて、イベントを購読するメソッドなど、コンテンツ アドインと作業ウィンドウ アドインによってサポートされる他のすべての API へのアクセスを含みます。これらの追加の API メンバーにアクセスするには ReadWriteDocument アクセス許可を宣言する必要があります。

関連項目