コンテンツ アドインと作業ウィンドウ アドインでの API 使用についてアクセス許可を要求するRequesting permissions for API use in content and task pane add-ins

この記事では、アドインの機能のために必要となる JavaScript API アクセスのレベルを指定するために、コンテンツ アドインまたは作業ウィンドウ アドインのマニフェストで宣言できるさまざまなアクセス許可レベルについて説明します。This article describes the different permission levels that you can declare in your content or task pane add-in's manifest to specify the level of JavaScript API access your add-in requires for its features.

アクセス許可モデルPermissions model

5 レベルの JavaScript API アクセス許可モデルは、コンテンツ アドインと作業ウィンドウ アドインでのユーザーのプライバシーとセキュリティの基礎となります。図 1 に、アドイン マニフェストで宣言できる 5 レベルの API アクセス許可を示します。A five-level JavaScript API access-permissions model provides the basis for privacy and security for users of your content and task pane add-ins. Figure 1 shows the five levels of API permissions you can declare in your add-in's manifest.

図 1. コンテンツ アドインと作業ウィンドウ アドインの 5 レベル アクセス許可モデルFigure 1. The five-level permission model for content and task pane add-ins

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

これらのアクセス許可は、ユーザーがアドインを挿入してアクティブ化 (信頼) したときに、アドイン ランタイムがコンテンツ アドインまたはタスク ウィンドウ アドインに使用を許可する API のサブセットを指定します。コンテンツ アドインまたは作業ウィンドウ アドインに必要なアクセス許可レベルを宣言するには、アドインのマニフェストの Permissions 要素に、いずれかのアクセス許可テキスト値を指定します。以下の例では、ドキュメントに書き込みができる (しかし読み取りはできない) メソッドだけを許可する、 WriteDocument アクセス許可を要求します。These permissions specify the subset of the API that the add-in runtime will allow your content or task pane add-in to use when a user inserts, and then activates (trusts) your add-in. To declare the permission level your content or task pane add-in requires, specify one of the permission text values in the Permissions element of your add-in's manifest. The following example requests the WriteDocument permission, which will allow only methods that can write to (but not read) the document.

<Permissions>WriteDocument</Permissions>

ベスト プラクティスとしては、最小限の特権_の原則に基づいてアクセス許可を要求するべきです。つまり、アドインが正しく機能するために必要な最小限の API サブセットにのみアクセスする許可を要求します。たとえば、ユーザーのドキュメントのデータさえ読み込めばアドインが正しく機能する場合、ReadDocument 以外のアクセス許可を要求しません。As a best practice, you should request permissions based on the principle of _least privilege. That is, you should request permission to access only the minimum subset of the API that your add-in requires to function correctly. For example, if your add-in needs only to read data in a user's document for its features, you should request no more than the ReadDocument permission.

各レベルのアクセス許可で使用可能になる JavaScript API のサブセットを次の表に示します。The following table describes the subset of the JavaScript API that is enabled by each permission level.

アクセス許可Permission 使用可能な API のサブセットEnabled subset of the API
制限されていますRestricted Settings オブジェクトのメソッドと Document.getActiveViewAsync メソッド。これは、コンテンツ アドインまたは作業ウィンドウ アドインで要求することができる、最小のアクセス許可レベルです。The methods of the Settings object, and the Document.getActiveViewAsync method.This is the minimum permission level that can be requested by a content or task pane add-in.
ReadDocumentReadDocument Restricted アクセス許可によって使用可能となる API に加えて、ドキュメントの読み取りとバインディングの管理に必要な API メンバーへのアクセス権を追加します。これには以下の使用が含まれます。In addition to the API allowed by the Restricted permission, adds access to the API members necessary to read the document and manage bindings.This includes the use of:
  • 選択されたテキスト、HTML (Word のみ)、または表形式のデータは取得するが、ドキュメント内のすべてのデータを含んでいる基礎となる Open Office XML (OOXML) コードは取得しない、Document.getSelectedDataAsync メソッド。The Document.getSelectedDataAsync method to get the selected text, HTML (Word only), or tabular data, but not the underlying Open Office XML (OOXML) code that contains all of the data in the document.

  • ドキュメント内のすべてのテキストを取得するが、基礎となるドキュメントの OOXML バイナリ コピーは取得しない、Document.getFileAsync メソッド。The Document.getFileAsync method to get all of the text in the document, but not the underlying OOXML binary copy of the document.

  • ドキュメント内のバインドされたデータを読み取るための Binding.getDataAsync メソッド。The Binding.getDataAsync method for reading bound data in the document.

  • ドキュメントでバインディングを作成するための Bindings オブジェクトの addFromNamedItemAsyncaddFromPromptAsyncaddFromSelectionAsync の各メソッド。The addFromNamedItemAsync, addFromPromptAsync, addFromSelectionAsync methods of the Bindings object for creating bindings in the document.

  • ドキュメントでバインディングにアクセスしてそれを削除するための Bindings オブジェクトの getAllAsyncgetByIdAsync、および releaseByIdAsync の各メソッド。The getAllAsync, getByIdAsync, and releaseByIdAsync methods of the Bindings object for accessing and removing bindings in the document.

  • ドキュメントの URL など、ドキュメント ファイルのプロパティにアクセスするための Document.getFilePropertiesAsync メソッド。The Document.getFilePropertiesAsync method to access document file properties, such as the URL of the document.

  • ドキュメント内で名前付きオブジェクトや場所に移動するための Document.goToByIdAsync メソッド。The Document.goToByIdAsync method to navigate to named objects and locations in the document.

  • Project 用の作業ウィンドウ アドインについては、ProjectDocument オブジェクトのすべての "get" メソッド。For task pane add-ins for Project, all of the "get" methods of the ProjectDocument object.

ReadAllDocumentReadAllDocument Restricted および ReadDocument アクセス許可によって使用可能になる API に加えて、ドキュメント データに対する以下の追加のアクセスも許可されます。In addition to the API allowed by the Restricted and ReadDocument permissions, allows the following additional access to document data:
  • Document.getSelectedDataAsync メソッドおよび Document.getFileAsync メソッドは、ドキュメント (テキストだけでなく、書式設定、リンク、埋め込まれたグラフィックス、コメント、リビジョンなど) の基礎となる OOXML コードにアクセスできます。The Document.getSelectedDataAsync and Document.getFileAsync methods can access the underlying OOXML code of the document (which in addition to the text may include formatting, links, embedded graphics, comments, revisions, and so forth).

WriteDocumentWriteDocument Restricted アクセス許可によって使用可能になる API に加えて、以下の API メンバーに対するアクセス権も追加されます。In addition to the API allowed by the Restricted permission, adds access to the following API members:
ReadWriteDocumentReadWriteDocument RestrictedReadDocumentReadAllDocument、および WriteDocument アクセス許可によって使用可能になる API に加えて、イベントを購読するメソッドなど、コンテンツ アドインと作業ウィンドウ アドインによってサポートされる他のすべての API へのアクセスを含みます。これらの追加の API メンバーにアクセスするには ReadWriteDocument アクセス許可を宣言する必要があります。In addition to the API allowed by the Restricted, ReadDocument, ReadAllDocument, and WriteDocument permissions, includes access to all remaining API supported by content and task pane add-ins, including methods for subscribing to events.You must declare the ReadWriteDocument permission to access these additional API members:

関連項目See also