Поделиться через

Запрос разрешений на использование 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, необходимым для чтения документа и управления привязками. В том числе разрешается использование следующих элементов:
  • Метод 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 Document.ReadAll.User То же, что и чтение документа. В дополнение к API, разрешенным ограниченными разрешениями на чтение документов , предоставляет следующий дополнительный доступ к данным документа.

  • Методы Document.getSelectedDataAsync и Document.getFileAsync получают доступ к коду OOXML документа (который кроме текста может содержать форматирование, ссылки, встроенную графику, комментарии, редакции и т. д.).
написание документа WriteDocument Document.Write.User Все и только API, которые записывают в документ или его свойства. Помимо API, разрешенного ограниченным разрешением, добавляет доступ к следующим членам API.
  • Метод Document.setSelectedDataAsync для записи данных в выделенную пользователем область документа.
чтение и запись документа ReadWriteDocument Document.ReadWrite.User Все api-интерфейсы application-specfic, в том числе те, которые подписываются на события. В дополнение к API, разрешенным разрешениями на чтение документа, чтение всех документов и запись документов , включает доступ ко всем остальным API, поддерживаемым надстройками, включая методы подписки на события. Чтобы получить доступ к дополнительным членам API, необходимо объявить разрешение на чтение и запись документа :

См. также