Запрос разрешений на использование API в надстройках

  • Статья

В этой статье описываются различные уровни разрешений, которые можно объявить в манифесте контентной надстройки или надстройки области задач, чтобы указать уровень доступа JavaScript API, необходимый вашей надстройке.

Примечание.

Сведения об уровнях разрешений для почтовых надстроек (Outlook) см. в статье Модель разрешений Outlook.

Модель разрешений

5-уровневая модель разрешений JavaScript API — это основа безопасности и конфиденциальности для пользователей контентных надстроек и надстроек области задач. На рис. 1 показаны пять уровней разрешений API, которые можно объявить в манифесте надстройки.

Рис. 1. Пятиуровневая модель разрешений для надстроек области задач и содержимого

Уровни разрешений для приложений области задач.

Эти разрешения указывают подмножество API, которое среда выполнения надстройки позволит использовать надстройке для содержимого или области задач при вставке пользователем, а затем активирует (доверяет) надстройку. Чтобы объявить уровень разрешений, необходимый вашей надстройке, укажите одно из текстовых значений разрешения в элементе Permissions манифеста надстройки. Следующий пример запрашивает разрешение WriteDocument, который разрешает использовать только методы записи в документ (но не методы чтения).

<Permissions>WriteDocument</Permissions>

Рекомендуется запрашивать разрешения по принципу минимальной привилегии. Другими словами, следует запрашивать разрешения для доступа только к минимальному подмножеству API, необходимому для правильной работы надстройки. Например, если надстройке требуется только считывать данные из документа пользователя, то максимальное разрешение, которое вам следует запросить, — ReadDocument.

В следующей таблице описывается подмножество API JavaScript, предоставляемое каждым уровнем разрешений.

Разрешение Включенное подмножество API
Ограниченный доступ Методы объекта Settings и метод Document.getActiveViewAsync. Это минимальный уровень разрешений, запрашиваемый контентной надстройкой или надстройкой области задач.
ReadDocument В дополнение к интерфейсам API, предоставляемым разрешением Restricted, добавляет доступ к элементам API, необходимым для чтения документа и управления привязками. В том числе разрешается использование следующих элементов:

  • Метод Document.getSelectedDataAsync для получения выбранного текста, HTML (только Word) или табличных данных, но не базовый код Open Office XML (OOXML), содержащий все данные в документе.

  • Метод Document.getFileAsync для получения всего текста документа, но не двоичной копии OOXML документа.

  • Метод Binding.getDataAsync для чтения связанных данных в документе.

  • Методы addFromNamedItemAsync, addFromPromptAsync, addFromSelectionAsync объекта Bindings для создания привязок в документе.

  • Методы getAllAsync, getByIdAsync и releaseByIdAsync объекта Bindings для доступа к привязкам документа и их удаления.

  • Метод Document.getFilePropertiesAsync для доступа к свойствам файла документа, таким как URL-адрес документа.

  • Метод Document.goToByIdAsync для перехода к именованным объектам и расположениям в документе.

  • Для надстроек области задач для Project — все методы "get" объекта ProjectDocument.

ReadAllDocument В дополнение к API, разрешенным разрешениями Restricted и ReadDocument , предоставляет следующий дополнительный доступ к данным документа.

  • Методы Document.getSelectedDataAsync и Document.getFileAsync получают доступ к коду OOXML документа (который кроме текста может содержать форматирование, ссылки, встроенную графику, комментарии, редакции и т. д.).
WriteDocument Помимо API, разрешенного ограниченным разрешением, добавляет доступ к следующим членам API.

  • Метод Document.setSelectedDataAsync для записи данных в выделенную пользователем область документа.
ReadWriteDocument В дополнение к интерфейсам API, предоставляемым разрешениям Restricted, ReadDocument, ReadAllDocument и WriteDocument, дает доступ ко всем оставшимся API, поддерживаемым контентными надстройками и надстройками области задач, в том числе методам для подписки на событий. Для доступа к этим дополнительные элементам API-интерфейса необходимо объявить разрешение ReadWriteDocument:

См. также