Запрос разрешений на использование API в надстройках
В этой статье описаны различные уровни разрешений, объявленные в манифесте надстройки, чтобы указать уровень доступа к API JavaScript, необходимый надстройке для ее функций.
Важно!
Эта статья относится только к надстройкам, отличным от Outlook. Сведения об уровнях разрешений для надстроек Outlook см. в статье Модель разрешений Outlook.
Модель разрешений
Пятиуровневая модель доступа к API JavaScript обеспечивает основу для конфиденциальности и безопасности для пользователей надстроек. На следующем рисунке показаны пять уровней разрешений 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, необходимому надстройке для правильной работы. Например, если надстройке требуется только чтение данных в документе пользователя для ее функций, следует запрашивать только разрешение на чтение документа .
В следующей таблице описаны подмножества api JavaScript Common и Application-api , которые включены на каждом уровне разрешений.
Каноническое имя разрешения | Только имя манифеста надстройки | Унифицированное имя манифеста | Включенное подмножество API для конкретных приложений | Включенное подмножество общих API |
---|---|---|---|---|
ограниченный | Restricted | Document.Restricted.User | Нет | Методы объекта Settings и метод Document.getActiveViewAsync. Это минимальный уровень разрешений, который может быть запрошен надстройкой. |
чтение документа | ReadDocument | Document.Read.User | Все и только API, которые считывают документ или его свойства. | Помимо API, разрешенного ограниченным разрешением, добавляет доступ к членам API, необходимым для чтения документа и управления привязками. В том числе разрешается использование следующих элементов:
|
чтение всего документа | ReadAllDocument | Document.ReadAll.User | То же, что и чтение документа. | В дополнение к API, разрешенным ограниченными разрешениями на чтение документов , предоставляет следующий дополнительный доступ к данным документа.
|
написание документа | WriteDocument | Document.Write.User | Все и только API, которые записывают в документ или его свойства. | Помимо API, разрешенного ограниченным разрешением, добавляет доступ к следующим членам API.
|
чтение и запись документа | ReadWriteDocument | Document.ReadWrite.User | Все api-интерфейсы application-specfic, в том числе те, которые подписываются на события. | В дополнение к API, разрешенным разрешениями на чтение документа, чтение всех документов и запись документов , включает доступ ко всем остальным API, поддерживаемым надстройками, включая методы подписки на события. Чтобы получить доступ к дополнительным членам API, необходимо объявить разрешение на чтение и запись документа :
|
См. также
Office Add-ins