Solicitar permissões para uso da API em suplementos

Este artigo descreve os diferentes níveis de permissão que você pode declarar no manifesto do suplemento de conteúdo ou de painel de tarefas para especificar o nível de acesso da API JavaScript que o suplemento requer para seus recursos.

Observação

Para saber mais sobre os níveis de permissão para suplementos de email (Outlook), consulte Modelo de permissões do Outlook.

Modelo de permissões

Um modelo de permissões de acesso da API JavaScript com cinco níveis fornece a base para a privacidade e a segurança dos usuários dos suplementos de conteúdo e de painel de tarefas. A Figura 1 mostra os cinco níveis de permissões da API que você pode declarar no manifesto do suplemento.

Figura 1. O modelo de permissão de cinco níveis para suplementos de conteúdo e painel de tarefas

Essas permissões especificam o subconjunto da API que o runtime de suplemento permitirá que seu suplemento de conteúdo ou painel de tarefas use quando um usuário insere e, em seguida, ativa (confia) seu suplemento. Para declarar o nível de permissão que o suplemento do conteúdo ou do painel de tarefas requer, especifique um dos valores de texto da permissão no elemento Permissions do manifesto do suplemento. O exemplo a seguir solicita a permissão WriteDocument, que autorizará somente os métodos que podem gravar no documento, mas não lê-lo.

<Permissions>WriteDocument</Permissions>

Como prática recomendada, você deve solicitar permissões com base no princípio do mínimo privilégio. Ou seja, você deve solicitar permissão para acessar apenas o subconjunto mínimo da API que o suplemento requer para funcionar corretamente. Por exemplo, se o suplemento precisar apenas ler os dados no documento de um usuário para seus recursos, você não deve solicitar mais do que a permissão ReadDocument.

A tabela a seguir descreve o subconjunto da API JavaScript que é habilitado por cada nível de permissão.

Permissão	Subconjunto habilitado da API
Restrito	Os métodos do objeto Configurações e o método Document.getActiveViewAsync . Esse é o nível mínimo de permissão que pode ser solicitado por um suplemento de conteúdo ou painel de tarefas.
ReadDocument	Além da API permitida pela permissão Restrita , adiciona acesso aos membros da API necessários para ler o documento e gerenciar associações. Isso inclui o uso de: O método Document.getSelectedDataAsync para obter o texto selecionado, HTML (Word apenas) ou os dados tabulares, mas não o código do Open Office XML (OOXML) subjacente que contém todos os dados no documento. Método Document.getFileAsync para acessar todo o texto no documento, mas não a cópia binária OOXML subjacente do documento. Método Binding.getDataAsync para a leitura dos dados associados no documento. Métodos addFromNamedItemAsync, addFromPromptAsync, addFromSelectionAsync do objeto Bindings para criar associações no documento. Métodos getAllAsync, getByIdAsync e releaseByIdAsync do objeto Bindings para acessar e remover as associações no documento. Método Document.getFilePropertiesAsync para acessar as propriedades de arquivo do documento, como a URL do documento. Método Document.goToByIdAsync para navegar até os objetos nomeados e locais no documento. Para os suplementos do painel de tarefas do Project, todos os métodos "get" do objeto ProjectDocument.
ReadAllDocument	Além da API permitida pelas permissões Restricted e ReadDocument , permite o seguinte acesso adicional aos dados do documento. Os métodos Document.getSelectedDataAsync e Document.getFileAsync podem acessar o código OOXML subjacente do documento (que, além de texto, pode conter formatação, links, gráficos incorporados, comentários, revisões, etc.).
WriteDocument	Além da API permitida pela permissão Restrita , adiciona acesso aos seguintes membros da API. Método Document.setSelectedDataAsync para gravar na seleção do usuário no documento.
ReadWriteDocument	Além da API permitida pelas permissões Restricted, ReadDocument, ReadAllDocument e WriteDocument , inclui acesso a todas as API restantes com suporte por suplementos de conteúdo e painel de tarefas, incluindo métodos para assinar eventos. Você deve declarar a permissão ReadWriteDocument para acessar esses membros adicionais da API: Método Binding.setDataAsync para gravar nas regiões associadas do documento. Método TableBinding.addRowsAsync para adicionar linhas às tabelas associadas. Método TableBinding.addColumnsAsync para adicionar colunas às tabelas associadas. Método TableBinding.deleteAllDataValuesAsync para excluir todos os dados em uma tabela associada. Métodos setFormatsAsync, clearFormatsAsync e setTableOptionsAsync do objeto TableBinding para definir a formatação e as opções nas tabelas associadas. Todos os membros dos objetos CustomXmlNode, CustomXmlPart, CustomXmlParts e CustomXmlPrefixMappings. Todos os métodos para se inscrever em eventos compatíveis com suplementos de conteúdo e de painel de tarefas, especificamente os métodos addHandlerAsync e removeHandlerAsync dos objetos Binding, CustomXmlPart, Document, ProjectDocument e Settings.

Confira também

• Privacidade e segurança para Suplementos do Office