在加载项中请求获取 API 使用权限

2025-02-14

本文介绍在外接程序清单中声明的不同权限级别，以指定外接程序对其功能所需的 JavaScript API 访问级别。

重要

本文仅适用于非 Outlook 加载项。若要了解 Outlook 外接程序的权限级别，请参阅 Outlook 权限模型。

权限模型

五级 JavaScript API 访问权限模型为加载项的用户提供了隐私和安全的基础。下图显示了可在外接程序清单中声明的五个 API 权限级别。

加载项的权限级别。

这些权限指定外接程序运行时允许外接程序在用户插入时使用的 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 的子集
限制	受限	Document.Restricted.User	None	Settings 对象的方法和 Document.getActiveViewAsync 方法。这是加载项可以请求的最低权限级别。
读取文档	ReadDocument	Document.Read.User	读取文档或其属性的所有 API 和仅 API。	除了受限制权限允许的 API 外，还可以添加对读取文档和管理绑定所需的 API 成员的访问权限。这包括对以下内容的使用： Document.getSelectedDataAsync 方法，用于获取所选文本、HTML（仅限 Word）或表格数据，但不可用于包含文档中所有数据的基础 Open Office XML (OOXML) 代码。 Document.getFileAsync 方法，用于获取文档中的所有文本，但不能获取文档的基础 OOXML 二进制副本 Binding.getDataAsync 方法，用于读取文档中的绑定数据。 Bindings 对象的 addFromNamedItemAsync、 addFromPromptAsync 和 addFromSelectionAsync 方法，用于在文档中创建绑定。 Bindings 对象的 getAllAsync、getByIdAsync 和 releaseByIdAsync 方法，用于访问和删除文档中的绑定。 Document.getFilePropertiesAsync 方法，用于访问文档文件属性，例如文档的 URL。 Document.goToByIdAsync 方法，用于导航到文档中的已命名对象和位置。对于项目的任务窗格外接程序，ProjectDocument 对象的所有"get"方法。
阅读所有文档	ReadAllDocument	Document.ReadAll.User	与阅读文档相同。	除了受限制的文档权限和读取权限允许的 API 外，还允许对文档数据进行以下附加访问。 Document.getSelectedDataAsync 和 Document.getFileAsync 方法可以访问文档（文档中除了文本，还可能包含格式、链接、嵌入图片、注释、修订等）的基础 OOXML 代码。
写入文档	WriteDocument	Document.Write.User	写入文档或其属性的所有且仅 API。	除了受限制权限允许的 API 外，还添加了对以下 API 成员的访问权限。 Document.setSelectedDataAsync 方法，用于在文档中写入用户所选内容。
可读/写文档	ReadWriteDocument	Document.ReadWrite.User	所有 Application-specfic API，包括订阅事件的 API。	除了受限制的、读取文档、读取所有文档和写入文档权限允许的 API 之外，还包括对外接程序支持的所有剩余 API 的访问权限，包括用于订阅事件的方法。必须声明读取/写入文档权限才能访问以下其他 API 成员：用于写入文档绑定区域的 Binding.setDataAsync 方法 TableBinding.addRowsAsync 方法，用于将行添加到绑定表格中。 TableBinding.addColumnsAsync 方法，用于将列添加到绑定表格中。 TableBinding.deleteAllDataValuesAsync 方法，用于删除绑定表格中的所有数据。 TableBinding 对象的 setFormatsAsync、clearFormatsAsync 和 setTableOptionsAsync 方法，用于设置绑定表格中的格式和选项。 CustomXmlNode、CustomXmlPart、CustomXmlParts 和 CustomXmlPrefixMappings 对象的所有成员用于订阅加载项支持的事件的所有方法，特别是 `addHandlerAsync`Binding、CustomXmlPart、Document、ProjectDocument 和 Settings 对象的和 `removeHandlerAsync` 方法。

另请参阅

Office 加载项的隐私和安全

通过

在加载项中请求获取 API 使用权限

权限模型

另请参阅

其他资源