次の方法で共有

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

  • [アーティクル]

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

重要

この記事は、Outlook 以外のアドインにのみ適用されます。Outlook アドインのアクセス許可レベルについては、「 Outlook のアクセス許可モデル」を参照してください。

アクセス許可モデル

5 レベルの JavaScript API アクセス許可モデルは、アドインのユーザーのプライバシーとセキュリティの基礎を提供します。次の図は、アドインのマニフェストで宣言できる API アクセス許可の 5 つのレベルを示しています。

アドインのアクセス許可のレベル。

これらのアクセス許可は、アドイン ランタイム がアドインを挿入するときに使用できる API のサブセットを指定し、アドインをアクティブ化 (信頼) します。 アドインで必要なアクセス許可レベルを宣言するには、マニフェストでいずれかのアクセス許可値を指定します。 マークアップはマニフェストの種類によって異なります。

  • Microsoft 365 の統合マニフェスト: "authorization.permissions.resourceSpecific" プロパティを使用します。 次の例では、 ドキュメントの書き込み アクセス許可を要求します。これにより、ドキュメントへの書き込み (読み取りはできない) メソッドのみが許可されます。

    "authorization": {
    "permissions": {
      "resourceSpecific": [
        ...
        {
          "name": "Document.Write.User",
          "type": "Delegated"
        },
      ]
    }  
},

    注:

    Microsoft 365 の統合マニフェストは、運用環境の Outlook アドインで使用できます。Excel、PowerPoint、Word アドインのプレビューとしてのみ使用できます。

  • アドインのみのマニフェスト: マニフェストの Permissions 要素を使用します。 次の例では、 ドキュメントの書き込み アクセス許可を要求します。これにより、ドキュメントへの書き込み (読み取りはできない) メソッドのみが許可されます。

    <Permissions>WriteDocument</Permissions>

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

次の表では、各アクセス許可レベルで有効になっている 共通およびアプリケーション固有の JavaScript API の サブセットについて説明します。

アクセス許可の正規名 アドインのみのマニフェスト名 統合マニフェスト名 アプリケーション固有 API の有効なサブセット 共通 API の有効なサブセット
制限 Restricted Document.Restricted.User なし Settings オブジェクトのメソッドと Document.getActiveViewAsync メソッド。 これは、アドインから要求できる最小限のアクセス許可レベルです。
ドキュメントの読み取り ReadDocument Document.Read.User ドキュメントまたはそのプロパティを読み取るすべておよび唯一の API。 制限付きアクセス許可によって許可される API に加えて、ドキュメントの読み取りとバインドの管理に必要な API メンバーへのアクセスを追加します。 これには以下の使用が含まれます。
  • 選択されたテキスト、HTML (Word のみ)、または表形式のデータは取得するが、ドキュメント内のすべてのデータを含んでいる基礎となる Open Office XML (OOXML) コードは取得しない、Document.getSelectedDataAsync メソッド。
  • Document.getFileAsync メソッドを使用して、ドキュメント内のすべてのテキストを取得しますが、ドキュメントの基になる OOXML バイナリ コピーは取得しません。
  • ドキュメント内のバインドされたデータを読み取るための Binding.getDataAsync メソッド。
  • ドキュメント内にバインドを作成するための Bindings オブジェクトの addFromNamedItemAsync、 addFromPromptAsync、 addFromSelectionAsync メソッド。
  • ドキュメントでバインディングにアクセスしてそれを削除するための Bindings オブジェクトの getAllAsync、getByIdAsync、および releaseByIdAsync の各メソッド。
  • ドキュメントの URL など、ドキュメント ファイルのプロパティにアクセスするための Document.getFilePropertiesAsync メソッド。

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

  • Project 用の作業ウィンドウ アドインについては、ProjectDocument オブジェクトのすべての "get" メソッド。
すべてのドキュメントを読み取る ReadAllDocument Document.ReadAll.User ドキュメントの 読み取りと同じです。 ドキュメントの制限付きアクセス許可と読み取りアクセス許可によって許可される API に加えて、ドキュメント データへの次の追加アクセスが許可されます。

  • Document.getSelectedDataAsync メソッドおよび Document.getFileAsync メソッドは、ドキュメント (テキストだけでなく、書式設定、リンク、埋め込まれたグラフィックス、コメント、リビジョンなど) の基礎となる OOXML コードにアクセスできます。
ドキュメントの書き込み WriteDocument Document.Write.User ドキュメントまたはそのプロパティに書き込むすべておよび唯一の API。 制限付きアクセス許可で許可される API に加えて、次の API メンバーへのアクセスを追加します。
ドキュメントの読み取り/書き込み ReadWriteDocument Document.ReadWrite.User イベントをサブスクライブするものも含め、すべての Application-specfic API。 制限付きドキュメント、読み取りドキュメント、すべてのドキュメントの読み取り、およびドキュメントの書き込みアクセス許可によって許可される API に加えて、イベントをサブスクライブするためのメソッドを含む、アドインでサポートされている残りの API へのアクセスが含まれます。 これらの追加の API メンバーにアクセスするには 、ドキュメントの読み取り/書き込み アクセス許可を宣言する必要があります。

関連項目